Skip to content

For developers

Hooks and filters

On this page

Themes and custom code can change what the plugin indexes, how the search window draws its filters, who may change the settings, and when the search opens. Put the code in a child theme's functions.php or in a small plugin of your own.

Filters

searcio_index_allow_protected_meta

(bool $allow, string $meta_key, WP_Post $post)

A field you map from a custom field (meta: followed by the key) skips protected meta, the keys that begin with an underscore, so that a broad mapping cannot put internal data into a public search. Return true to index one of those keys anyway:

php
add_filter( 'searcio_index_allow_protected_meta', function ( $allow, $key ) {
    return '_my_public_field' === $key ? true : $allow;
}, 10, 2 );

searcio_storefront_facet_display

(string $display, string $field)

How the search window draws the values of a filter:

Value Draws
auto The default: colour swatches when every value has a colour, image swatches when every value has an image, tiles for sizes, shoe sizes and capacities, and a list with checkboxes otherwise.
list A list with checkboxes.
tiles Tiles.
color Colour swatches as soon as one value has a colour. A value without one is drawn as an empty ring.
image Image swatches, in the same way.
range A range with a minimum and a maximum.

Any other value counts as auto. The plugin already passes tiles for an attribute your swatches plugin shows as labels or buttons, and color or image for an attribute set up as colour or image swatches.

php
add_filter( 'searcio_storefront_facet_display', function ( $display, $field ) {
    return 'attr_fit' === $field ? 'tiles' : $display;
}, 10, 2 );

searcio_storefront_facet_colors

(array $colors, string $field, string $taxonomy)

The colour of each value of a filter, as value => hex colour, in the language of the page. The plugin fills it from your swatches plugin or theme for a WooCommerce attribute (see How products are sent). $taxonomy is empty for a field that is not an attribute. A value without a valid hex colour is dropped.

php
add_filter( 'searcio_storefront_facet_colors', function ( $colors, $field ) {
    if ( 'attr_color' === $field ) {
        $colors['Petrol'] = '#1f6f78';
    }

    return $colors;
}, 10, 2 );

searcio_storefront_facet_images

(array $images, string $field, string $taxonomy)

The image of each value of a filter, as value => image address, in the same way. An address that does not start with http or https is dropped. Together with searcio_storefront_facet_colors, this covers a swatches plugin or theme that the plugin does not read by itself.

searcio_storefront_is_preview

(bool $is_preview)

Whether the page is a page builder's editor. Searches from an editor count toward your plan but stay out of your search statistics. The plugin recognises the editors of Elementor, Divi, Beaver Builder, Oxygen, Bricks and WPBakery's frontend editor, and the Customizer. Return true for another editor:

php
add_filter( 'searcio_storefront_is_preview', function ( $is_preview ) {
    return $is_preview || isset( $_GET['my_builder_edit'] );
} );

searcio_sync_tick_budget

(int $budget)

How many seconds one step of a full sync may run, checked between batches. The default is 20. Lower it where PHP's time limit is shorter, so that a step ends before PHP stops it:

php
add_filter( 'searcio_sync_tick_budget', fn () => 10 );

woocommerce_product_is_visible

WooCommerce's own filter, (bool $visible, int $product_id), also applies while syncing when Only index published, visible products is on (see Product details). Return false to keep a product out of the search.

The value it receives says whether WooCommerce's search would list the product. Your callback runs where the sync runs, in WP-Cron, WP-CLI or a REST request, so is_search() is false and there is usually no logged-in user.

Actions

Action Fires Arguments
searcio/before_load On plugins_loaded, before the plugin starts. None
searcio/after_load On plugins_loaded, once the plugin has started. The plugin's instance

Open the search from your code

A link to #searcio, or any element with the class searcio-open, opens the search window (see Other ways to place it).

From JavaScript, dispatch the whsc:open event on window. detail.query is the text the search starts with, and can be left out:

js
window.dispatchEvent( new CustomEvent( 'whsc:open', { detail: { query: 'jacket' } } ) );

The event works on every page where the search is loaded: a page with a search block, widget or shortcode, and every page while the theme's search icon, the keyboard shortcut or the floating search button is on.

CSS custom properties

The search window and the search field read --whsc-* custom properties. Set them for the whole site on :root or body, or for one placement on its whsc-instance-* class. A value you set wins over the defaults. The block, the Elementor widget and the look editor set most of them for you; use the properties for what those do not cover.

Property Styles
--whsc-accent The accent colour of buttons, active tabs and links.
--whsc-accent-strong Text drawn in the accent colour.
--whsc-tab-text-active The text of the active tab. Defaults to --whsc-accent-strong.
--whsc-floating-bg The background of the floating search button. Defaults to the accent colour.
--whsc-floating-color The icon of the floating search button. White by default.
--whsc-floating-offset The distance of the floating search button from the bottom of the screen.
--whsc-stock-in-color The "In stock" line on product cards.
--whsc-stock-out-color The "Out of stock" line on product cards.
css
:root {
    --whsc-accent: #25735f;
}

Change the look through these properties rather than with rules for the window's own classes: the plugin's stylesheet keeps the window looking the same under any theme, so such a rule needs !important to take effect.

Permissions

The plugin's three permissions are given to Administrators. Each is checked by itself, so a role that may change settings also needs searcio_view to open the screen. To give them to another role, use a role editor plugin, or add them once, for example when your own plugin is activated, since a role keeps what is added to it:

php
$role = get_role( 'shop_manager' );

if ( $role ) {
    $role->add_cap( 'searcio_view' );
    $role->add_cap( 'searcio_run_sync' );
}

More