Custom Widget API

ibm.nitro.NitroConfig.runtimeResources.1 = \
  <link rel='stylesheet' type='text/css' media='screen' href='https://mywidgets.example.com/common.css'>; \n\
  <link rel='stylesheet' type='text/css' media='screen' href='https://mywidgets.example.com/MyYesNoWidget.css'>; \n\
  <script src='https://myWidgets.example.com/common.js'></script> \n\
  <script src='https://myWidgets.example.com/MyYesNoWidget.js'></script> \n

As your custom .js is loaded into the page, it is expected to register one or more widget definitions:

const myWidgetDefinition = {...};
nitro.registerWidget(myWidgetDefintion);

Full descriptions and examples are provided in the following topics. The following example is the basic skeleton of a custom widget:

const myWidgetDefinition = {
    id: 'example.YesNo', // uniquely identifies this widget
    version: '2.0.0', // the widget's version
    apiVersion: '1.0.0', // the version of this API
    label: 'Yes/No',
    description: 'Allows user to choose "Yes" or "No"',
    datatype: {
        type: 'string' // must be one of 'string', 'date', 'number', 'boolean', 'time', 'timestamp'
    },
    // for placement in the palette
    category: {
        id: 'example.choice.widgets',
        label: 'Choice Components'
    },
    iconClassName: 'myYesNoIcon', // styling of this class expected in custom .css
    builtInProperties: [...], // use existing properties: 'title', 'required', etc
    properties: [...], // custom properties, of prescribed types

    // called by Leap to initialize widget in the DOM with initial properties, and set-up event handling
    instantiate: function (context, domNode, initialProps, eventManager) {
        return {
             // (optional) for display in various parts of the UI
            getDisplayTitle: function () {
                return ...
            },

            // (required) for Leap to get widget's data value
            getValue: function () {
                return ...
            },

            // (required) for Leap to set widget's data value
            setValue: function (val) {
                ...
            },

            // (optional) for additional validation of value
            validateValue: function (val) {
                // return true, false, or custom error message
            },

            // (required) called when properties change in the authoring environment, or via JavaScript API
            setProperty: function (propName, propValue) {
                ...
            },

            // (optional) method to enable/disable widget
	        setDisabled: function (isDisabled) {
                ...
            },

            // (optional) determines what the author can do with the widget via custom JavaScript
            getJSAPIFacade: function () {
                return {
                    ...
                 };
            }
        };
    }
};