Developer Reference

This page is for developers extending or customising the HawkSearch plugin. The same information is summarised on the plugin's HawkSearch → Developers page.

🚧

Don't edit the plugin's files

Updates replace the plugin's files. Make customisations with the filters on this page, in your theme's functions.php or a small custom plugin.

Where the Code Lives

Rapid UI is loaded on the results page; on every page once site search is on; and on any page with a recommendation widget or a tracked event (product views, cart, order confirmation).

Only the Client GUID and the public endpoints reach the browser. The API key is used only on the server.

Configuration Constants

Settings can be defined in wp-config.php, for example to keep the API key out of the database or to use different engines per environment. A constant overrides the value on the Settings page, and the field is shown as locked.

define( 'HAWKSEARCH_API_KEY', 'your-api-key' );
define( 'HAWKSEARCH_CLIENT_GUID', 'your-client-guid' );
define( 'HAWKSEARCH_ENGINE', 'yourengine' );
define( 'HAWKSEARCH_ENVIRONMENT', 'prod' ); // dev, test or prod

Shortcodes

Filters

Search and Rapid UI

The default field mappings are:

Indexing

Items are sent as field name: array of values, for example:

{
  "id": ["1600"],
  "title": ["Women's Dree Jacket"],
  "url": ["https://example.com/product/womens-dree-jacket/"],
  "image_url": ["https://example.com/wp-content/uploads/dree-jacket.jpg"],
  "type": ["item"],
  "tab": ["Products"],
  "price": [89],
  "category": ["Jackets"],
  "brand": ["Prana"]
}

Use Indexing → Preview an item to see exactly what is sent for any item.

Examples

Rename a Results Tab

add_filter( 'hawksearch_tab_value', function ( $tab, $post ) {
	return 'post' === $post->post_type ? 'Blog Posts' : $tab;
}, 10, 2 );

Run a reindex afterwards, and update the facet's Default Item Type in the Workbench if you rename the Products tab.

Add a Value to Every Item

The field must exist in HawkSearch (create it in the Workbench, or add it as a custom field and sync it on the Field Configuration page).

add_filter( 'hawksearch_index_item', function ( $item, $post ) {
	$item['region'] = array( get_post_meta( $post->ID, 'region', true ) ?: 'All' );
	return $item;
}, 10, 2 );

Using Smart Search

Use the unified Smart Search box everywhere the plugin places a search box. Smart Search must be enabled for your engine first.

add_filter( 'hawksearch_search_field_html', function () {
	return '<div class="hawksearch-search-box"><hawksearch-unified-search-field></hawksearch-unified-search-field></div>';
} );

For Smart Response, add <hawksearch-smart-response></hawksearch-smart-response> in a Custom HTML block above the results shortcode. See Available Enhancements.

Changing the Look of Results

Each Rapid UI component has a Handlebars template you can replace (Rapid UI Overrides). Copy the component's default markup from the component reference into a template tag on the page, change it, and point the component at it:

add_filter( 'hawksearch_rapid_ui_config', function ( $config ) {
	$config['components']['search-results-item']['template'] = 'my-result-item';
	return $config;
} );

add_action( 'wp_footer', function () {
	echo '<template id="my-result-item">';
	echo '<!-- your copy of the search-results-item markup -->';
	echo '</template>';
} );

To hide a component, set its template to an empty string.

Adding Custom Styles

add_filter( 'hawksearch_rapid_ui_config', function ( $config ) {
	$config['css']['customStyles'][] = '.search-results-list__item__title { font-weight: 700; }';
	return $config;
} );

Rapid UI components use shadow DOM, so styles passed this way reach inside them; normal theme CSS styles only the page around them.

Tracking Events in the Browser

With verbose logging on (HawkSearch → Tracking), every event is written to the browser console, prefixed [HawkSearch tracking]. The plugin calls Rapid UI's tracking service, so all events share Rapid UI's visitor and visit IDs:

To track a custom event, wait for Rapid UI and use the same service:

addEventListener( 'hawksearch:initialized', function () {
	HawkSearch.services.tracking.trackPageLoad( 5 ); // 5 = other page type
} );

See the Event Tracking API for event types.

Scheduled Tasks

With WP-CLI, wp cron event run hawksearch_scheduled_reindex starts the scheduled reindex immediately.

Stored Settings

The plugin stores its settings in WordPress options whose names start with hawksearch_, for example hawksearch_settings (connection), hawksearch_fields (Field Configuration), hawksearch_indexing, hawksearch_search, hawksearch_tracking and hawksearch_recommendations. Facets and recommendation widgets are stored in HawkSearch, not in WordPress.