Adding Widgets

A widget is added to a Layout or Playlist in a multi-step process.

1

Locate module / template and playlist

Find the Module and optional Template you want to add, along with the playlist you want to add it to.

2

Call “Add Widget”

Use the widget POST API to add the widget. The add widget API requires a playlistId; when working with a standalone playlist this is simply the ID obtained from playlist add or playlist search. However, when working with a layout you either need to add a region for your new widget to sit in, or add it to an existing region.

Once you have a playlistId for the region you’re adding against, you can use the widget POST API to add the widget. There are two key parameters to this API, aside from playlistId:

• type: The module type of the widget you’re trying to add. Use the Module Search API to find the one you want.
• templateId: If the module has a dataType, provide the ID of a module template returned by the Module Template Search API.

The templateId of elements is reserved for Elements, but is not available via the API yet.

Note: widgets and data widgets with static templates can be added via the API. It is not possible to add Elements via the API.

3

Discover supported properties

Discover the properties supported by the module and the template. Any omitted properties will be set as their defaults.

4

Call “Edit Widget” and supply properties

Call the Edit Widget API and supply the properties you discovered. When a widget is edited it is necessary to provide all properties for that widget’s module and its module template if it has one. Any omitted properties will be set as their defaults.

Types of region

There are 4 types of region available:

• zone: Used only in templates and automatically converted to either a frame or playlist when a widget is added to them.
• frame: For single widgets (only one widget can be added).
• playlist: For multiple widgets which will play in sequence.
• canvas: For elements and not yet available via the API.

If you have a frame region and you use its playlistId to add another widget it will automatically be converted to a playlist with both widgets in sequence.

Hint: Regions are not applicable when adding a widget to a standalone playlist.

Older versions

Xibo CMS v3.3 and earlier had a more rigid set of API calls for adding widgets and did not cater for custom modules. They were still added in the same process, but the properties supported by the module were already documented in Swagger.

You can view each of these requests in the Swagger docs for those older versions.

Links:

• Adding Widgets: https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-adding-widgets
• Types of region: https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-types-of-region
• Editing Widgets: https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-editing-widgets
• Older versions: https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-older-versions