cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

Community Tip - Did you get an answer that solved your problem? Please mark it as an Accepted Solution so others with the same problem can find the answer easily. X

Create A Mashup Widget Extension Part 2

100% helpful (1/1)

 

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.

Version history
Last update:
‎Feb 23, 2023 08:58 AM
Updated by: