# Block Registry

ACF-style block management for the MTC Pharmacy platform. Define reusable content blocks with configurable fields, assign them to page templates, and manage block instances on pages, products, and categories.

## Setup

The module is registered as a Laravel service provider in `config/app.php`. Run migrations to create the required tables:

```sh
make migrate
```

This creates: `block_registry`, `block_registry_fields`, `block_registry_categories`, `block_registry_template_assignments`, `block_registry_versions`, and `entity_blocks`.

## Admin

Access the Block Registry at `/admin/blocks`. From here you can:

- **Define blocks** — create block definitions with fields, icons, categories, and optional Twig templates
- **Manage categories** — organise blocks into categories
- **Global blocks** — create site-wide blocks that can be referenced from any page/product/category
- **Template assignments** — control which blocks are available on which page templates, and which are added by default

Blocks are also available as a "Blocks" tab when editing pages, products, and categories in the admin.

## Field Types

| Type | Description |
|------|-------------|
| `text` | Single-line text input |
| `textarea` | Rich text editor (TinyMCE) |
| `checkbox` | Boolean toggle |
| `select` | Dropdown with predefined options |
| `image` | Image upload with optional cropping and srcset generation |
| `file` | File upload |
| `gallery` | Multiple image upload |
| `datetime` | Date and time picker |
| `colorpicker` | Colour picker |
| `coordinates` | Lat/lng coordinates |
| `tags` | Tag input |
| `repeater` | Repeatable group of sub-fields (no nesting) |

## Using Blocks in Templates

### Render all blocks for a page

```twig
{{ render_entity_blocks('page', p.id) }}
```

Each block is rendered using its assigned Twig template (set in the block definition's `template` field).

### Render blocks of a specific type

```twig
{{ render_blocks_by_type('page', p.id, 'hero-banner') }}
```

### Render a single block

```twig
{{ render_block(entityBlockId) }}
```

### Render a global block

```twig
{{ render_global_block(42) }}
```

### Get block data without rendering

```twig
{% set blocks = get_entity_blocks('page', p.id) %}
{% for item in blocks['hero-banner'] %}
    <h1>{{ item.title.value }}</h1>
{% endfor %}
```

Pass `true` as a third argument to include pre-rendered HTML alongside the data:

```twig
{% set blocks = get_entity_blocks('page', p.id, true) %}
```

### Entity types

Blocks can be attached to any of these entity types:

- `page` — CMS pages
- `item` — Products
- `category` — Product categories
- `global` — Site-wide blocks (not tied to a specific entity)

## Block Templates

When a block has a Twig template assigned, the template receives these variables:

| Variable | Description |
|----------|-------------|
| `block` | The block definition model |
| `block_name` | Block name string |
| `block_slug` | Block slug string |
| `fields` | Simple key/value map of field data |
| `banner` | Full field data with value, type, label, and required |
| `block_data` | Alias for `banner` |
| `slides` | Repeater field data (auto-mapped) |

## Image Processing

Image fields with cropping enabled will automatically:

- Crop to the specified aspect ratio
- Generate responsive `srcset` images at multiple widths (default: 400, 800, 1200, 1600px)
- Cache processed images to `/uploads/cache/blocks/{entityBlockId}/`

Configure per field via the image settings in the block definition editor.
