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
- Navigate to your environment home:
…/e/[environmentId]. - Open Widgets or click Create Widget.
- On
…/widgets/new, enter a display name and submit. - 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 Display panel to change layout, text, images, and per-device settings. See The Composer for full detail.
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.
| Action | Typical permission / user group |
|---|---|
| View widget list | USER_GROUP_VIEW_WIDGET |
| Create / edit draft | USER_GROUP_MANAGE_WIDGET |
| Delete widget | USER_GROUP_ADMIN_WIDGET |
| Publish to staging | USER_GROUP_POST_PUBLISH_TO_STAGING + staging widget groups |
| Publish to production | USER_GROUP_POST_PUBLISH_TO_PRODUCTION + production widget groups |