Live Search & Autocomplete for OpenCart

Overview

Search as you type for OpenCart 4. Shoppers see products with image, price and stock, matching categories and brands, and can add a product to the cart without leaving the page. Typos are understood, synonyms you define are applied, and you see which searches found nothing.

• Dropdown under every search box of the store: product image, name with the typed text highlighted, price and special price in the shopper's currency and tax setting, stock status, Add button (or Choose options when the product has required options)
• Categories and brands that match the typed words, as links
• Typo tolerance: "samsnug" finds Samsung. Unknown words are matched to the closest words of your own catalogue, so it works for your brands and model names
• Synonyms and stop words you edit in the admin: equal words (tv, television), one-way rules (mobile => phone) and phrases (usb stick => flash drive)
• Recent searches (kept in the shopper's browser) and popular searches (curated from your analytics, off until you switch them on) when the box is focused and empty
• Phone overlay: a full-screen search with its own field, so the keyboard never covers the results
• Keyboard and screen readers: arrow keys, Enter, Escape, / to jump to the search box, combobox roles
• Results page: when OpenCart's normal search finds nothing, the page shows the corrected or synonym search, with a note and a link to the original
• Analytics: top searches with clicks, searches without results, and a one-click way to turn them into synonyms
• Fast: an own word index in your database (about 7 ms per search on 5,000 products, uncached), a result cache, debounced requests
• Safe: no external service, prepared queries, every shown value escaped, no personal data in the analytics
• No OCMOD and no core file changes: OpenCart events plus a daily cron task. Works with the default theme and attaches to any search field with a CSS selector
• OpenCart 4.1.0.x

Installation

Requirements: OpenCart 4.1.0.x, PHP 7.4 or newer with the mbstring extension (the intl extension improves accent handling but is not required).

1. In the OpenCart admin open Extensions > Installer, upload kv_live_search.ocmod.zip and click Install.
2. Open Extensions > Extensions, choose Modules, find Live Search & Autocomplete, click the green Install button, then the blue pencil.
3. Installing builds the index: small and medium catalogues are done at once, a very large one is finished by the daily task or by Rebuild index on the Index tab.
4. The extension is switched on after installing. Open the store, click into the search box and type.
5. Make sure the OpenCart cron job runs (php /path/to/cron.php every few minutes). The daily task of this extension indexes products added by imports and other extensions, and rebuilds the index after category or brand changes.

Uninstall: Extensions > Modules > Uninstall removes the settings, the index, the analytics, the events and the cron entry.

Update: upload the new zip in the Installer; settings, synonyms and analytics stay. Use Rebuild index after an update only when the changelog says so.

Configuration

Extensions > Modules > Live Search & Autocomplete.

Settings tab

• Start after (characters) and Wait after typing (ms): when suggestions start and how long the script waits for the next key before asking the server
• Products in the dropdown: 3 to 12
• Typo tolerance: matches unknown words to the closest known word (one typo for words of 4 to 7 letters, two for 8 or more; a swap of two letters counts as one)
• Fix the results page too: when OpenCart's own search finds nothing and the corrected or synonym search does, the results page shows that search with a note and a link to the original
• What the dropdown shows: image, price, stock status, add to cart button, matching categories, matching brands, recent searches, popular searches (off by default, see below)
• Attributes and option values: words from attribute values and option values (colour, size) find the product
• Product descriptions: adds the first words of the description with the lowest weight (rebuild the index after changing this)
• Cache results: seconds; cleared when a product is saved; 0 switches it off
• Search box selector: empty means every field named search. Enter a CSS selector (for example #header-search input) to attach the dropdown to a theme's own field. A field with data-kvls="off" is skipped
• Keep analytics (days): older rows are deleted by the daily task

Synonyms tab

One rule per line. tv, television makes the words equal. mobile => phone makes a search for mobile find phone products as well, but not the other way round. usb stick => flash drive rewrites a phrase. Lines starting with # are notes. Stop words are ignored when a search has other words.

Test a search runs the real search with your rules and shows the words it was matched with, the speed and the products with their scores.

Index tab

Shows how many products are indexed and when the last full build was. Rebuild index works in steps with a progress bar and empties the index first; the daily task rebuilds in place, so searches keep working. The page also shows the address of the cron task if you prefer calling it from outside OpenCart's cron.

What is indexed, with its weight: product codes (model, SKU and the other product codes) 12, name 10, brand 5, tags 4, categories including their parents 3, attribute and option values 2, description 1. A product code such as SM-G900F is found by its parts and as SMG900F.

Popular searches (curated)

Popular searches are shown to every shopper, so they are off until you switch them on. Look at the Top searches table in the Analytics tab first: Hide removes a search for good, Pin shows it first (while it finds products) without the visitor threshold.

A search reaches the list only when all of this is true:

• it was understood completely: every word matched a word of your catalogue (the list shows those catalogue words, never what the visitor typed);
• shoppers clicked a result for it and it was searched at least twice;
• it came from at least Popular: different visitors different visitors (default 5, 1 to 50). Visitors are counted with a keyed one-way hash of the address (only 10 characters are kept, deleted with the analytics); no address is stored;
• it passes the text filter (no web addresses, no long numbers, at most five words, no rude or spam words) and contains none of your Popular: blocked words.

Visitor address from: normally the connection address. Behind a proxy or CDN choose the header it sets, otherwise every visitor looks like one address and the rate limit (120 suggestion requests and 40 tracked searches a minute per address) applies to all of them together.

Usage

What shoppers see

Click into any search box and type. After the number of characters you set, the dropdown lists matching products. Use the arrow keys and Enter, or click. Add puts one item in the cart and refreshes the cart in the header; Choose options opens the product page. At the bottom, See all results opens the normal results page. Press / anywhere on the page to jump to the search box.

On phones the search opens as a full-screen panel with its own field.

Analytics

The Analytics tab shows the last 30 days: searches, clicks on results, different queries and searches without results; the top searches; and the searches that found nothing.

For a search without results type the word you sell for it, press Add, then save the page: a rule such as iphone case => case is added to the synonyms. Ignore hides a query. Only the query text and the number of searches and clicks are stored, no customer data. A search is counted once, after the shopper stops typing or presses Enter.

Catalogue changes

Saving a product in the admin updates its index rows at once. Products added by an import or another extension are picked up by the daily task. Changing a category or a brand marks the index as outdated; the daily task rebuilds it, or press Rebuild index.

FAQ

Does it need an external service?

No. The index lives in your database and the search runs on your server.

Does it work with my theme?

It attaches to every field named search, and to any field you name with a CSS selector. It takes its colours from the theme's Bootstrap variables.

Does it change the normal search results page?

Only when OpenCart's search finds nothing and ours finds the corrected or synonym search; the page then says so and links to the original.

Which languages?

Every language installed in the store has its own index. Accents are folded ("creme" finds "crème"). East Asian text is searched character by character.

How fast is it?

About 7 ms per uncached search on 5,000 products; building the index for 5,000 products takes about a second.

Customer group prices and taxes?

The dropdown uses the store's own price functions, so special prices, customer group prices, taxes and currencies match the product list.

Why is a product missing?

Disabled products, products not in the store, and products with a future available date are not shown. Run Rebuild index if you changed products directly in the database.

Does it use OCMOD?

No. Events and a cron task only.

Can someone fill the popular searches with spam?

No. A search is counted only when the suggestion endpoint answered it (signed token), the number per address is limited, and the list shows only catalogue words of searches that several different visitors made and clicked. You can also hide any entry or block words, and the list is off until you switch it on.

Does the search slow my store down when someone sends many requests?

The suggestion endpoint answers 120 requests a minute per address and then replies with HTTP 429; typo correction is capped (two unknown words per query, a short CPU budget, similar-length words only) and searches that found nothing are not cached.