# Workflow: Add a Block

This workflow guides you through adding a block to an existing page.

## Prerequisites

- Page already exists in the CMS
- Latest content pulled: `riverbankcms pull`

## Steps

### 1. Check Available Block Types

View built-in blocks in `block-types.md`. Common block kinds:

| Kind | Description |
|------|-------------|
| `block.hero` | Hero sections with heading, subheading, image, CTA |
| `block.body-text` | Rich text content |
| `block.image` | Image with caption |
| `block.cta` | Call-to-action buttons |
| `block.embed` | Embedded content (videos, iframes) |
| `block.image-gallery` | Image gallery (grid/carousel/masonry/marquee variants) |
| `block.quote` | Blockquote with attribution |

Check `schema.md` for custom blocks specific to this site.

### 2. List Existing Blocks

See what blocks are already on the page:

```bash
riverbankcms block list <page-identifier>
```

**Example:**

```bash
riverbankcms block list home
```

### 3. Add the Block

**Basic usage:**

```bash
riverbankcms block upsert <page-id> <block-id> --kind <block-kind> --data '<json>'
```

**Examples:**

Add a hero block:

```bash
riverbankcms block upsert home main-hero \
  --kind block.hero \
  --data '{"heading": "Welcome", "subheading": "to our website"}'
```

Add a body text block:

```bash
riverbankcms block upsert home intro-content \
  --kind block.body-text \
  --data '{"content": "<p>Welcome to our site. We offer...</p>"}'
```

Add an image block:

```bash
riverbankcms block upsert home feature-image \
  --kind block.image \
  --data '{"src": "/images/feature.jpg", "alt": "Feature image", "caption": "Our latest product"}'
```

Add a CTA block:

```bash
riverbankcms block upsert home main-cta \
  --kind block.cta \
  --data '{"text": "Get Started", "url": "/signup", "style": "primary"}'
```

### 4. Specify Position (Optional)

Add the block at a specific position (0-indexed):

```bash
riverbankcms block upsert home new-section \
  --kind block.body-text \
  --data '{"content": "<p>...</p>"}' \
  --position 0
```

- `--position 0` places it first
- `--position 1` places it second
- Omitting position adds it at the end

### 5. Preview the Block

Preview how the block will render:

```bash
riverbankcms preview block.hero \
  --data '{"heading": "Welcome", "subheading": "to our website"}' \
  --open
```

### 6. Verify the Block

Confirm the block was added:

```bash
riverbankcms block get home main-hero
```

List all blocks to see the order:

```bash
riverbankcms block list home
```

## Complex Block Content

For blocks with nested or complex content, use a JSON file.

### Example: Hero with Background and CTA

**hero-content.json:**

```json
{
  "heading": "Welcome to Our Platform",
  "subheading": "Build amazing things with us",
  "backgroundImage": {
    "src": "/images/hero-bg.jpg",
    "alt": "Abstract background"
  },
  "cta": {
    "text": "Get Started",
    "url": "/signup"
  },
  "alignment": "center"
}
```

```bash
riverbankcms block upsert home main-hero \
  --kind block.hero \
  --file ./hero-content.json
```

### Example: Gallery Block

**gallery-content.json:**

```json
{
  "images": [
    { "image": { "type": "image", "src": "/images/project-1.jpg", "alt": "Project 1" }, "caption": "E-commerce redesign" },
    { "image": { "type": "image", "src": "/images/project-2.jpg", "alt": "Project 2" }, "caption": "Mobile app" },
    { "image": { "type": "image", "src": "/images/project-3.jpg", "alt": "Project 3" }, "caption": "Brand identity" }
  ],
  "variant": "grid"
}
```

```bash
riverbankcms block upsert home portfolio-gallery \
  --kind block.image-gallery \
  --file ./gallery-content.json
```

### Example: Marquee Gallery (infinite scroll)

```json
{
  "variant": "marquee",
  "marqueeDirection": "left",
  "marqueeSpeed": "medium",
  "marqueePauseOnHover": true,
  "marqueeImageSize": "md",
  "images": [
    { "image": { "type": "image", "src": "/images/project-1.jpg", "alt": "Project 1" }, "caption": "E-commerce redesign" }
  ]
}
```

## Updating Existing Blocks

To update a block, use the same `upsert` command with the same block ID:

```bash
riverbankcms block upsert home main-hero \
  --kind block.hero \
  --data '{"heading": "New Heading", "subheading": "Updated content"}'
```

The block is replaced with the new content.

## Reordering Blocks

Change the order of blocks on the page:

```bash
riverbankcms block reorder home main-hero intro-content feature-image main-cta
```

Blocks appear in the order listed.

## Deleting Blocks

Remove a block:

```bash
riverbankcms delete block home old-section --yes
```

## Troubleshooting

### "Invalid block kind"

- Check the kind matches exactly (e.g., `block.hero` not `hero`)
- See `block-types.md` for valid system blocks
- See `schema.md` for custom blocks (e.g., `custom.my-block`)

### Block not rendering correctly

- Verify the data structure matches what the block expects
- Preview the block: `riverbankcms preview <kind> --data '...' --open`
- Check for required fields in `block-types.md`

### JSON parsing error

- Ensure JSON is properly quoted in the shell
- Use single quotes around the JSON string
- For complex content, use `--file` instead of `--data`

### Block at wrong position

- Use `riverbankcms block reorder` to fix the order
- Or delete and re-add with `--position`

## Related Workflows

- **Block Extensions** - Add layout variants to system blocks: see `block-extensions.md`
- **Custom Blocks** - Create site-specific blocks: see `custom-block.md`
- **Content Types** - Embed content entries on pages: see `content-types.md`
- **CMS-ify a Page** - Convert hard-coded pages to CMS-driven: see `cmsify-page.md`
