Anatometal Gem Selector

Per-variation gemstone selection for Anatometal jewellery. The gem catalogue ships inside the plugin - 244 gem groups, 2,132 colours and 448 swatches - so there are no gem products to import and no media library entries.

WooCommerce v2.2.2
Download

Anatometal Gem Selector - WordPress Plugin

Per-variation gem selection for Anatometal jewellery, with the gem catalogue built into the plugin.

Gem availability is not a property of a product; it is a property of each *variation*, and a piece can have more than one gem position. The Hera Gem End offers 4 gem types at 1.5mm but 9 at 4mm. A Captive Gem Bead End offers 4 types in gold and 3 in stainless. A 2-Tiered Navel Curve takes three stones - two 4mm in position "Gem 1" and one 6mm in "Gem 2" - and the allowed types differ between stainless and titanium. Native WooCommerce variations cannot express this: folding gems into the variation matrix would need roughly 5,900 variations for the Hera alone, and about 36,700 product-gem combinations across the catalogue.

Installation Instructions

  • 1. Download: You've already downloaded the plugin! The file anatometal-gem-selector_2.2.1.zip contains the complete plugin, catalogue and swatches.
  • 2. Import the jewellery CSV first:
  • Gem products are not required and should not be imported
  • Bindings are keyed by variation SKU, so they survive re-imports
  • 3. Upload to WordPress:
  • Login to your WordPress admin dashboard
  • Navigate to Plugins → Add New
  • Click Upload Plugin at the top of the page
  • Choose the anatometal-gem-selector_2.2.1.zip file
  • Click Install Now
  • 4. Activate:
  • After installation, click Activate Plugin
  • 5. Set your pricing:
  • Go to WooCommerce → Gem Selector
  • Set the price multiplier - currency conversion and margin in one number - and an optional rounding rule
  • The settings screen shows worked examples

The catalogue ships with the plugin

Gems are not WooCommerce products. Modelling them as products meant importing 2,314 rows, carrying 244 hidden products in the admin and sideloading 480 images into the media library - all for stones that are never browsed or sold on their own.

Instead the plugin carries its own catalogue:

  • data/gems.json - 244 gem groups, 2,132 colours (265 KB)
  • data/variant-gems.json - variation SKU → gem positions (5,959 variations)
  • assets/gems/*.webp - 448 swatches (~0.9 MB)

Nothing to import, no media library entries, and the whole plugin is about 1.2 MB.

How customers choose a gem

Selection happens in a three-step panel - a drawer on desktop, a full-screen sheet on phones - rather than inline on the product page. Inline selects did not scale: the median variation hides 67 colours behind its pickers, the heaviest offers 50 gem types and 586 colours, and a five-position piece showed ten dropdowns at once.

  • Step 1 - Sandblasting. A real Anatometal product (gemsandblasting), charged *per gem*, so a three-stone piece pays it three times. Anatometal's data carries no per-gem sandblasting compatibility, so their warning that some gems cannot be sandblasted is shown, but no stone is greyed out.
  • Step 2 - Gemstone. A grid of swatches grouped under sticky type headings, with a search box. Names repeat across types - Aqua Blue exists as both Passion Topaz and Zirconia - so the grouping is what tells them apart.
  • Multi-gem pieces are asked whether one gemstone should be used for every placement, so a five-stone piece need not be chosen five times.

No gemstone is ever pre-selected. A default would ship the wrong stone - a customer seeing the blue gem in the photo receives cubic zirconia weeks later - so every position must be chosen explicitly. Add-to-cart is blocked client-side with a clear message when a position is unfilled, and the server re-validates regardless.

The panel is keyboard accessible: focus trap, Escape to close, focus restored on close, ARIA dialog semantics and a labelled progress list.

Pricing

The catalogue holds the supplier's list prices in USD. WooCommerce → Gem Selector sets a multiplier - currency conversion and margin in one number - plus an optional rounding rule (none, round up to the next 1 or 5, or nearest .95). Prices can therefore be adjusted without regenerating the plugin.

Cart behaviour

A chosen gem rides on the jewellery line item rather than becoming its own line: one cart row, one packing-slip row. The gem's price is added to the line (multiplied by the position count), and the gem SKUs are stored as order line-item meta so staff know which stones to pull. A machine-readable copy is kept in _am_gems for reporting.

Safety

  • Selections are re-validated server-side on add-to-cart: a posted gem SKU is resolved only within the groups that position allows.
  • Gems are priced from the bundled catalogue, never from the submitted form, so prices cannot be manipulated.
  • The price hook re-reads the variation's own price and sets the line total absolutely, so WooCommerce running calculate_totals more than once per request cannot charge for the gem twice.
  • A variation with no gem data simply shows no selector.

Regenerating the bundled data

python3 anatometal.py plugin # gems.json + swatches python3 anatometal.py build # variant-gems.json

Requirements

  • WordPress: 6.0 or higher
  • WooCommerce: 7.0 or higher
  • PHP: 7.4 or higher

License

GPLv2 or later.