GravityKit\GravityView\Settings\ViewStyles
Single source of truth for View styling tokens and their CSS emission.
Since: 3.0.0
Source: src/Settings/ViewStyles.php:37
Details
- Kind:
class - Namespace:
GravityKit\GravityView\Settings
Methods
| Method | Description |
|---|---|
tokens() | Returns every token, keyed by its canonical dot-namespaced id. |
sanitize() | Sanitises a single token value against its definition. |
sanitize_payload() | Sanitises an incoming template_settings payload before it is |
saved_values() | Returns saved (sanitised) values for every category, keyed by |
scoped_selector() | Returns the dual-selector wrap (outer-wrapper arm + container arm) |
prefers_contrast_css() | Returns the prefers-contrast: more re-statement block for a |
emit_css_declarations() | Returns the saved-token declarations for a View as a single |
sanitize_custom_css() | Sanitise customer-authored Custom CSS before emission. |
flush() | Clears static caches. Test/admin-render seam. |
Method Reference
tokens()
public static function tokens(): array
Returns every token, keyed by its canonical dot-namespaced id.
Each entry is normalised:
- id, category, group, label, desc, control, default, css_var
- options (when control = select)
- unit, min, max, step (when control = number)
The filtered result is memoised for the rest of the request, so
gk/gravityview/theme/tokens filters must be registered
before the first render that touches tokens (hook them by init).
Call flush() to invalidate the cache after a runtime registry
change.
Returns
array<string,— array>
Since: 3.0.0
Source: src/Settings/ViewStyles.php:81
sanitize()
public static function sanitize( string $token_id, $value ): string
Sanitises a single token value against its definition.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$token_id | string | Dot-namespaced token id. | |
$value | mixed | Raw value (string, numeric, etc.). |
Returns
string— Sanitised value, or empty string if invalid.
Since: 3.0.0
Source: src/Settings/ViewStyles.php:124
sanitize_payload()
public static function sanitize_payload( array $template_settings ): array
Sanitises an incoming template_settings payload before it is
persisted to post meta.
Recognised token buckets (see self::CATEGORIES) are cleaned in
place: each slug runs through sanitize() and invalid values are
dropped. Unrecognised bucket-shaped keys (string-keyed arrays under
a key that is not a registry category) are removed entirely so
unsanitised data is never persisted waiting for a future category
to make it live. Scalar settings and list-style arrays (e.g. the
multisort sort_field[] inputs) flow through unchanged, so this is
safe to compose with the existing save pipeline.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$template_settings | array | Raw template_settings array (e.g. from $_POST). |
Returns
array— Sanitised array with the design buckets cleaned.
Since: 3.0.0
Source: src/Settings/ViewStyles.php:252
saved_values()
public static function saved_values( array $template_settings, ?string $category=null ): array
Returns saved (sanitised) values for every category, keyed by
dot-namespaced id.
Defence-in-depth: even though sanitize_payload() runs on write,
read-time sanitisation guards against legacy data and pre-3.0
import paths that bypass save_postdata().
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$template_settings | array | Raw template_settings array. | |
$category | string | null | null | Optional category to scope the result. |
Returns
array<string,— string>
Since: 3.0.0
Source: src/Settings/ViewStyles.php:306
scoped_selector()
public static function scoped_selector( int $view_id ): string
Returns the dual-selector wrap (outer-wrapper arm + container arm)
for a View.
The [id^="gv-view-{ID}-"] arm catches outer wrappers (so widget
zones inherit) plus Edit Entry, and matches every embed of the View
on the page (-2, -3, ...). The .gv-container.gv-container-{ID}
arm catches every layout's container plus DIY single's
outer-as-container. Together they reach every layout's DOM at
specificity (0,2,0).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$view_id | int | The View's id. |
Returns
string— The selector string, ready to drop into a CSS rule.
Since: 3.0.0
Source: src/Settings/ViewStyles.php:347
prefers_contrast_css()
public static function prefers_contrast_css( int $view_id, array $overrides ): string
Returns the prefers-contrast: more re-statement block for a
View's overridden contrast-relevant tokens, or '' when no such token is overridden.
The stylesheet ships a boosted palette under
@media (prefers-contrast: more) at .gv-themed specificity
(0,1,0). A per-View token override lands at the dual selector's
(0,2,0) and would beat that boost, so each overridden
contrast-relevant custom property is re-stated here at the same
(0,2,0) specificity inside the media query. Tokens the customer
did not override stay covered by the stylesheet block, keeping the
inline payload proportional to what changed.
Boosted values follow the spec section "prefers-contrast: more":
9.4:1 / 8.7:1 / 9.2:1 / 7.6:1 against --gv-color-surface #fff.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$view_id | int | The View's id. | |
$overrides | array | Override map keyed by dot-namespaced token id (color.text_secondary) or by CSS custom property (--gv-color-text-secondary). |
Returns
string— CSS@mediarule, or empty string.
Since: 3.0.0
Source: src/Settings/ViewStyles.php:381
emit_css_declarations()
public static function emit_css_declarations( $view ): string
Returns the saved-token declarations for a View as a single
semicolon-joined string, without a wrapping selector. Lets callers compose tokens with their own declarations under one rule (e.g. Frontend's grid metrics) instead of emitting two separate rules with the same selector.
Override values equal to the token's registry default are skipped intentionally (except state-suffixed tokens): the stylesheet layer already supplies the default, so re-emitting it would only bloat the inline payload. The payload stays proportional to what the customer actually changed.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$view | \GV\View | The View whose overrides to emit. |
Returns
string— Declaration list, or empty string if nothing to emit. No trailing semicolon.
Since: 3.0.0
Source: src/Settings/ViewStyles.php:463
sanitize_custom_css()
public static function sanitize_custom_css( $css ): string
Sanitise customer-authored Custom CSS before emission.
Runs on the View's custom_css setting on the Themes
emission path, where it is wrapped in the View's per-id scope at
render time (see Frontend::get_view_custom_css_for_theme()).
Only a </style sequence can escape the inline <style> element,
so that sequence is neutralised case-insensitively, and < is
stripped when it begins a tag-like sequence (followed by a letter,
/, !, or ?). Bare < and all > are left intact: > is the
child combinator and both appear as comparison operators in
range-syntax media queries (@media (width > 600px)). @import
and JavaScript-protocol references are rejected because neither
belongs in View-scoped customisation.
Doesn't try to be a CSS parser; this is a low-effort filter for
the common-case dangerous patterns. The save layer additionally
gates persisting Custom CSS behind the unfiltered_html
capability, making this sanitiser defense in depth rather than the
only barrier.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$css | string | Raw customer input. |
Returns
string— Cleaned CSS, safe to inline. Empty when the input is non-string or strips to nothing.
Since: 3.0.0
Source: src/Settings/ViewStyles.php:777
flush()
public static function flush(): void
Clears static caches. Test/admin-render seam.
Returns
void
Since: 3.0.0
Source: src/Settings/ViewStyles.php:1048