Creating a Module

“Module” is Xibo’s name for the logic which sits behind a Widget. Users create widgets, developers create modules.

Xibo v4 has extensive changes to the way widgets are modelled and developed. If you are thinking of making a widget, we recommend using v4 as your starting point.

Xibo separates widget creation into two parts, the Module and then optionally the Template. All widgets must have a module, but only widgets with data will require a template. Templates can be reused across multiple modules, for example you may have multiple services providing social media data, all of which can be visualised by the same template.

• Module: is a library file or produces some HTML generated when it is saved, and does not change (unless changed by JavaScript).
• Template: is HTML/CSS/JavaScript applied to each item of data, and new data can be fed into the widget as it is playing.

Properties in the module will be shown on a “configure” tab in the Layout Editor, and properties in the template will be shown on an “appearance” tab.

Modules which are expected to supply data have the dataType property set. Xibo has some built in datatypes, such as article, social media, event, etc, but if these do not match the module it is possible to add new data types via XML.

What do you want to create?

Hello World…

See hello world for simple working examples of a Module. See templates for a detailed look at how to create elements, stencils and static templates for Data Widgets.

File locations

Xibo’s module system uses XML, and where necessary PHP files for data retrieval, complex validation and upgrading.

These files are located in the following places:

XML definitions

Definitions for module and template XML files can be found in XML definitions.

Saving, previewing and generating HTML

Properties

Properties declared in either the module or template XML will be shown on the widget edit form in the Layout Editor and saved with the Widget. Properties from the module will be shown in the “Configure” tab, and properties from the template will be shown in the “Appearance” tab.

The users choices will be saved with the widget and automatically available when rendering a stencil from Twig or Handlebars. If the user does not make a choice, any default value will be used.

Generating HTML

Each time the widget is saved, the module and template XML stencils will be used to generate and cache the Widget HTML, which will subsequently be sent to players as necessary. HBS content in the stencils will be rendered at playtime.

Working with Data

Modules with data will need to supply a dataType property and should ensure that this is unique to the CMS. There are two ways to provide data for a dataType, see “Providing Data” below.

Previewing

A module has the opportunity to provide an alternative preview using the preview option. If this is not provided the full HTML will be shown instead.

Render flow

How it works

The rendering flow of a module is how the content is created, based on the data that is passed in to the module. All methods are optional, and run in sequence.

The onInitialize method is the first to run, and is mostly used to set up the variables and methods that will be used in the rendering process.

If the module has a data type, this is followed by either onDataLoad or onDataError depending on whether the data is cached and ready to use.

This is followed by the onParseData method, which is used to parse and transform the data for each item that comes from the provider.

Next the rendering method onRender and onTemplateRender run in sequence. The onRender method is used to render the HTML for the module, and the onTemplateRender method is used to render the HTML for the template. If they are not present, a default render method is used to render and scale the module appropriately.

Finally, the onVisible method is used to start any animations that may be required.

Methods

onInitialize, onRender, onVisible

Called on the module.

onDataLoad

Called on any data returned by the provider.

onDataError

Called if data is expected and the provider doesn’t return any

onParseData

Called on each data item returned by the provider.

onTemplateRender

Called on the template.

Note: Both onRender and onTemplateRender are called multiple times when changing the dimensions of the preview window. If set, the methods needs to be able to clear the previous render in each call.

onElementParseData

Elements only.

Replacements

In the module hbs template, with handlebar expressions we can use module properties and template properties to render and structure the content.

<hbs><![CDATA[
<h1>{{name}}</h1>
{{#eq showAge 1}}
    <p>Age: {{age}}</p>
{{/eq}}
]]></hbs>

In the twig template, we can also use variables and expression from the Twig template engine to render the content.

<twig><![CDATA[
<style>
    .name {
        font-size: {{fontSize}}px;
    }
{% if showAge != 1 %}
    .age {
        display: none;
    }
{% endif %}
]]></twig>

Using the Xibo Interactive Control

Xibo Interactive Control is a JavaScript helper library used primarily to send actions from Widgets running in Xibo’s built in Web Browser, to the Player application itself on its local web server.

But that tool can also be used to store and retrieve data during the execution of a Widget. That means we can store data in a rendering method and retrieve it in another one.

Store data

To store data, we can use the xiboIC object, which is available globally in the window object.

Store variable:

xiboIC.set('myData', 'Hello World');

Store method:

xiboIC.set('myMethod', function() {
    return 'Hello World';
});

Retrieve data

In a different method, we can then retrieve the data using the xiboIC object.

Retrieve variable:

var myData = xiboIC.get('myData');
console.log(myData);

Retrieve method:

var myMethod = xiboIC.get('myMethod');
console.log(myMethod());

Providing data

If you’re creating a template data will be provided by one of the existing modules without any further action.

If you want to make a new data source available for an existing data type, or you’re creating a module and templates for a completely new data type; you will need to implement a data provider.