Extend Builder controls from PHP

Cliq Store Locator Pro defines standard Builder controls in PHP. The same authoritative registry supplies the React inspector and sanitizes submitted design models. Do not add a persisted setting only in JavaScript: hiding or normalizing a value in the browser is not a security boundary.

Register a standard control

Use cliqthemes_ui_builder_control_registry from a custom plugin or must-use plugin. The callback receives CliqThemes\UI\Controls\ControlRegistry.

use CliqThemes\UI\Controls\ControlRegistry;

add_filter(
    'cliqthemes_ui_builder_control_registry',
    function (ControlRegistry $registry): ControlRegistry {
        $registry->register([
            'id'       => 'widget.results.partner-label',
            'type'     => 'text',
            'scope'    => 'widget',
            'section'  => 'widget-results-display',
            'order'    => 950,
            'path'     => 'partnerLabel',
            'label'    => __('Partner label', 'my-store-extension'),
            'default'  => '',
            'sanitize' => 'text',
            'editions' => ['pro'],
            'conditions' => [
                'path'     => 'widgetType',
                'operator' => 'equals',
                'value'    => 'results',
            ],
        ]);

        return $registry;
    }
);

After registration, the Store List inspector renders the field, saves its value under widgetSettings.partnerLabel, and strips unsafe markup before persistence. Your rendering extension is still responsible for consuming that value.

Choose the correct scope

Scope	Saved under	Typical use
container	model.container	Overall design size or appearance
form-settings	model.settings	Search/lead/registration form behavior
row	row.settings	Row layout behavior
col	Column or column.settings	Grid span and column behavior
item	The selected element/field	Store Card content or Search Form field
widget	item.widgetSettings	Map, Store List, filters, and other Layout widgets

Widget IDs must begin with widget.{widget-type}.. For example, widget.map.partner-layer applies only to an item whose widget is map. This prevents a setting with the same path from being sanitized by another widget’s schema.

Standard control types

The generic inspector supports:

• bool, text, textarea, select, and combobox;
• segmented, range, unit, color, font, and icon;
• checkbox-list and choices-editor;
• notice and merge-tag-insert.

Useful schema properties include label, help, placeholder, default, options, optionsPath, min, max, step, units, conditions, and editions.

optionsPath reads a server-supplied option collection from the Builder context. Use it for design lists or registered Store Locator option sets. Do not send arbitrary PHP callable names to the browser.

Conditions

Conditions are data, not JavaScript callbacks:

'conditions' => [
    'all' => [
        [
            'path'     => 'widgetType',
            'operator' => 'equals',
            'value'    => 'results',
        ],
        [
            'path'     => 'values.showLoadMore',
            'operator' => 'truthy',
        ],
    ],
],

Supported compositions include all, any, and not. Comparisons include equals, not_equals, in, not_in, truthy, falsy, greater_than, and less_than. Use values already present in the control context; conditions do not execute PHP or JavaScript.

Sanitizers

Every persisted control must declare a sanitizer:

Sanitizer	Accepted value
boolean	Boolean-like input
integer, number	Numeric input, clamped by min and max
key	Letters, numbers, underscore, and hyphen
keys	A unique non-empty array of sanitized keys
text, textarea	Plain text with tags removed
url	Relative URL or HTTP/HTTPS URL
css_length	Safe CSS length such as 600px, 40rem, or 100vh
css_color	Valid supported color/variable syntax
choices	Sanitized {value, label} option rows

If options are declared, a submitted value outside those options falls back to default.

Register a custom visual control

Use a custom control only when the interaction cannot be represented by the standard types—for example the Map theme gallery, marker picker, or cluster preview. Register the PHP definition as usual, using a unique type, then register its React renderer through:

window.cliqUI.registerControlType( 'my-visual-picker', MyVisualPicker );

The component receives the control definition, current value, onChange, onChangePath, and the current context. The PHP control must still declare its path, default, conditions, edition, and sanitizer. Custom rendering never bypasses server validation.

Bootstrap-only configuration

cliqthemes_ui_builder_controls filters the complete Builder bootstrap object, including option sets and display configuration. Use it to extend read-only context data. Register persisted controls with cliqthemes_ui_builder_control_registry so editor rendering and server sanitization cannot diverge.