Widgets

What is a widget?

A widget is a page or screen built in the RuleCMS composer — a tree of rows and components stored as an itemList. Widgets are always scoped to a project environment (typically Development while you edit).

Creating a widget

1. Navigate to your environment home: …/e/[environmentId].
2. Open Widgets or click Create Widget.
3. On …/widgets/new, enter a display name and submit.
4. RuleCMS creates the widget and opens the composer at …/composer/widgets/[widgetId].

Requires POST_COMPOSER_WIDGET_ENV (via USER_GROUP_MANAGE_WIDGET or higher).

Editing a widget

In the composer

The composer is the primary editing surface. Drag components from the palette, arrange rows, and use the Modify drawer to change layout, text, images, and per-device settings. The gear in the widget header opens Widget Settings for styles on the widget as a whole — see Widget Settings and The Composer for full detail. Content that has to sit on top of the widget — a badge on a photo, a caption on a hero — lives on an overlay layer.

Widget list and search

The widgets list at …/widgets supports search and filters to find widgets in large projects. Click a widget to open its management page.

Widget management page

…/widgets/[widgetId] is the control center for one widget:

• Rename — change display name or key
• Copy — duplicate within the environment or copy to another environment
• Promote — move draft content to Staging or Production (separate from publishing)
• Publish tab — publish snapshots to staging or production; see Publishing
• Open in composer — return to visual editing

Edit JSON (advanced)

From the composer Go-To menu, choose Edit JSON to open …/configuration/widgets/[widgetId]. This raw JSON editor is for power users and integrations. Invalid JSON shows a validation message when you save.

Compare versions

…/widgets/compare-versions/[widgetId] lets you diff draft against published versions or compare two published snapshots side by side.

Collections inside widgets

Drop shared or embedded collections from the palette into a widget. Shared collections update everywhere they are referenced; embedded collections are tied to the widget version. See Collections.

Publishing widgets

Draft edits do not affect live sites until you publish. Publishing creates a versioned snapshot with a published key your apps fetch via the public API. The full workflow — staging vs production, version history, republish, restore to draft — is documented in Publishing.