Widgets
Contents
Introduction
Widgets are user interface components that dynamically extends Admin interfaces. Widgets may or may not be context-dependent (require id of selected content and current branch).
Interface
Currently, the only admin tool that implements widget support is Content Studio. Read more about Content Studio widgets here
Implementation
Widgets are essentially a specialized web apps. Like all other XP components, they are defined by a controller and a descriptor.
To create a widget, add a new folder in your project structure, i.e. src/main/resources/admin/widgets/<widget-name>
. The folder must contain both a descriptor (<widget-name>.xml
), and a controller (<widget-name>.js
).
Descriptor
The widget descriptor defines the display name, which roles are required to access the widget and the interfaces it implements.
An interface is simply a unique identifier that links the widget to its extension point (i.e. Content Studio’s context panel)
For example, for your widget to be displayed in the Content Studio’s Context panel, specify interface contentstudio.contextpanel
. To extend the Content Studio top menu, specify interface contentstudio.menuitem
.
The descriptor file must match the widget folder name, i.e. admin/widgets/<widget-name>/<widget-name>.xml
.
<widget>
<display-name>My first widget</display-name>
<description>Description of my first widget</description>
<interfaces>
<interface>contentstudio.contextpanel</interface>
</interfaces>
<allow>
<principal>role:system.admin</principal>
<principal>role:myapp.myrole</principal>
</allow>
</widget>
Controller
To drive the widget, we will need a controller. The controller typically renders the widget’s initial html. Depending on the widget implementation it may also handle any further server requests from the widgets interface.
The controller file must match the widget name, i.e. admin/widgets/<widget-name>/<widget-name>.js
:
exports.get = function (req) {
return {
body: '<widget>My first widget</widget>',
contentType: 'text/html'
};
};
Depending on the interface a widget is implementing, controller may be initialised with parameters, for instance providing a specific context. |
Icon
Widgets may also have icons. Simply place an SVG or PNG file into the widget folder, i.e. admin/widgets/<widget-name>/<widget-name>.svg`
Context Panel widgets
INFO: This section contains specific details on implementing Context panels for Content studio.
Once your widget application is deployed, the widget should become available in the Content Studio’s Context Panel.
The ID of currently selected content item and the contextual repository/branch will be passed to the widget via query parameters: contentId
, repository
and branch
.

If your widget is context-dependent (requires content id), remember to add a proper check/error feedback to the controller:
exports.get = function (req) {
var contentId = req.params.contentId;
if (!contentId) {
return {
contentType: 'text/html',
body: '<widget class="error">No content selected</widget>'
};
}
}