Gem Attacher - WordPress Plugin

Attach a supplier's gemstone catalogue to your WooCommerce product variations. Shoppers choose a stone for every setting on a piece; the choice is priced from the catalogue, rides on the jewellery line item and reaches the packing slip as a gem SKU.

Installation Instructions

1. Download: You've already downloaded the plugin! The file gem-attacher_1.1.0.zip contains the complete plugin.

2. 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 gem-attacher_1.1.0.zip file
Click Install Now

3. Activate:
After installation, click Activate Plugin

4. Import a catalogue:
Go to WooCommerce -> Gem Attacher
Give the catalogue a slug and a name, choose your file and import

5. Set your pricing:
Set the multiplier that turns the supplier's list price into your retail price, and a rounding rule if you want one

6. Say what you carry:
Under the catalogue, open Gem groups this store carries and untick anything you do not stock

7. Attach settings to a product:
Edit a product, find the Gem Attacher panel, add a setting, tick the gem groups it offers, and choose which variations it applies to

Importing a catalogue

Two file formats are accepted, and the importer works out which it has been given by trying to parse it as JSON first.

Gem CSV

One row per stone. The header row names the columns, order does not matter, and unknown columns are ignored. Only group_handle, sku and name are required.

Column	Meaning
`group_handle`	Machine name for the group of stones this one belongs to. Positions allow groups by this handle.
`group_label`	Human name for the group, shown above the stones. Defaults to the handle.
`size`	Stone size, e.g. `2mm`. Shown beside the group label.
`material`	Free text, e.g. `Zirconia`, `Genuine`.
`round`	`1`, `yes` or `true` renders the stone as a circle rather than a rounded square.
`sku`	The SKU your staff pull from the shelf. Written to the order line meta.
`name`	Colour name, e.g. `London Blue`.
`price`	The supplier's list price, not your retail price.
`image`	A filename in this catalogue's uploads folder, or a full URL. Leave blank to use a colour swatch.
`colour`	`#rrggbb` for the swatch. Leave blank to derive one from the name.

A CSV imports stones only. It does not touch which variations offer which groups, so refreshing a supplier's prices never disturbs your own bindings.

That also means a CSV on its own does not put anything on your storefront: it gives you a catalogue to choose from, and you then attach settings to products in the Gem Attacher panel on the product screen.

Catalogue JSON

The full structure, including which variation SKU offers which groups:

{
  "catalogue": { "slug": "bvla", "name": "BVLA", "currency": "USD" },
  "groups": [
    {
      "handle": "2mm-faceted-brilliant-zirconia",
      "label": "Faceted Round Zirconia",
      "size": "2mm",
      "material": "Zirconia",
      "round": true,
      "options": [
        { "sku": "fb-2.0WH-cz", "name": "White", "price": "6.00", "image": "", "colour": "#f4f4f4" }
      ]
    }
  ],
  "bindings": {
    "YOUR-VARIATION-SKU": {
      "positions": [
        { "label": "Centre Stone", "count": 1, "groups": [ "2mm-faceted-brilliant-zirconia" ] }
      ],
      "extras": [
        { "key": "sandblast", "label": "Sandblasting", "sku": "gemsandblasting", "price": 4.0, "per_gem": true }
      ]
    }
  }
}

Re-importing with a slug that already exists replaces that catalogue's gems and bindings but keeps your multiplier and rounding rule, so a refreshed price list does not reset your retail pricing.

Attaching gems to your products

Two things decide what a shopper is offered, and both are yours to set.

What your store carries. Under WooCommerce -> Gem Attacher, each catalogue has a *Gem groups this store carries* list. Untick anything you do not stock. It stops being offered everywhere at once, and it cannot be bought even by someone posting its SKU directly. Re-importing that supplier's price list does not switch it back on.

What each setting offers. Edit a product and use the Gem Attacher panel. Add a setting for each place a stone goes, name it as the customer would recognise it ("Centre stone"), say how many stones it takes, and tick the gem groups it can accept. A 1.5mm cup ticks only the 1.5mm groups, so a 3mm stone is never offered for it.

Settings are described once for the product and applied to the variations you tick, because a piece almost always takes the same settings across its sizes and finishes. Untick a variation that does not take stones and it shows no picker at all.

Bindings are keyed by variation SKU, not by variation ID, so rebuilding a product's variations keeps its gem settings as long as the SKUs survive.

Notes

Gem images are yours to supply. Supplier photography is usually the supplier's copyright, so nothing is bundled. Put image files in wp-content/uploads/gem-attacher/<catalogue-slug>/ and name them in the image column, or leave it blank and let the colour swatch stand in.

Prices are never taken from the form. The browser posts a gem SKU and nothing else. The server looks that SKU up within the groups the setting actually allows, and prices it from the catalogue. A stone from a group this setting does not offer is rejected rather than silently priced.

Selection is required. A piece with bound settings cannot be added to the cart until every setting has a stone. Choosing a default would ship a customer the wrong gemstone weeks later.

Extras are catalogue data. An add-on such as sandblasting is defined per variation with its own SKU and price, and per_gem decides whether it is charged once or once per stone.

Several catalogues can be active at once. Each carries its own currency, multiplier and rounding rule, because two suppliers rarely quote alike.

The catalogue lives in its own tables. A product page resolves all its variations with a single indexed query rather than parsing the whole catalogue on every request.

Upgrading from Anatometal Gem Selector

Gem Attacher replaces it. On activation it reads that plugin's bundled catalogue and pricing settings, writes them in as a catalogue called *Anatometal*, and copies the gem swatches into your uploads folder so they outlive the old plugin folder. Sandblasting is converted into an ordinary per-stone extra.

The migration runs once and never writes back to the old plugin, so you can check a product page before deactivating it.

Requirements

WordPress: 5.0 or higher
WooCommerce: 7.0 or higher
PHP: 7.4 or higher

Support

Email Support: support@bloodweb.net

License

This plugin is licensed under GPLv2 or later. You are free to use, modify, and distribute this plugin.