# Set up Scruff's metafields

Chapter 7 of the Scruff user guide.

Scruff's features read three kinds of data, none of which needs an app:

* **Metafields** in the `custom` namespace (the one Shopify admin uses when you create a definition): seven on products and one on variants.
* **Theme settings** in **Theme settings › Pet profile**, **Sizing**, **Personalisation** and **Feeding and autoship**, and the blocks' own settings: your size names and weight ranges, your default size table, your breeds, threads and tag fonts.
* **Product option names and values**, for sizes, tag shapes and finishes, and strap colours, and a **product tag**, `personalise`, for the products you engrave or embroider.

Scruff doesn't use metaobjects, so there is nothing to set up under **Content › Metaobjects**. You only need the data for the features you use, and nothing breaks while you fill it in: each part of a feature shows only when it has data, and the theme settings give every product sensible defaults.

In Shopify admin, metafield definitions live under **Settings › Custom data** (called **Metafields and metaobjects** in newer versions of the admin).

## The metafields Scruff reads

Keys are exact and case-sensitive. The name is yours to choose: it's what you see when you edit a product.

| Namespace and key | Owner | Type in admin | Example | What reads it |
| --- | --- | --- | --- | --- |
| `custom.size_weights` | Product | **Multi-line text** (`multi_line_text_field`) | `XS \| 0–4 kg` (one size per line) | The fit badges and the fit row: this product's weight range per size, in place of **Weight range per size** (chapter 8) |
| `custom.species` | Product | **Single line text**, **List of values** (`list.single_line_text_field`) | Dog | Who the product is for. The Dogs / Cats / All filter, and no fit badge for the other species (chapter 8). Also the **Species** filter (chapter 13). |
| `custom.size_table` | Product | **Multi-line text** | `Size \| Neck cm \| Chest cm \| Weight kg`, then one size per line | The size guide's table and the size tiles' small lines, in place of **Default size table** (chapter 9) |
| `custom.feeding_guide` | Product | **Multi-line text** | `10 \| 165` (one weight per line) | The feeding calculator: the maker's grams per day by the pet's weight (chapter 11) |
| `custom.net_grams` | **Variant** | **Integer** (`number_integer`) | 6000 | The feeding calculator: how much food is in this bag, in grams, so it can say how long it lasts (chapter 11) |
| `custom.free_from` | Product | **Single line text**, **List of values** | Grain free, Chicken free | The free-from chips under the price (chapter 11) |
| `custom.ingredients` | Product | **Multi-line text** | Lamb (32%), oats, brown rice… | The **Ingredients** accordion (chapter 11) |
| `custom.card_meta` | Product | **Single line text** (`single_line_text_field`) | Vegetable-tanned leather | The meta line above the name on product cards, in place of the type and the number of sizes (chapter 2) |

A **Specification row** block can show any other product metafield you create, such as a material (chapter 6).

## How to fill them in

**Size weights** (`custom.size_weights`): only for a product whose sizes don't match your theme-wide **Weight range per size**, such as a harness that runs small. One size per line, the size name exactly as in the product's Size option, a `|`, then the weight range:

```
XS | 0–4 kg
S | 4–9 kg
M | 9–18 kg
L | 18–32 kg
XL | 32+ kg
```

* Write the range with a dash (`0-4` or `0–4`) or "to" (`4 to 9 kg`), and end it with `kg` or `lb`. A range without a unit is read as kg.
* `32+ kg` means 32 kg and up, with no upper limit.
* Pounds work too, and are converted to kilograms at 0.45359237: `S | 9–20 lb`, `XL | 70+ lb`.
* A header line such as `Size | Weight` is ignored, and so are blank lines and lines starting with `#`.
* Sizes not listed get no range. If none of the product's sizes match a line, cards show "Check size".

**Species** (`custom.species`): `Dog`, `Cat`, or both for a product that suits either. Capitals don't matter, and "Dogs" and "Cats" work too. A product with no species shows for every pet; leave it empty on bowls, beds and anything else that suits both. Make it a list: a single line "Dog, Cat" reads as one value that matches neither.

**Size table** (`custom.size_table`): only for a product whose measurements differ from your **Default size table**. The header line first, then one size per line, columns separated by `|`:

```
Size | Neck cm | Chest cm | Weight kg
XS | 20–26 | 28–36 | 0–4
S | 26–32 | 36–46 | 4–9
M | 32–42 | 46–60 | 9–18
L | 42–52 | 60–76 | 18–32
XL | 52–62 | 76–92 | 32+
```

* The first column is the size, written exactly as in the product's Size option.
* A column whose heading says **cm** or **in** is a measurement: shoppers can switch it between centimetres and inches. Write `Neck in` for a table in inches.
* A column whose heading says **kg**, **lb** or **weight** is a weight. It's shown as written, never converted. The size guide's suggestion uses your weight ranges instead (chapter 9), so keep this column the same as them. `32+` means 32 and up.
* Any other column, such as `Fits`, is shown as written. Add more measurement columns the same way, such as `Back length cm`.
* A table with no header line gets the default headings, so always write one.

**Feeding guide** (`custom.feeding_guide`): copy the feeding table from the bag. One line per weight, the pet's weight in **kilograms**, a `|`, then grams of food per day. A header line is skipped:

```
Weight kg | Grams per day
2 | 55
5 | 105
10 | 165
15 | 215
20 | 265
30 | 350
40 | 430
```

The weights must be in kilograms even if your bag lists pounds, and the amounts in grams. Write plain numbers (`165`, not `165 g` or `150–180`); for a range on the bag, use the middle. Chapter 11 shows how the calculator reads between the lines.

**Net grams** (`custom.net_grams`): on each **variant**, the food in that bag in whole grams: `6000` for 6 kg, `1500` for 1.5 kg, `800` for 800 g. A variant without it shows the daily amount but not how long the bag lasts.

**Free from** (`custom.free_from`): short phrases, one per value, such as "Grain free", "Chicken free", "No added sugar". Each becomes a chip.

**Ingredients** (`custom.ingredients`): the ingredient list as it's printed, with line breaks if you want paragraphs (such as a second paragraph for the analysis). Use **Multi-line text**, not Rich text.

**Card meta** (`custom.card_meta`): one short line, such as the material. It replaces the type and size count on that product's card.

## Step 1: create the definitions

In admin, go to **Settings › Custom data › Products** and click **Add definition** for each product metafield you need:

1. Type the **Name**: Size weights, Species, Size table, Feeding guide, Free from, Ingredients or Card meta.
2. Check the **Namespace and key** under it and change it to exactly the key in the table. Shopify suggests `custom.` plus the name, so "Size weights" gives `custom.size_weights`, but a name like "Feeding guide (grams)" would give something like `custom.feeding_guide_grams`, which the theme won't find. Change it to `custom.feeding_guide`.
3. Click **Select type** and choose the type in the table: **Multi-line text** for size weights, size table, feeding guide and ingredients; **Single line text** for species, free from and card meta. For **Species** and **Free from**, change **One value** to **List of values**.
4. **Save**.

Then go to **Settings › Custom data › Variants** and add **Net grams**: key `custom.net_grams`, type **Integer**, **One value**. Add a minimum of 1 under the validations, if your admin offers it, so a wrong number can't be saved.

If Search & Discovery later doesn't offer **Species** as a filter source, open the definition again and check its access and filter options: the wording depends on your admin version.

## Step 2: fill them in

Open a product in admin and scroll to **Metafields**. For **Net grams**, click each variant in the product's **Variants** list and fill it in on the variant's page. To fill in many at once, select your products, use **Bulk edit** and add the metafield columns there. Metafields can also go through a product CSV, once they're defined.

The multi-line fields keep line breaks: press Enter between lines.

## Step 3: set up the filters

Install Shopify's free **Search & Discovery** app and add **Size**, **Species** (from `custom.species`) and **Colour** as filters. Shop by size links to the Size filter. Chapter 13 has the steps.

## Step 4: check

* Save a pet in the header chip, then open a collection: products with a Size option should show "Fits Mabel", "Too small for Mabel" or "Check size". A product for the other species shows no bone.
* Open a product with its own `custom.size_weights`: the fit row should give its range ("M fits 9 to 18 kg").
* Open a product with `custom.size_table` and click **Size guide**: the table should be yours, and the size tiles should show your neck ranges.
* Open a food on `product.food`: the calculator should say "About 185 g a day" and "This 6 kg bag lasts about 32 days." for a 12 kg pet with the sample guide above, the chips should sit under the price, and the Ingredients accordion should open.

If a value doesn't show, check the namespace and key first, then the owner (product or variant), then the type.