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.
View full tip
