# Editing Published Widgets

How to change a widget definition that is already published and used on pages, without breaking the pages that render it. Read [Widget Workflows](workflows.md) first for the version model.

## Key concepts

- A widget **definition** holds the code (HTML, CSS, JS). A widget **instance** is one placement of a definition on a page, with its own title, position and variable values.
- Editing a definition never changes what the site shows. Edits go to the **editable** version; pages keep rendering the **current** (published) version until you publish.
- Publishing makes the editable version the current one, keeps the previous current version as a backup, and creates a new editable version with a new `id`. The `uuid` does not change.
- Every page that uses the definition shows the new code after the publish.

## Edit a widget used on a page

### 1. Find the definition's UUID

Read the page with the widget fields you need:

```json
{
  "siteId": 1001,
  "action": "manage",
  "identifier": 2001,
  "widget_fields": ["id", "title", "type", "widget_definition_uuid", "column", "position"]
}
```

Each custom widget in the response carries `widget_definition_uuid`. To list only the widgets of one page, `channels-pages-widget-instance` with `action: "list"` does the same.

### 2. Read the current code

```json
{ "siteId": 1001, "action": "manage", "identifier": "<definition uuid>", "includeCode": true }
```

`channels-widgets-manage` returns the definition, with its HTML, CSS and JS when `includeCode` is `true`.

### 3. Lock it (optional, recommended on shared sites)

```json
{ "action": "acquire", "lockable_type": "widget_definition", "lockable_id": 3001 }
```

Use `channels-locks-manage`, and `release` the lock when you finish. If another user holds it, `take_over` transfers it.

### 4. Change the code

For a small change, edit one section in place:

```json
{
  "siteId": 1001,
  "identifier": "<definition uuid>",
  "section": "html",
  "operation": "replace",
  "search": "<h2>Old title</h2>",
  "replaceWith": "<h2>New title</h2>"
}
```

This is `channels-widgets-code-edit`. Add `preview: true` to see the result without writing. For larger changes, send the new code with `channels-widgets-upsert` (by name) or `channels-widgets-manage` (by identifier).

The pages still show the previous version at this point.

### 5. Preview before publishing

`channels-preview` with `action: "page"` and `editableWidgets` set to an array with the numeric `id` of the editable widget version (for example `[3001]`) renders the page with your unpublished changes. Preview with `editableTemplates`, `editableContent` or `editableNavigation` as well when the change depends on them.

### 6. Publish

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

Run it with `dry_run: true`, check that only your widget is listed, then run it again without `dry_run`. Without filters, `channels-publish` publishes everything pending on the site.

### 7. Check

Look the widget up again by UUID, and open a page preview. The numeric `id` you edited is now the published version; do not reuse it for the next edit.

## Common issues

### The changes are not visible on the page

The edit is still in the editable version. Publish it with `channels-publish`.

### An `id` stops working or points to the wrong version

Numeric ids change at every publish. Store and pass the `uuid`.

### The widget instance and the definition are mixed up

`widgetUuid` in `channels-pages-widget-instance` and `channels-pages-widget-variables` identifies the **instance** on the page. `identifier` in `channels-widgets-manage` and `channels-widgets-code-edit` identifies the **definition**. They are different UUIDs; the instance carries the definition's UUID in `widget_definition_uuid`.

### Field names do not match the content type

Field names in Liquid must match the content type exactly, including spaces, accents and capitalization:

```liquid
{{ product.fields['Title'] }}
{{ product.fields['Icon SVG'] }}
{{ product.fields['URL'] }}
```

Read the exact names with `content-types-get`:

```json
{ "spaceId": 3001, "typeId": 5001 }
```

Use the names in the field definitions of the response, not guessed variants such as `'icon_svg'` or `'url'`.

### Somebody else is editing the same widget

Check `channels-locks-manage` with `action: "list"`. Wait for the release or use `take_over` when the lock is stale.

## Best practices

- Store the `uuid`, never the numeric `id`.
- Keep a copy of the current code before a large rewrite. `includeCode: true` cuts each section at 102,400 characters and marks it with `[truncated, N chars total]`; when a section is truncated, take the complete code from `channels-download` instead.
- A published change reaches every page that uses the definition. Treat a breaking change as a change to all of them.
- Publish with `publish_all: false`, `element_types: ["widgetDefinition"]`, `element_names` and `dry_run` so only the widget you edited goes out.

## Limitations

- Rolling a widget back to a previous published version is not available through the MCP.
- Removing a variable from a widget definition is not available through the MCP. Variables are created and updated with `channels-variables-manage` (`action: "manage"`, `applicationType: "widgets"`, the definition id as `applicationId`, plus `siteId`, `slug`, `value` and `lang`).

## Tool reference

| Tool | Use |
|------|-----|
| `channels-pages-manage` | Read a page and the widgets it contains |
| `channels-pages-widget-instance` | List, read, update or remove one widget instance |
| `channels-pages-widget-variables` | Read and write the variable values of one instance |
| `channels-widgets-manage` | Read a definition, with code, and manage its lifecycle |
| `channels-widgets-code-edit` | Change one section of a definition in place |
| `channels-widgets-upsert` | Create or replace a definition by name |
| `channels-locks-manage` | Lock a definition while editing |
| `channels-preview` | Preview pages and widgets, including unpublished changes |
| `channels-publish` | Publish, with `dry_run` |
| `content-types-get` | Read the exact field names of a content type |

## Related documentation

- [Widget Workflows](workflows.md)
- [Development best practices](development.md)
