Create A Mashup Widget Extension Part 2

Yes

Step 5: Mashup Builder API
Step 6: Mashup Builder Callbacks

Step 5: Mashup Builder API

The following APIs can be accessed by a widget in the context of the Mashup Builder:

API Description

this.jqElementId	This is the DOM element ID of your object after renderHtml().
this.jqElement	This is the jquery element.
this.getProperty(name) / this.setProperty(name,value)	Note that every call to this function will call afterSetProperty() if it’s defined in the widget.
this.updatedProperties()	This function should be called anytime properties are changed in the widget so that the Mashup Builder can update the widget properties window, the connections window, and so on.
this.getInfotableMetadataForProperty(propertyName)	If you need the infotable metadata for a property that you bound, you can get it by calling this API; it returns undefined if it is not bound.
this.resetPropertyToDefaultValue(propertyName)	This call resets the named property to its default value.
this.removeBindingsFromPropertyAsTarget(propertyName)	This call removes target data bindings from the propertyName. Use it only when the user has initiated an action that invalidates the property.
this.removeBindingsFromPropertyAsSource(propertyName)	This call removes source data bindings from the propertyName. Use this only when the user has initiated an action that invalidates the property.
this.isPropertyBoundAsTarget(propertyName)	This call returns a result that indicates if the property has been bound as a target. You can use it to determine if a property has been set or bound.
this.isPropertyBoundAsSource(propertyName)	This call returns a result that indicates if the property has been bound as a source. You can use it to determine if a property has been bound to a target.

Example of the Checkbox Widget’s validate() function:

this.validate = function () {
    var result = [];
    if (!this.isPropertyBoundAsSource('State') && !this.isPropertyBoundAsTarget('State')) {
        result.push({ severity: 'warning',
        message: 'State for {target-id} is not bound' });
    }

    return result;
}

Example of the Blog Widgets validate() function:

this.validate = function () {
    var result = [];
    var blogNameConfigured = this.getProperty('Blog');

    if (blogNameConfigured === '' || blogNameConfigured === undefined) {
        if (!this.isPropertyBoundAsTarget('Blog')) {
            result.push({ severity: 'warning', message: 'Blog is not bound for {target-id}' });
        }
    }

    return result;
}

Step 6: Mashup Builder Callbacks

The following widget functions are called by the Mashup Builder to control the widget’s behavior.

widgetProperties() - Returns a JSON structure that defines the properties of the widget. Listed are the possible properties of the widget:

Required Property

The only required property is:

name - The user-friendly widget name, as shown in the widget toolbar

Optional Properties

There are a number of optional properties that can be contained in the returned JSON structure.

Property Description

description	A description of the widget, used for its tooltip. iconImage - File name of the widget icon/image
category	An array of strings for specifying one or more categories to which the widget belongs (such as “Common”, “Charts”, “Data”, “Containers”, and “Components”), enabling widgets to be filtered by type/category.
isResizable	true (default) or false
defaultBindingTargetProperty	Name of the property to use as the data/event binding target
borderWidth	If the widget has a border, set this property to the width of the border. This property ensures pixel-perfect WYSIWG between design and runtime. If you set a border of one pixel on the widget-content element at design time, you are making the widget two pixels taller and two pixels wider (one pixel on each side). To account for this discrepancy, set the borderWidth property to make the design-time widget the same number of pixels smaller. This property places the border inside the widget that you created and makes the width and height in the widget properties accurate.
isContainer	true or false (default). Controls whether an instance of the widget can be a container for other widget instances.
customEditor	The name of the custom editor dialog for entering and editing the widget configuration. The system assumes there is a dialog you created named TW.IDE.Dialogs.<name>.
customEditorMenuText	The text that appears on the flyout menu of the widget and the tooltip text for the Configure Widget Properties button. For example, “Configure Grid Columns.”
allowPositioning	true (default) or false
supportsLabel	true or false (default). If true, the widget exposes a label property used to create a text label that appears next to the widget in the Composer and at runtime.
supportsAutoResize	true or false (default). If true, the widget can be placed in responsive containers (such as columns, rows, responsive tabs, responsive mashups).
properties	A collection of JSON objects for the widget that describe the properties of the widget that can be modified when the widget is added to a mashup. These properties are displayed in the Properties window of the Mashup Builder - the name of each object is used as the property name and the corresponding attributes control how the property value is set.
afterLoad()	Called after the object is loaded and properties have been restored from the file, but before the object has been rendered
renderHtml() [required]	Returns HTML fragment that the Composer will place in the screen; the widget’s content container (e.g. div) must have a ‘widget-content’ class specified. After this container element is appended to the DOM, it becomes accessible via jqElement and its DOM element ID will be available in jqElementId
widgetEvents()	A collection of events.
warnIfNotBound	true or false; If true, the property will be checked by Composer to determine whether it is bound, then generate a to-do item if/when it is not.
widgetServices()	A collection of services.
warnIfNotBound	true or false; If true, the property will be checked by the Composer to determine whether it is bound, then generate a to-do item if/when it is not.
afterRender()	Called after the HTML fragment is inserted into the DOM.
beforeDestroy()	Called right before the widget’s DOM element gets removed and the widget is detached from its parent widget and delocated; this is the place in which to perform any clean-up of resources (e.g. plugins, event handlers) acquired throughout the lifetime of the widget.
beforeSetProperty(name,value) [Mashup Builder only - not at runtime]	Called before any property is updated within Composer; this is a good place to perform validation on the new property value before it is committed. If a message string is returned, then the message will be displayed to the user, and the new property value will not be committed. If nothing is returned, then the value is assumed to be valid.
afterSetProperty(name,value) [Mashup Builder only - not at runtime]	Called after any property is updated within Composer. Return true to have the widget re-rendered in Composer.
afterAddBindingSource(bindingInfo)	Whenever data is bound to the widget, you will call back with this (if you implemented it … it’s optional). The only field in bindingInfo is targetProperty which is the propertyName that was just bound.
validate()	Called when Composer refreshes its to-do list. The call must return an array of result objects with severity (optional and not implemented) and message (required) properties. The message text may contain one or more pre-defined tokens, such as {target-id}, which will contain a hyperlink that allows the user to navigate to or select the specific widget that generated the message.

Properties Section Breakdown

The following attributes can be specified for each property object:

Aspect Description

description	A description of the widget, which is used for its tooltip.
baseType	The system base type name - if the baseType value is FIELDNAME the widget property window displays a dropdown list of fields available in the INFOTABLE bound to the sourcePropertyName value based on the baseTypeRestriction.
mustImplement	If the baseType is THINGNAME and you specify “mustImplement”, the Mashup Builder will restrict popups to those implementing the specified EntityType and EntityName [by calling QueryImplementingThings against said EntityType and EntityName].
baseTypeInfotableProperty	If baseType is RENDERERWITHFORMAT, baseTypeInfotableProperty specifies which property’s infotable is used for configuration.
sourcePropertyName	When the property’s baseType is FIELDNAME, this attribute is used to determine which INFOTABLE’s fields are to be used to populate the FIELDNAME dropdown list.
baseTypeRestriction	When specified, this value is used to restrict the fields available in the FIELDNAME dropdown list.
tagType	If the baseType is TAGS this can be ‘DataTags’ (default) or ‘ModelTags.’
defaultValue	Default undefined; used only for ‘property’ type.
isBindingSource	true or false; Allows the property to be a data binding source, default to false.
isBindingTarget	true or false; Allows the property to be a data binding target, default to false.
isEditable	true or false; Controls whether the property can be edited in Composer, default to true.
isVisible	true or false; Controls whether the property is visible in the properties window, default to true.
isLocalizable	true or false; Only important if baseType is STRING - controls whether the property can be localized or not.
selectOptions	An array of value / (display) text structures.
warnIfNotBoundAsSource	true or false; If true, the property will be checked by Composer to determine whether it is bound and generate a to-do item if/when it is not.
warnIfNotBoundAsTarget	true or false; If true, the property will be checked by Composer to determine whether it is bound and generate a to-do item if/when it is not.

Other Special BaseType

Additional special baseTypes:

STATEDEFINITION - Picks a StateDefinition
STYLEDEFINITION - Picks a StyleDefinition
RENDERERWITHSTATE - Displays a dialog and allows you to select a renderer and formatting. Note: You can set a default style by entering the string with the default style name in the defaultValue. When your binding changes, you should reset it to the default value, as shown in the code below:

this.afterAddBindingSource = function (bindingInfo) {
    if(bindingInfo['targetProperty'] === 'Data') {
        this.resetPropertyToDefaultValue('ValueFormat');
    }
};

STATEFORMATTING - Displays a dialog and allows you to pick a fixed style or state-based style. Note: You can set a default style by entering the string with the default style name in the defaultValue. When your binding changes, you should reset it to the default value as shown in the code above for RENDERERWITHSTATE.
VOCABULARYNAME - Will pick a DataTag vocabulary

Some Examples

An example of the properties property:

properties: {
    Prompt: {
        defaultValue: 'Search for...',
        baseType: STRING,
        isLocalizable: true
    }, 

    Width: {
        defaultValue: 120
    },

    Height: {
        defaultValue: 20,
        isEditable: false
    },
}

An example of mustImplement:

'baseType': 'THINGNAME',
'mustImplement': {
    'EntityType': 'ThingShapes',
    'EntityName': 'Blog'
}

An example of selectOptions:[

    {value: ‘optionValue1’, text: ‘optionText1’}, 
    {value: ‘optionValue2’, text: ‘optionText2’}
]

An example of validate function that allows you to navigate/select the specific widget that generated the message:

this.validate = function () {
    var result = [];
    var srcUrl = this.getProperty('SourceURL');

    if (srcUrl === '' || srcUrl === undefined) {
        result.push({ severity: 'warning', message: 'SourceURL is not defined for {target-id}'});
    }

    return result;
}

Click here to view Part 3 of this guide.