et Product Search

E-Toolkit Product Search — User Guide

E-Toolkit Product Search replaces the standard WordPress search with an index designed for online stores. Customers can search for products by name, code, and other selected data, use live suggestions, and narrow the results with filters.

The plugin provides separate screens for Overview & Status, Settings, Synonyms, Result Rules, Statistics, Search Quality, Tools, and Guide. To get started, you only need to select the content to index and build the index. The remaining screens let you fine-tune the results, appearance, behavior, and reports later.

Getting started

The search field and the results list are two separate elements:

• Search field — the compact field placed in a header, menu, widget, or page. It provides live suggestions and sends the customer to the full results page after Enter is pressed.
• Results list — the content of the full results page. It displays the search bar, products, filters, active filters, sorting, and pagination.

Set them up in this order so the search field always has a valid destination.

1. Select searchable content and build the index

1. Open ET Product Search → Settings → Results content.
2. Leave Product enabled. Enable posts or pages only when they should also appear among product results.
3. Save the settings.
4. Open ET Product Search → Overview & Status and select Prepare data or Rebuild all data.
5. Wait until processing reaches 100%. Rebuild the data again whenever you change indexed fields, searchable taxonomies, or relevance priorities.

2. Create the full results page

Create and publish a normal WordPress page, for example “Search results”. Add exactly one results list using either method:

• Block editor: add the Product search results block from the E-Toolkit category.
• Shortcode or page builder: insert
  Wyniki: 0 • Strona: 1/1

  Dopasowanie Popularność Cena rosnąco Cena malejąco Nazwa A→Z Nazwa Z→A

  Wyczyść filtry

  Szukaj

  Cena

  –
  in a Shortcode element.

Do not place the compact search-field shortcode in place of the results list. The destination page must contain the listing block or

so it can read the etps_q query parameter and display matching products.

The listing block sidebar can override the number of products, column count, filter visibility, and active-filter bar for this one page. Leave the column value at 0 to use the global plugin settings.

3. Choose where Enter should send the customer

1. Open ET Product Search → Settings → Results appearance.
2. Select the Search field tab.
3. Under Open after pressing Enter, select the published results page created above.
4. Save the settings.

This selection is the default destination for every search-field block and

shortcode. If no results page is selected, the field falls back to the standard WordPress search instead of the dedicated listing.

For one exceptional field, you can override the destination directly:

The URL must point to a page containing the results listing.

4. Add the compact search field

Place the field where customers begin their search:

• Block editor or Site Editor: add the Product search field block from the E-Toolkit category.
• Header builder, widget, or shortcode element: insert
  Szukaj produktów…
  .

The field intentionally has no separate Search button. It displays suggestions while the customer types. Enter opens the selected results page; Enter on a highlighted suggestion opens that product or filter result.

In the block sidebar, Results page address overrides the global destination only for that block. Leave it empty in the normal setup. You can also change the placeholder globally under Results appearance → Search field, or for one shortcode with

.

5. Enable customer filters

1. Open Settings → Customer filters.
2. Select the product taxonomies that customers may use, such as categories, tags, brands, or WooCommerce attributes.
3. Add custom-field filters only when you know the exact meta key used by the theme or another plugin.
4. Save the settings and rebuild the search data so filter values and counts are available.
5. Open Settings → Results appearance → Filters to choose whether filters appear above or beside results and whether the active-filter bar is visible.

If a filter does not appear, confirm that it is enabled under Customer filters, indexed products actually have values for it, the listing block has Show product filters enabled, and the index was rebuilt after configuration.

6. Configure the listing and filter style

Open Settings → Results appearance and use the tabs in this order:

• Layout — grid or list, product columns, and the product template.
• Search field — Enter destination, placeholder, field size, and optional field-specific colors.
• Filters — filters above or beside results, active-filter bar, live search, default open/closed state, and filter order.
• Product cards — image, name, description, price, SKU, stock, and add-to-cart visibility.
• Style and preview — accent color, separate sections or one shared background, boxed or flat filters and cards, spacing density, radius, and exact dimensions.

Start with Separate sections, Boxed filters, and Standard density. Change one setting at a time and use the desktop/mobile preview before saving. The global appearance applies to both the block and shortcode listing; block options affect only the behavior exposed in that block's sidebar.

Operations that change the search configuration or data require an active license and an available connection to the E-Toolkit platform. This includes saving settings, rebuilding search data, clearing statistics, manually processing pending changes, and editing synonyms. If the platform is temporarily unavailable, the plugin safely stops the operation without saving partial changes.

How search works

The plugin automatically selects the most suitable search method:

• it searches product codes and identifiers very precisely,
• it searches ordinary phrases more broadly,
• it attempts to match similar words when a query contains a typo,
• it handles very short phrases cautiously to avoid irrelevant results.

While a customer types, the plugin can display grouped suggestions for products, matching categories, and brands below the field. The matching part of a product name is highlighted, and you can optionally show its price, SKU, and stock status. Customers can open a product immediately, select a category, or continue to the full results page. Suggestions support the Up and Down arrow keys, Enter, and Escape. On mobile devices, they use the available width of the field. Configure groups, details, and limits under Settings → Results appearance → Filters → Search as you type.

Ordering relevant results

Under Settings → Visibility and matching → Search fields, select which data is searchable and assign its importance. Priority is available only for enabled fields. By default, the product name and exact SKU or EAN matches receive the highest score, while the description has less influence. A product matching the query in its name will therefore usually appear above one that contains the phrase only in a long description.

Changing a priority does not hide products; it affects only their order. After saving priorities, rebuild the data on Overview & Status, because these values are stored in the search index.

Filtering results

You can allow customers to narrow results by:

• categories,
• tags,
• custom fields,
• price range,
• other elements enabled in the configuration.

Customer filters determines which data can be filtered. Results appearance → Filters determines where and how those filters are displayed. Both steps are required: choosing a category taxonomy does not by itself decide whether the controls appear above or beside the products.

Use Above results when the page should keep its full width for products. Use Beside results when customers need to see filter options while browsing a larger catalog. The active-filter bar shows each current choice and lets the customer remove it without reopening a filter group.

Customizing the appearance

Under Settings → Results list appearance → Style and preview, you can:

• choose collapsible filter groups or an always-visible list,
• keep lists expanded on desktop while automatically using space-saving accordions on mobile,
• use separate sections or a shared background with subtle dividers between search, filters, and results,
• display filters and cards in containers or use a flat layout,
• select compact, standard, or spacious density for filters and cards,
• set the placeholder color for empty search and filter fields,
• select a predefined border radius for fields, filters, and cards,
• hide the active filters bar; the Clear filters button then remains available in the main search bar.

Exact desktop and mobile dimensions and spacing are available in the collapsed implementation settings. The preview can switch between desktop and mobile and updates immediately; the storefront changes only after you save the settings. When filters are placed above the results, groups remain compact dropdowns so they do not occupy the entire page width.

Synonyms

Synonyms help when customers use different terms for the same item. For example, a search for “notebook” can lead to products described as “laptop”.

The Statistics screen shows a funnel from search and click through to a confirmed purchase. You can limit the report by date range, number of phrases, and store language. Searches with no results to improve is ordered by the number of unsuccessful searches. For each phrase, you can select the correct catalog term and save the redirect without leaving the screen.

The Recommendations section identifies repeated searches with no results, phrases with few results, frequent searches without clicks, and products that receive clicks but no confirmed purchases. Suggestions are calculated from aggregate counters and separately for each store language. The plugin never adds a synonym or changes product order automatically; you approve every change yourself.

Result rules

Use a rule when you intentionally want to change product order for an important phrase. Pin first preserves the specified order, Boost in results places products after pinned items, and Hide from results removes products from the results and filter counts. A product can belong to only one group; selecting it elsewhere automatically moves it. Rules apply to the exact normalized phrase and only when the standard relevance sorting is used. The product must still match the phrase and active filters.

Statistics show aggregate clicks, add-to-cart events, confirmed purchases, and attributed revenue. A purchase is recorded when a WooCommerce order enters the processing or completed status. A full refund or cancellation reverses it. Revenue includes attributed products after discounts and with tax, excluding shipping. Only an irreversible hash of the phrase and its language is stored with the order, so the report does not identify a customer or reveal the content of their search.

Search quality

Add an important customer phrase, find the expected products, and drag them into the correct order. Products do not need to occupy consecutive positions: the check verifies that all of them were found and that the first still ranks above the second. Run all checks performs the checks without recording customer statistics. A failed check can open Result Rules with the phrase already filled in so you can correct the order.

Where it is useful

• stores with large product catalogs,
• stores where the standard search returns insufficiently relevant results,
• stores whose customers frequently use abbreviations or make typing mistakes.

Integrations

The plugin can work:

• in place of the standard WordPress search,
• through its own form,
• as a source of results for the theme,
• with additional filters on the page.

Multilingual stores with ET Lingua

When ET Lingua is active, the search engine automatically separates products by the current page language. A customer browsing the Polish storefront sees Polish products, categories, brands, suggestions, and filter counts. English and German versions use their own data. You do not need to create or switch indexes manually.

Changing a product's language or connecting a new translation automatically queues the correct product for refresh. After ET Lingua is enabled for the first time, languages are added to the existing index automatically in small background batches. After a large translation import, run a full refresh from Overview & Status.

The Overview & Status screen shows the detected languages and the Indexes up to date message. During the initial language assignment, it shows Synchronizing languages. Search remains available while the operation finishes automatically in the background.

Search field in the header

Insert

in a header, menu, or widget. The field has no Search button: it displays products, categories, and brands while the customer types, and Enter opens the full results page. Under Settings → Results appearance → Search field, select the page containing

Wyniki: 0 • Strona: 1/1

Dopasowanie Popularność Cena rosnąco Cena malejąco Nazwa A→Z Nazwa Z→A

Wyczyść filtry

Szukaj

Cena

–

, a predefined field size, and — only when necessary — custom colors. The preview updates immediately.

The destination is resolved in this order:

1. Results page address set on an individual block or the shortcode's results_url parameter.
2. The page selected globally under Results appearance → Search field.
3. Standard WordPress search when neither destination is configured.

In most stores, configure the global page once and leave individual overrides empty.

Best practices

• index only data that genuinely helps customers find a product,
• refresh the index after changing settings,
• add only simple and unambiguous synonym pairs,
• test search with real customer queries.

Troubleshooting

• If results are outdated, refresh the index.
• If Enter opens the wrong page, check Results appearance → Search field → Open after pressing Enter, then remove any results_url override from the shortcode or block.
• If the correct page opens but no dedicated listing is visible, add the Product search results block or
  Wyniki: 0 • Strona: 1/1

  Dopasowanie Popularność Cena rosnąco Cena malejąco Nazwa A→Z Nazwa Z→A

  Wyczyść filtry

  Szukaj

  Cena

  –
  to that page.
• If filters are missing, enable their data under Customer filters, rebuild the index, and confirm that filters are not disabled in the listing block.
• If filters are in the wrong place, change Results appearance → Filters → Filter position; do not change the indexed taxonomies.
• If the style differs from the preview, save the settings, clear the page/cache plugin cache, and verify that the listing block is not overriding columns or filter visibility.
• If search returns no results, make sure the relevant content types are included in the index.
• If saving or rebuilding data is blocked, check the license status and the connection to the E-Toolkit platform.

E-Toolkit Product Search — Developer Guide

Public PHP functions

• et_product_search_search(string $phrase, array $args = []): array — searches for a phrase and returns ids, total, and max_pages.
• et_product_search_filtered(string $phrase, array $search_args = [], array $wp_query_args = []): array — combines indexed search with controlled WP_Query arguments.
• et_product_search_queue_reindex($post_ids, string $reason = 'manual'): void — queues one or more posts for reindexing.
• et_product_search_public_indexed_search(array $payload): array — runs the search used by the public frontend.

$result = et_product_search_search('red shoes', [
    'page'     => 1,
    'per_page' => 12,
]);

foreach ($result['ids'] ?? [] as $post_id) {
    echo esc_html(get_the_title((int) $post_id));
}

Hooks and filters

Public filters:

• et_product_search_wp_integration_enabled — enables or disables WP_Query integration.
• et_product_search_filtered_enabled — enables or disables filtered mode.
• et_product_search_filtered_candidates_limit — limits candidate count in filtered mode.
• et_product_search_filtered_wp_query_args — changes controlled WP_Query arguments.
• et_product_search_filtered_result — modifies the filtered-mode result.
• et_product_search_args_from_wp_query — changes arguments built from a query.
• et_product_search_results — filters the completed result set.
• et_product_search_should_index_post — decides whether a record is indexed.
• et_product_search_price_value — changes the price stored in the index.
• et_product_search_exclude_zero_price — excludes zero-price records.
• et_product_search_index_fields — extends indexed fields for a record.
• et_product_search_index_meta_keys — extends indexed meta keys.
• et_product_search_index_taxonomies — extends indexed taxonomies.
• et_product_search_index_post_parts — adds content fragments to the index.
• et_product_search_relevance_weights — changes text-source weights for one index document.
• et_product_search_document_fields — changes data stored in a search document.
• et_product_search_facet_taxonomies — selects taxonomies used by filters.
• et_product_search_facet_meta_keys — selects meta fields used by filters.
• et_product_search_facet_excluded_tax_term_ids — excludes selected terms from filters.
• et_product_search_facet_excluded_meta_values — excludes selected meta values from filters.
• et_product_search_card_templates — changes result-card template paths.
• et_product_search_card_data — changes data for one result card.
• et_product_search_public_response — changes the public API response.
• et_product_search_content_language — changes the language code used by search.

Public actions:

• et_product_search_queue_added(int $post_id, string $reason) — after a post is queued.
• et_product_search_queue_item_failed(int $post_id, string $error) — after a queue item fails.
• et_product_search_indexed(int $post_id, array $context) — after a document is stored successfully.
• et_product_search_card_media_before(int $product_id, array $data, array $context) — inside the media area of the built-in result card, before its image.
• et_product_search_enqueue_listing_assets — after the public listing assets are enqueued, for optional card extensions.

Integration examples

Controlling WP_Query and filtered mode

add_filter('et_product_search_wp_integration_enabled', function (bool $enabled, WP_Query $query) {
    unset($query);
    return !is_admin() && $enabled;
}, 10, 2);

add_filter('et_product_search_filtered_enabled', function ($enabled, string $phrase, array $search_args, array $wp_query_args) {
    unset($phrase, $search_args, $wp_query_args);
    return is_admin() ? false : $enabled;
}, 10, 4);

add_filter('et_product_search_filtered_candidates_limit', function (int $limit) {
    return 1000;
});

add_filter('et_product_search_filtered_wp_query_args', function (array $args, string $phrase, array $search_args, array $wp_query_args) {
    unset($phrase, $search_args, $wp_query_args);
    $args['posts_per_page'] = 20;
    return $args;
}, 10, 4);

add_filter('et_product_search_filtered_result', function (array $result, string $phrase, array $search_args, array $wp_args, WP_Query $query) {
    unset($phrase, $search_args, $wp_args, $query);
    $result['source'] = 'filtered';
    return $result;
}, 10, 5);

Changing query arguments and final results

add_filter('et_product_search_args_from_wp_query', function (array $args, WP_Query $query) {
    unset($query);
    $args['orderby'] = 'date';
    return $args;
}, 10, 2);

add_filter('et_product_search_results', function (array $results, string $phrase, array $args, WP_Query $query) {
    unset($phrase, $args, $query);
    return $results;
}, 10, 4);

Deciding what is indexed

add_filter('et_product_search_should_index_post', function (bool $should_index, int $post_id, array $context) {
    unset($context);
    return get_post_status($post_id) === 'publish' ? $should_index : false;
}, 10, 3);

Extending index data

add_filter('et_product_search_document_fields', function (array $fields, int $post_id, array $context) {
    unset($context);
    $fields['delivery_note'] = (string) get_post_meta($post_id, '_delivery_note', true);
    return $fields;
}, 10, 3);

add_filter('et_product_search_index_fields', function (array $fields, int $root_id, string $doc_type, array $context) {
    unset($root_id, $doc_type, $context);
    $fields['delivery_note'] = 'delivery_note';
    return $fields;
}, 10, 4);

add_filter('et_product_search_index_meta_keys', function (array $keys, int $root_id, string $doc_type, array $context) {
    unset($root_id, $doc_type, $context);
    $keys[] = '_delivery_note';
    return array_values(array_unique($keys));
}, 10, 4);

add_filter('et_product_search_index_taxonomies', function (array $taxonomies, int $root_id) {
    unset($root_id);
    $taxonomies[] = 'brand';
    return array_values(array_unique($taxonomies));
}, 10, 2);

add_filter('et_product_search_index_post_parts', function (array $parts, WP_Post $post, array $context) {
    unset($post, $context);
    $parts[] = 'Additional description fragment for the index.';
    return $parts;
}, 10, 3);

add_filter('et_product_search_relevance_weights', function (array $weights, int $root_id, string $doc_type, array $context) {
    unset($root_id, $doc_type, $context);
    $weights['title'] = 5;
    $weights['brand'] = 4;
    $weights['description'] = 1;
    return $weights;
}, 10, 4);

Weights are clamped to 1–5. Rebuild the index after changing them.

Result cards and public API

add_action('et_product_search_card_media_before', function (int $product_id) {
    echo '<span class="my-product-badge">' . esc_html(get_post_meta($product_id, '_badge', true)) . '</span>';
});

add_filter('et_product_search_card_data', function (array $data, int $post_id, WP_Post $post, array $context) {
    unset($post_id, $post, $context);
    $data['badge'] = 'New';
    return $data;
}, 10, 4);

add_filter('et_product_search_card_templates', function (array $paths, string $context) {
    unset($context);
    $paths[] = get_stylesheet_directory() . '/product-search/card.php';
    return $paths;
}, 10, 2);

add_filter('et_product_search_public_response', function (array $data, WP_REST_Request $request) {
    unset($request);
    $data['generated_by'] = 'ET Product Search';
    return $data;
}, 10, 2);

Facets and prices

add_filter('et_product_search_price_value', function ($price, int $post_id, int $root_id, string $doc_type, $product, array $context) {
    unset($post_id, $root_id, $doc_type, $product, $context);
    return (float) $price;
}, 10, 6);

add_filter('et_product_search_exclude_zero_price', function (int $exclude, int $post_id, array $context) {
    unset($post_id, $context);
    return $exclude;
}, 10, 3);

add_filter('et_product_search_facet_taxonomies', function (array $taxonomies, int $root_id) {
    unset($root_id);
    $taxonomies[] = 'product_cat';
    return $taxonomies;
}, 10, 2);

add_filter('et_product_search_facet_meta_keys', function (array $keys, int $root_id) {
    unset($root_id);
    $keys[] = '_brand';
    return $keys;
}, 10, 2);

add_filter('et_product_search_facet_excluded_tax_term_ids', function (array $ids, string $taxonomy, array $body, WP_REST_Request $request) {
    unset($taxonomy, $body, $request);
    return $ids;
}, 10, 4);

add_filter('et_product_search_facet_excluded_meta_values', function (array $values, string $meta_key, array $body, WP_REST_Request $request) {
    unset($meta_key, $body, $request);
    return $values;
}, 10, 4);

Search language

A custom PHP call can pass a language code:

$result = et_product_search_search('shirt', [
    'language' => 'en',
]);

Change the resolved language through a filter:

add_filter('et_product_search_content_language', function (string $resolved, string $requested): string {
    return $requested !== '' ? sanitize_key($requested) : $resolved;
}, 10, 2);

Rebuild the index after changing filters that affect document fields, taxonomies, metadata, or relevance weights.