# cms-edit — Collection Field Reference

A `collection` entry is a group of components — a card grid, timeline, category explorer, etc. The `collectionType` field picks which visual layout to use. Children are stored in the `contents` field.

---

## Fields

| Field | Type | Description |
|---|---|---|
| `cmsLabel` | Text | Human-readable label in Contentful's entry list |
| `collectionType` | Text | Variant discriminator — e.g. `CardGrid`, `Timeline`, `CategoryExplorer`. Run `cms-edit types` to see valid values |
| `heading` | Text | Section heading |
| `preHeading` | Text | Small label above the heading. Rendered as `<p>`, not a heading tag |
| `postHeading` | Text | Small label below the heading. Rendered as `<p>`, not a heading tag |
| `body` | RichText | Introductory body text for the collection |
| `links` | Array of Links | CTA link entries for the collection as a whole |
| `contents` | Array of Links | The child component/collection entries in display order |
| `backgroundColour` | Text | Named background colour |
| `textColour` | Text | Named text colour |

---

## Reading Collection Fields

```bash
cms-edit open --page-slug /solutions
cms-edit snapshot
# A collection appears as a nested group in the tree, e.g.:
#   @c3   collection  [draft]  CardGrid
#     @c4   component  [draft]  Card — Hepatology
#     @c5   component  [draft]  Card — Dermatology

cms-edit read @c3              # all fields on the collection
cms-edit read @c3 heading      # just the heading
```

---

## Setting Collection Fields

```bash
cms-edit set @c3 heading "Our Solutions"
cms-edit set @c3 preHeading "What We Do"
cms-edit rtf @c3 body "An overview of our capabilities.\n\nSelect a speciality below."
cms-edit set @c3 backgroundColour "Grey"
```

---

## Adding Child Items

```bash
# Add a new child component inside a collection
cms-edit add Generic component --parent @c3

# Re-snapshot after add — refs are renumbered
cms-edit snapshot

# Then set fields on the new child
cms-edit set @c4 heading "New Card Heading"
```

**Important:** After any `add --parent` operation, all entries that come after the collection in the depth-first tree are renumbered. Always re-snapshot or use variable binding in `run` batches. See `cms-edit help run`.

---

## Reordering Children

```bash
# Move a child to a specific position (0-indexed) within its parent
cms-edit move @c5 0      # move to first position
cms-edit move @c4 2      # move to third position
```

---

## Removing a Child

```bash
cms-edit remove @c5      # unlinks from parent; does not delete the entry
```

---

## In create from-json

Collections use `"contentType": "collection"` and their children go in `"items"`. The `items` array maps to the `contents` field in Contentful:

```json
{
  "contentType": "collection",
  "type": "CardGrid",
  "cmsLabel": "Solutions Cards",
  "fields": {
    "heading": "Our Solutions",
    "preHeading": "What We Offer",
    "body": "Choose a speciality area below.\n\n",
    "backgroundColour": "Grey"
  },
  "links": [
    { "type": "internal", "label": "See All Solutions", "slug": "/solutions" }
  ],
  "items": [
    {
      "contentType": "component",
      "type": "Generic",
      "cmsLabel": "Card — Hepatology",
      "fields": {
        "heading": "Hepatology",
        "body": "Evidence generation for liver disease.\n\n"
      },
      "links": [
        { "type": "internal", "label": "Learn More", "slug": "/solutions/hepatology" }
      ]
    },
    {
      "contentType": "component",
      "type": "Generic",
      "cmsLabel": "Card — Dermatology",
      "fields": {
        "heading": "Dermatology",
        "body": "Real-world data for skin conditions.\n\n"
      },
      "links": [
        { "type": "internal", "label": "Learn More", "slug": "/solutions/dermatology" }
      ]
    }
  ]
}
```

**Note:** Internal links in `items[].links` must resolve — the target pages must exist in Contentful before running `create from-json`. Use `--dry-run` to validate all slugs first. See `cms-edit help create-from-json`.