Developer documentation


A WordPress plugin for WooCommerce products AJAX Search with filters.

SpeedSearch themes

To add a custom SpeedSearch theme, add it to your WP theme under speedsearch/themes/ directory.

You can see an example of the theme in samples/example-theme/ dir. So its path should be wp-content/themes/my-theme/saffy/themes/example-theme/ (and don’t forget to run npm install and npm run build for it).

And then select a theme under SpeedSearch settings in “Themes” tab (you don’t have this tab if you have no themes installed).

Shortcodes #

Syntax Description
[speedsearch html_id="saffy-main-block" hide_search="0"] Main block (contains all below parts).


hide_search – Whether to hide the search bar. Default: 0.

[speedsearch_search small_size="1" align="center" search_in_results="0"] Search box.


small_size – Whether search bar size is small or not. Default: 0.
align – Alignment. Default: right.
search_in_results – Whether to search in results. Default: 0.

[speedsearch_part_categories html_id="saffy-categories"] Categories.
[speedsearch_part_filters] Filters. Contains Toggles (because toggles are filters).
[speedsearch_part_tags] Tags.
[speedsearch_part_posts] Posts.
[speedsearch_part_filter name="price"] Single “Price” filter.
[speedsearch_part_active_filters] Active filters block.
[speedsearch_part_toggle name="reviews_allowed"] Single toggle.

To get toggle name, hover over it in admin menu and wait for 2 seconds (“title” attribute). For example, the toggle “Reviews Allowed” will be “reviews_allowed”.

Important: If the toggle is not active (in general or at least for one filter), it will not be shown.

[speedsearch_recently_viewed_products show_limit="3"] List recently viewed products. “show_limit” is the maximum amount of recently viewed products to show. Can’t be more than 10.
  • Each shortcode supports html_id attribute, which adds ID to HTML the element.

Env variables #

Variable Description
SAFFY_SERVER BE server address with protocol.
SAFFY_LICENSE SpeedSearch license key.
SAFFY_ORIGIN Origin server for BE requests.

HTML Classes #

Syntax Description
saffy-hide-when-no-recently-viewed-products Hides the elem when no recently viewed products.

REST API Endpoints #

sy | Syntax | Method | Description | |————————————-|——–|———————————————————————————–| | products-hash | GET | The list of products with their hash. | | saffy-settings | GET | Webhooks secret. | | product-hash-generation-data/6360 | GET | For debugging, returns the array used right before the product hash generation. | | saffy-term-products/462 | GET | For debugging, returns the list of products that belong to the specified term ID. | | saffy-backend-fix-counts | GET | For BE fix, returns the list of different types of counts. |

Fake params #

Syntax Description
fake_posts_counter Specify the fake posts counter (used for debugging and demoing of counter for more than 100k of results).

Notes #

  • html_id is a global attribute that can be added to any shortcode. Adds the specified ID to the HTML element. Should be unique.

Plugin templates overwriting #

  • To overwrite template files from within your theme, put them to /saffy/ directory in your theme directory. For example, /themes/my-theme-directory/saffy/parts/filters/sort-by.php will be given priority over the /plugins/saffy/src/templates/parts/filters/sort-by.php.

Meta #

Type Key Description
Term saffy-swatch-image Term image swatch of thumbnail size with two keys: url and alt.
Post saffy-product-hash Product hash (for sync on hash diff with the backend).

Constants #

Constant Description

Action #

Action Description

Filters #

Filter Description Params
saffy_post_field_content_types Posts block field content types. $types
saffy_opportunity_to_insert_custom_html_for_ids A place where html for IDs could be inserted (this case, no raw posts data will be returned). Used for search and recently_viewed_products requests. Used for theme integrations. $data$posts_ids$endpoint
saffy_before_public_settings_ajax_output Before public settings AJAX output. $data

JS #

Events #

Event Target Description
saffy_after_filter_window_close let filter After filter window close.
saffy_pre_filter_reset let filter Before filter reset (on Reset button click).
saffy_after_posts_updated document After the posts are updated (fires only if at least one post was retrieved from the backend).
saffy_after_filters_init document After filters are initialized.
saffy_after_categories_init document After categories init.
saffy_after_tags_init document After tags are initialized.
saffy_after_category_change document After category changed. 'categorySlug', 'isSelected', 'isAllCategoriesActive'
saffy_after_tag_change document After tag changed. 'tagID', 'isSelected'
saffy_after_attribute_change document After attribute field changed. 'attributeSlug', 'value', 'isSelected', 'isSingleSelect'
saffy_admin_after_themes_init document Admin panel. After themes are initialized.
saffy_after_date_change document After price changed (but not saved yet).
saffy_after_price_change document After price changed (but not saved yet). newMinPricenewMaxPrice
saffy_admin_after_swatch_images_added document Admin panel. After swatch images were added to the field. field
saffy_before_posts_request document After request params for search request are retrieved but before the request is done. requestParams
saffy_admin_after_select_table_row_click table Admin panel. After select table row click.
saffy_after_wc_breadcrumbs_updated document After WC breadcrumbs were updated.
saffy_after_attribute_terms_filtering_finished document After attribute terms filtering (first/second layer) finished.
saffyLoaded document Equivalent to “DOMContentLoaded” but fires only when JSON cache settings are retrieved.
saffy_autocomplete_window_rendering_finished document When autocomplete window rendering finished.
saffy_after_first_layer_filtering_finished document When first layer filtering finished (any of the times).
saffy_after_second_layer_filtering_finished document When second layer filtering finished (any of the times).
saffy_autocomplete_entity_selected document After autocomplete entity has been selected (it’s data is available via saffy.autocompletePreviouslyActivatedFilter variable).
saffy_filters_retrieved document After filters data is retrieved.
saffy_initial_init document Initial pre-init. When the most of routine are initialized but all data not necessary finished the loading.

Dev Admin Panel Methods #

Event Description
saffy.resetToFreshState() Resets the plugin to the fresh state. And de-activates the license also.
saffy.activateLicense() Activates the license.

Libs #

JS #

Name Description
SortableJS Sorting of filters. Admin menu only.
Pickr Color picker. Admin menu only.
noUiSlider Price range slider.
Flatpickr Date range select.
intro.js Plugin introduction tour.

Other Notes #

  • There are 3 levels on filtering:
Level Description
0 When you select “how to treat empty categories and attributes” (saffy-setting-how-to-treat-empty option) or “hide unavailable tags” setting.
1 When you select category. Its behaviour is also affected by level 0 setting to a full degree.
2 When you select filters (tags, toggles, attributes) inside the category. Its behaviour is also affected by level 0 setting – but it doesn’t hide, just disables (even if the level 0 option is set to “hide”), and doesn’t work when it’s set to “show”.

Dev Notes / TODO #

  • Be aware of possible filters’ data-name collisions! Use ‘attribute’ or ‘pa_’ prefixes for attributes.