Widgets

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.

Sample descriptor file:

<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:

Example controller file:

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>'
        };
    }
}