Description
Your catalog is searchable by name and CAS number, which works right up until
the buyer knows neither. They know the structure. This lets them draw it.
A shopper clicks a button, draws a molecule, and gets back the products in your
catalog that match — either the same substance, or every product containing what
they drew. Draw a benzene ring and you get everything with a benzene ring in it.
Results are rendered with your theme’s own product template, so they look
like the rest of your shop: your prices, your badges, your add-to-cart buttons.
Who it is for
Any WooCommerce store that sells by structure: chemical suppliers and
distributors, reagent and laboratory supply shops, building-block and
screening-compound vendors, custom synthesis and research chemical sellers,
fine chemical and pharmaceutical intermediate catalogs. If your buyers think
in molecules, SMILES strings and CAS numbers, this gives them a search box
that speaks their language: chemical structure search, substructure search,
SMILES search, CAS number lookup and plain product name search, all in one
drawer on your product pages.
What it does
- Exact structure search. Finds the same molecule however it was drawn or
written. Caffeine drawn three different ways finds caffeine all three times —
and does not find theobromine, which is one methyl group away. - Substructure search. Finds every product containing the drawn fragment.
- Similarity search. A checkbox that also returns the products closest to
what was drawn, each scored, so a buyer who cannot find the exact compound
is shown the nearest thing you do stock. - A drawing editor built into your storefront (JSME, by Peter Ertl and
Bruno Bienfait). - Chemistry fields on every product: SMILES, CAS number, molecular formula,
molecular weight — shown on the product page in your theme’s own styling. - Structure images drawn automatically and saved as files.
- CSV import that accepts the column names your supplier already uses.
- A block and a shortcode, so search goes wherever you want it.
It does not slow your site down
The chemistry toolkit is large — around 10 MB between the structure editor and
the chemistry engine — and none of it is downloaded until a shopper actually
clicks to open the drawing editor. A page with the search widget on it costs
about 11 KB of JavaScript. A page without one costs nothing at all: no scripts,
no styles, no requests.
Searching happens in the shopper’s browser against a small index file, so it
puts no load on your database however many people are searching at once.
Accurate chemistry
Matching is done by RDKit, the standard open-source
cheminformatics toolkit, compiled to WebAssembly. The same code canonicalises
your catalog when you build the index and canonicalises what the shopper draws,
so the two are always comparable. Aromaticity, tautomers, salts, stereochemistry
and isotopes are handled by RDKit rather than by string matching — deuterated
solvents stay distinct from their ordinary counterparts.
Pro version
Everything described on this page is in this plugin and stays free. A separate
Pro add-on, sold by Branching Software, adds tools for keeping a catalog’s
structures complete and for seeing what shoppers want:
- CAS to structure enrichment — products with a CAS number and no structure
are looked up on PubChem in the background, and you approve each suggestion
before it is saved. - SDF import — upload a supplier’s SDF, map its fields to SKU or CAS,
preview exactly what will change, then import. - Search demand report — the full report over the searches this plugin
already records: every structure and query, filters, a daily trend, CSV
export and a retention setting.
The add-on installs as a second plugin and adds its tabs to this plugin’s
screen. See https://branchingsoftware.com/chemical-structure-search/.
Third-party libraries
This plugin bundles two open-source libraries, both redistributed under their own
terms with their licence files included:
- RDKit (
assets/vendor/rdkit), the cheminformatics toolkit that performs
all structure matching, compiled to WebAssembly.
BSD 3-Clause. https://www.rdkit.org/ — source:
https://github.com/rdkit/rdkit-js - JSME Molecule Editor (
assets/vendor/jsme), the structure drawing editor,
by Peter Ertl and Bruno Bienfait.
BSD 3-Clause. https://jsme-editor.github.io/ — source:
https://github.com/jsme-editor/jsme-editor.github.io
Neither library contacts any external service. Both run entirely in the
visitor’s browser, and this plugin makes no outbound requests of its own.
Screenshots
Blocks
This plugin provides 1 block.
- Chemical Structure Search Let shoppers draw a chemical structure and find the products that match it.
Installation
- Install and activate the plugin. WooCommerce 9.0 or newer must be active.
- Add SMILES structures to your products — on each product’s Chemistry tab, or in bulk under WooCommerce Structure Search Import.
- Go to WooCommerce Structure Search and click Build index. Leave the tab open while it runs; the chemistry runs in your browser.
- Add the Chemical Structure Search block to a page, or use the shortcode [chemical_structure_search].
Rebuild the index after changing product structures. The admin screen tells you when it has drifted.
Starting open
By default the page shows a button and the drawing editor opens when a shopper
clicks it, so nothing chemistry-sized downloads until they do. For a page that
exists for structure search, turn on the block’s Start open toggle, or use
[chemical_structure_search open=”yes”]: the editor is shown immediately with
no button. The button and heading text are the block’s Button text and
Heading fields, or button="..." and heading="..." on the shortcode.
Typing instead of drawing
The drawer also has one typed box. A SMILES or InChI is matched by chemistry, exactly as a drawing would be, and appears in the editor so it can be adjusted. A CAS number, a catalog number or a product name is looked up in the store’s own product data, which means it also finds products that have a CAS number but no structure yet, and works before the index has been built.
Sizing and layout
The drawing editor fills whatever width it is given. In the block editor, use
the block’s alignment control to make it wide or full width; the shortcode
takes width="wide" or width="full" for the same thing. With room to spare,
the search controls move into a column beside the editor.
Results are laid out in a grid of your theme’s product cards. The block’s Results layout panel, or these shortcode attributes, control it:
columns="3"— a fixed number of columns, 1 to 6. The default,0, fits as many as the space allows. Small screens always get fewer.layout="list"— one product per row, thumbnail on the left.limit="200"— the most substructure matches one search will find. Exact matches are always found. Results arrive forty at a time behind a “Load more” button however high this is set, so raising it costs the store nothing per request.
For example: [chemical_structure_search width="wide" columns="4"].
Colours
WooCommerce Structure Search Appearance sets the accent colour, panel background, text colour and corner radius, with a live preview and your theme’s palette in the picker. Button text switches between white and dark on its own so a pale accent stays legible. The block has its own accent setting for one search that should differ, and the shortcode takes accent=”#b4532a”.
Beyond that, every colour and size in the drawer is a CSS custom property a
theme can override on .chemsearch.
FAQ
-
What is SMILES?
-
A line notation for chemical structures —
CN1C=NC2=C1C(=O)N(C(=O)N2C)Cis
caffeine. Most catalog systems and suppliers can export it, and PubChem lists it
for any compound. It is the one field structure search actually needs. -
Do I have to get the SMILES exactly right?
-
No. Any valid way of writing a structure works, because RDKit converts every one
to a single canonical form before comparing. You do not have to match how anyone
else wrote it. -
Why do I have to build an index?
-
So that searching is instant and costs your server nothing. The index is one
file, built once, that shoppers download and search against in their own browser. -
Why does the index build happen in my browser?
-
The chemistry toolkit is WebAssembly. Running it needs a browser or a Node
process, and a WordPress host has neither. Building it in your browser also means
your catalog is canonicalised by exactly the same code that will later match
against it — which is what makes exact search reliable. -
How big a catalog does this handle?
-
Comfortably into the low thousands of products. Beyond about 10 000 the index
file becomes large enough that it should be split into parts, which this version
does not do yet. -
Will it work with my theme?
-
Results are rendered by your theme’s own product template, so if your shop page
looks right, results will too. -
Does it send my catalog anywhere?
-
No. Everything runs on your site and in your shoppers’ browsers. The plugin
makes no outbound requests at all. -
Which products end up in the public index?
-
Only products a shopper could reach by browsing: published, not
password-protected, and with catalog visibility “Shop and search results”.
Hidden, draft, private and password-protected products are left out of the
index file and are never rendered by the results endpoint, whatever a request
asks for. Changing a product’s visibility marks the index as needing a rebuild. -
What does the search log store?
-
Each search stores what was asked — the drawn or typed structure as canonical
SMILES, or the CAS number, catalog number or name that was typed — and how
many products matched, to the hour, and nothing about who searched: no IP
address, account, cookie or browser details. The same visitor repeating the
same search within an hour is recorded once. Rows are deleted after the
retention period (default 90 days), the table is capped in size, and a
suggested privacy-policy paragraph is added under Settings Privacy Policy
Guide.The Index tab shows the last 30 days: how many searches, by structure or by
name, how many found nothing, and the five most-wanted things the catalog
does not have. -
Can someone overload the search endpoint?
-
Each client gets a budget of thirty searches at once and thirty a minute after
that, and one request renders at most forty product cards. A search that
matches more sends the rest a page at a time behind a “Load more” button, so
no single request can ask the store to build more than forty cards however
many products matched. Both are filterable (bscs_results_rate_limit,
bscs_max_results) for stores that need more. -
What happens when I uninstall?
-
Deleting the plugin removes its settings, the search log table, its scheduled
tasks and the index files it wrote to the uploads folder. The chemistry
fields on your products (SMILES, CAS number, formula, weight) are left in
place, because they are your catalog data and you may install the plugin
again or export them. -
How does the CSV import work?
-
Each row is matched to a product by SKU. A matching product is updated; a
row with a new SKU creates a simple product. The file only changes the
columns it carries: a SKU and SMILES file refreshes structures and leaves
CAS numbers, formulas, weights, names and prices as they were. The column
names your supplier uses are accepted (CAS No, Catalog Number, Mol Weight
and so on). After an import the admin screen asks for an index rebuild,
since searching reads the index, not the products. -
What about variable products?
-
Structures are set on the parent product, and the parent is what search returns.
Per-variation structures are not supported.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Branching Software Chemical Structure Search for WooCommerce” is open source software. The following people have contributed to this plugin.
Contributors
Translate “Branching Software Chemical Structure Search for WooCommerce” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.0.0
- First public release on wordpress.org.
- Exact, substructure and similarity search, matched by RDKit in the
shopper’s browser against an index built in the admin. Nothing is sent
anywhere. - A drawing editor (JSME) in a drawer that opens on click or, with the
block’s Start open toggle oropen="yes", is shown immediately. - One typed box: SMILES and InChI go to the chemistry engine; CAS numbers,
catalog numbers and product names are looked up in your own product data. - Results rendered through your theme’s product loop, in a grid or list,
1 to 6 columns, wide or full width. - Chemistry fields on every product (SMILES, CAS, formula, weight), a
Chemistry tab on the product page, and a structure image per product. - CSV import that accepts supplier column names.
- Appearance tab: accent, panel and text colours and corner radius, with your
theme’s palette in the picker. The block and shortcode take anaccent. - Search activity for the last 30 days on the admin screen, recorded with
no personal data and purged after the retention period. - Rate-limited public endpoints that only ever return products a shopper
could reach by browsing.