# Widget Workflows Guide for Modyo MCP

How to create, publish and place widget definitions on a page with the MCP tools, and how to keep references stable while doing it. Widget IDs change when a widget is published; the UUID does not.

---

## Table of Contents

1. [How versions work](#how-versions-work)
2. [IDs vs UUIDs](#ids-vs-uuids)
3. [Create and publish a widget](#create-and-publish-a-widget)
4. [Add the widget to a page](#add-the-widget-to-a-page)
5. [Widget variables](#widget-variables)
6. [Publishing](#publishing)
7. [Common pitfalls](#common-pitfalls)
8. [Limitations](#limitations)

---

## How versions work

A widget definition is stored as several rows that share one UUID. Each row has a version type:

| Version type | Meaning |
|--------------|---------|
| `editable` | The working copy. Edits go here and are invisible on the site |
| `current` | The published version, the one pages render |
| `backup` | A previous published version, kept for rollback up to a fixed limit |
| `scheduled` | A version waiting for its publication date |

Publishing turns the **editable row itself** into the published one: it keeps its `id` and becomes `current`. The row that was `current` becomes a `backup`, and Modyo creates a **new editable row, with a new `id`**, as a copy of what was just published. So after every publish:

- The `id` you were editing is now the published version.
- The next edit goes to a different row with a different `id`.
- The `uuid` is the same in all of them.

A rollback does not copy anything: the chosen backup row becomes `current` again and the row that was `current` becomes a backup.

---

## IDs vs UUIDs

| Identifier | Stable across publishes | Use it for |
|------------|-------------------------|------------|
| `id` (number) | No | Short-lived references inside one editing session |
| `uuid` (string) | Yes | Anything stored, scripted or repeated: `identifier` in `channels-widgets-manage`, `channels-widgets-upsert` by name, `nameOrUuid` when placing a widget on a page |

Widget tools accept a smart identifier: a number resolves by `id`, a string by UUID or name. Prefer the UUID. Do not keep a numeric `id` across a publish.

---

## Create and publish a widget

### 1. Create or update the definition

`channels-widgets-upsert` creates the definition if the name does not exist and updates it if it does, so it is safe to repeat:

```json
{
  "siteId": 1001,
  "name": "my-widget",
  "html": "<div class=\"my-widget\">...</div>",
  "css": ".my-widget { padding: 1rem; }",
  "js": ""
}
```

To change one section without resending the others, use `channels-widgets-code-edit` (`section`, `operation` = `replace`, `insert` or `append`; `preview: true` shows the result without writing).

`channels-widgets-manage` covers the rest of the lifecycle: `manage` (get, create, update), `clone`, `list`, `unpublish`, `archive`, `restore` and `delete`. Keep the `uuid` from the response.

### 2. Preview

`channels-preview` with `action: "widget"` and the widget's `widgetUuid` returns a preview URL for the widget.

### 3. Publish

```json
{ "siteId": 1001, "publish_all": false, "element_types": ["widgetDefinition"], "element_names": ["my-widget"], "dry_run": true }
```

Run it first with `dry_run: true` to see what would be published, then again without it. See [Publishing](#publishing).

### 4. Look the widget up again

After publishing, find the widget by its UUID (`channels-widgets-manage` with `identifier` set to the UUID) and take the current `id` from the response if you need one.

---

## Add the widget to a page

A page can only use a widget definition that is **published**. Place it by name or UUID.

To add one widget without touching the others, use `channels-pages-widget-instance`:

```json
{
  "siteId": 1001,
  "pageId": 2001,
  "action": "create",
  "type": "custom_widget",
  "nameOrUuid": "<widget uuid>",
  "title": "My widget",
  "column": 0,
  "position": 0,
  "sync": false
}
```

To set the complete layout of a page, use `channels-pages-widget`. It **replaces all widgets** of the page, so it asks for confirmation when the page already has widgets; send `confirmed: true` when you intend the replacement.

| Property | Description |
|----------|-------------|
| `type` | `custom_widget` (needs `nameOrUuid`), `html` or `rich_text` (need `code`) |
| `nameOrUuid` | Name or UUID of an existing widget definition |
| `title` | Instance title, required |
| `column` | Column, 0 to 2; the valid values depend on the page grid |
| `position` | Position inside the column, starting at 0 |
| `sync` | `true` renders the widget with the page; `false` (default) loads it after the page renders |
| `variables` | Variable values for this instance |

Update or remove an instance with `channels-pages-widget-instance` (`update`, `delete`) using `widgetUuid`, which is stable across publishing.

---

## Widget variables

A widget definition declares variables; each instance on a page stores its own values. Read and write them per slug with `channels-pages-widget-variables`:

```json
{ "siteId": 1001, "pageId": 2001, "widgetUuid": "<instance uuid>", "action": "set", "slug": "limit", "value": 3 }
```

- `action` is `list`, `get`, `set` or `unset`. `set` also accepts a `variables` map to set several slugs.
- The slug must already be declared by the widget definition.
- Values are stored as selected, which is what makes them take effect.

In the widget's Liquid, read them from `widget.variables`:

```liquid
{% assign limit = widget.variables.limit | default: 3 %}
{% assign entries = spaces[widget.variables.space_uid].types[widget.variables.type_uid].entries | limit: limit %}
```

Values shared by many widgets or pages belong in global variables: `channels-variables-manage`, read in Liquid as `{{ vars.slug }}`.

---

## Publishing

`channels-publish` creates the release. Parameters:

| Parameter | Description |
|-----------|-------------|
| `siteId` | Required |
| `publish_all` | Default `true`: publish every pending element of the site |
| `element_types` | Limit to `template`, `page`, `widgetDefinition` or `menu` (with `publish_all: false`) |
| `element_names` | Limit to elements whose name matches exactly, ignoring case |
| `dry_run` | Preview only; nothing is published |
| `dependency_order` | Publish templates, then widgets, then pages and menus, in separate releases |
| `continue_on_error` | With `dependency_order`, keep going when one phase fails (default `true`) |

Publish a widget and the page that uses it together, or widgets first:

```json
{ "siteId": 1001, "dependency_order": true, "dry_run": true }
```

Because `publish_all` defaults to `true`, a call without filters publishes everything pending on the site, not just your widget, and `element_types` is ignored. Pass `publish_all: false` with `element_types` and `element_names`, and run `dry_run` first.

The response lists each published element with its `uuid` and its `oldId`.

### After publishing

- Use UUIDs to refer to the widget from here on.
- If a script kept a numeric `id`, look the widget up again.
- Check the result in a page preview: `channels-preview` with `action: "page"`.

---

## Common pitfalls

### Using a numeric id after a publish

The `id` you edited is now the published version, and the next edit lands on a new row. Reference the widget by `uuid`.

### Placing a widget that is not published

An empty or unpublished definition renders nothing. Publish it with `channels-publish`, or pass `publishWidgets: true` when creating the instance with `channels-pages-widget-instance`.

### Publishing too much

`channels-publish` without filters publishes every pending template, page, widget and menu. Use `dry_run` and `element_names`.

### Replacing a page's widgets by accident

`channels-pages-widget` replaces the whole widget set. For one widget, use `channels-pages-widget-instance`.

### Concurrent edits

Lock a widget definition before editing it when others work on the site: `channels-locks-manage` with `action: "acquire"`, `lockable_type: "widget_definition"` and `lockable_id`, then `release` when you finish.

### Hardcoded content

```liquid
<!-- Only works for one type -->
{% assign entries = spaces['my-space'].types['my-type'].entries %}

<!-- Reusable: the instance decides -->
{% assign entries = spaces[widget.variables.space_uid].types[widget.variables.type_uid].entries %}
```

---

## Widget development checklist

Before publishing:

- [ ] Liquid syntax is valid
- [ ] Field names use bracket notation with the exact name from the content type: `fields['Name']`
- [ ] Optional fields render conditionally and collections have an empty state
- [ ] Variables have sensible defaults
- [ ] No inline styles or scripts without `nonce="{{csp_nonce}}"`
- [ ] Accessibility attributes (ARIA, alt text) are present
- [ ] Layout works at mobile widths

After publishing:

- [ ] The widget is referenced by UUID
- [ ] The widget renders in a page preview

---

## Limitations

- Rolling back a widget to a previous published version is not available through the MCP.
- Variables of a widget definition are created and updated with `channels-variables-manage` (`action: "manage"`, `applicationType: "widgets"`, the definition id as `applicationId`, plus `siteId`, `slug`, `value` and `lang`). Deleting a variable is not available.
- `channels-publish` publishes templates, pages, widget definitions and menus; it always publishes immediately; scheduled publication is not available.

---

## Related documentation

- [Editing published widgets](editing-published.md)
- [Development best practices](development.md)
