Functions Available for Customizing ThingWorx Widgets
This section describes the functions available for widgets.
Widget Lifecycle in the Mashup Builder
A widget has the following lifecycle in the Mashup Builder. In each lifecycle state, the Mashup Builder calls the following functions that are available for widgets:
• Discovered
The widget is loaded in index.html and added to the widget toolbar or palette.
|
Function
|
Description
|
|---|---|
|
widgetProperties()
|
Get information about every widget in the mashup. Information such as display name and description is retrieved.
|
|
widgetEvents()
|
Get information about the events that are exposed by every widget.
|
|
widgetServices()
|
Get information about the services that are exposed by every widget.
|
• Created
The widget is added on the mashup panel.
|
Function
|
Description
|
|---|---|
|
afterload()
|
Called after your object is loaded and properties have been restored from the file, but before your object has been rendered.
|
• Appended
The widget is appended to the workspace DOM element.
|
Function
|
Description
|
|---|---|
|
renderHtml()
|
Get the HTML fragment that is inserted in the mashup DOM element.
|
|
afterRender()
|
Called after the HTML fragment representing the widget is inserted in the mashup DOM element and a usable element ID is assigned to the DOM element holding the widget content. After this, the DOM element is ready to be manipulated.
|
• Updated
The widget is resized or updated in the widget property window.
|
Function
|
Description
|
|---|---|
|
beforeSetProperty()
|
Called before a widget property is updated.
|
|
afterSetProperty()
|
Called after a widget property is updated.
|
• Destroyed
The widget is deleted from the mashup.
|
Function
|
Description
|
|---|---|
|
beforeDestroy()
|
Called before the DOM element of the widget is removed, and the widget is detached from its parent widget and deallocated. You should free the resources such as plugins and event handlers that are acquired during the lifetime of the widget. To support reloading the widget in a lazily loaded container, you must add the domOnly argument to the beforeDesctroy() function and then only destroy the widget when the value is false. Not using the domOnly argument prevents the widget form reloading correctly. For more information, see Using Lazy Loading in a Mashup.
|
Property Bag
Property bag is a set of name-value pairs. Each pair is a simple value store. ThingWorx uses property bags as a structure persistence mechanism for mashups.
Mashup Builder APIs Available for Widgets
The following APIs can be accessed by a widget in the context of the Mashup Builder:
• this.jqElementId—This is the DOM element ID of your object after the widget has been rendered on the HTML page.
• this.jqElement—This is the jQuery element.
• this.getProperty(name)—Retrieves the name of the property.
• this.setProperty(name,value)—Every call to this function calls the function afterSetProperty(), if afterSetProperty() is defined in the widget.
• this.updatedProperties()—This function should be called when properties are changed in the widget. After the function is called, the Mashup Builder updates the widget properties window.
• this.getInfotableMetadataForProperty(propertyName)—Gets the infotable metadata for a property that is bound. It returns undefined if the property is not bound.
• this.resetPropertyToDefaultValue(propertyName)—Resets the specified property to its default value.
• this.removeBindingsFromPropertyAsTarget(propertyName)—Removes target data bindings from the specified property.
• this.removeBindingsFromPropertyAsSource(propertyName)—Removes source data bindings from the specified property.
• this.isPropertyBoundAsTarget(propertyName)—Checks if the property is bound as a target. You can use the function to determine if a property has been set or bound. For example, the following sample shows how to use validate() function in the blog widget to determine if a property is bound:
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;
}
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;
}
• this.isPropertyBoundAsSource(propertyName)—Checks if the property has been bound as a source. You can use the function to determine if a property has been bound to a target. For example, the following sample shows how to use the validate() function in the checkbox widget to determine if a property is bound:
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;
}
var result = [];
if (!this.isPropertyBoundAsSource('State') &&
!this.isPropertyBoundAsTarget('State')) {
result.push({ severity: 'warning',
message: 'State for {target-id} is not bound' });
}
return result;
}
Callbacks from Mashup Builder to Your Widget
The following functions on the widget are called by the Mashup Builder to modify the behavior of a widget.
• widgetProperties() [required]—Returns a JSON structure that defines the properties of the widget.
Required properties are:
◦ name—Name of the widget that is displayed in the widget toolbar.
Optional properties are:
|
Property
|
Description
|
|---|---|
|
description
|
Description of the widget, which is used as its tooltip.
|
|
iconImage
|
File name of the widget icon or image.
|
|
category
|
Array of strings that specify the categories under which the widget is available.
For example, Common, Charts, Data, Containers, and so on. This enables the user to filter the widgets by the category type.
|
|
isResizable
|
Specifies if the widget can be resized.
|
|
defaultBindingTargetProperty
|
Name of the property that should be used as the data or event binding target.
|
|
borderWidth
|
If your widget has a border, set this property to the width of the border. The property helps you ensure a pixel-perfect design during the development and at runtime.
For example, consider a widget whose size at runtime should be 10X10 pixels with a border size of 1 pixel. At the design time, the size of the widget should be 8X8 pixels to handle the 1 pixel added at design time. This places the border inside the widget and makes the width and height in the widget properties accurate.
|
|
isContainer
|
Specifies if an instance of the widget can be a container for other widget instances. The valid values are true and false. The default value of the property is false.
|
|
customEditor
|
Name of the custom editor dialog that should be used to set and edit the widget configuration. In your widget project create a dialog box with the name TW.IDE.Dialogs.<name>.
|
|
customEditorMenuText
|
The text that appears on the flyout menu of the widget. It is also the text that appears as the tooltip for widgets in the ThingWorx Composer . For example, Configure Grid Columns.
|
|
allowPositioning
|
Checks if the widget can be placed on a panel. The valid values are true and false. The default value of the property is true.
|
|
supportsLabel
|
Specifies if the widget supports the Label property. The valid values are true and false. The default value of the property is false.
When set to true, the widget exposes a Label property. This property is used to create a text label that appears next to the widget in the ThingWorx Composer and at runtime.
|
|
supportsAutoResize
|
Specifies if the widget automatically supports resizing. The valid values are true and false. The default value of the property is false.
When set to true, the widget can be placed in responsive containers, such as, columns, rows, responsive tabs, and 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 with the name of each object used as the property name. The corresponding attributes control how the property value is set.
For example:
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
The following attributes can be specified for each property object:
|
Attribute
|
Description
|
||||
|---|---|---|---|---|---|
|
description
|
Description of the widget used for its tooltip.
|
||||
|
baseType
|
Base type of the widget. If the base type value is FIELDNAME, the widget property window displays a list of fields available in the infotable. The fields are bound to the sourcePropertyName value based on the base type restriction.
The other special base types are:
• STATEDEFINITION—Selects a state definition.
• STYLEDEFINITION—Selects a style definition.
• RENDERERWITHSTATE—Displays a dialog that enables you to select a data renderer and state formatting.
• STATEFORMATTING—Displays a dialog that enables you to select a fixed style or state-based style.
• VOCABULARYNAME—Selects the data tags vocabulary at runtime.
|
||||
|
mustImplement
|
If the base type is THINGNAME and you specify the mustImplement attribute, the Mashup Builder restricts the dialog box to open only those popups that implement the specified EntityType and EntityName. The Mashup builder calls the function QueryImplementingThings to validate if the value passed is of the type EntityType and checks if EntityName is implemented.
For example:
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
If the base type of the widget is set as RENDERERWITHFORMAT, the attribute specifies which property of the infotable is used for configuration.
|
||||
|
sourcePropertyName
|
If the base type of the widget is set as FIELDNAME, the attribute checks which property of the infotable is used for configuration.
|
||||
|
baseTypeRestriction
|
If this attribute is specified, the value is used to restrict the fields available in the FIELDNAME drop-down list.
|
||||
|
tagType
|
If the base type is set as TAGS, the attribute specifies the tag type. The valid values are DataTags, which is the default value or ModelTags.
|
||||
|
defaultValue
|
Used to set the default value for a property. The default value is undefined.
|
||||
|
isBindingSource
|
Specifies if the property is a data binding source. The valid values are true and false. The default value of the property is fasle.
|
||||
|
isBindingTarget
|
Specifies if the property is a data binding target. The valid values are true and false. The default value of the property is fasle.
|
||||
|
isEditable
|
Specifies if the property is editable in ThingWorx Composer. The valid values are true, which is the default value and false.
|
||||
|
isVisible
|
Specifies if the property is visible in the properties window. The valid values are true and false. The default value of the property is true.
|
||||
|
isLocalizable
|
Specifies if the property can be localized. This attribute is required when the base type is set to STRING. The valid values are true and false.
|
||||
|
selectOptions
|
An array of value or display text structures.
For example:
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer checks if the property is a data binding source. The valid values are true and false.
If the attribute value is set to true, but the property is not bound, ThingWorx Composer generates a list of items that you must complete to save the mashup.
|
||||
|
warnIfNotBoundAsTarget
|
The composer checks if the property is a data binding target. The valid values are true and false.
If the attribute value is set to true, but the property is not bound, ThingWorx Composer generates a list of items that you must complete to save the mashup.
|
• afterLoad() [optional]—The function is called after your object is loaded and properties are restored from the file, but before your object is rendered on the HTML page.
• renderHtml() [required]—The function returns the HTML fragment that ThingWorx Composer places on the screen. The content container of the widget, such as, div, should have a widget-content class specified in it. After this, the container element is appended to the DOM. The container is accessible using the jqElement, and its DOM element ID is available in jqElementId.
• widgetEvents() [optional]—A collection of events; each event can have the following property:
◦ warnIfNotBound—The composer checks if the property is bound. The valid values are true and false.
If the attribute value is set to true, but the property is not bound, ThingWorx Composer generates a list of items that you must complete to save the mashup.
• widgetServices() [optional]—A collection of services; each service can have the following property:
◦ warnIfNotBound—The composer checks if the property is bound. The valid values are true and false.
If the attribute value is set to true, but the property is not bound, ThingWorx Composer generates a list of items that you must complete to save the mashup.
• afterRender() [optional]—The function is called after the HTML fragment is inserted in the DOM.
• beforeDestroy() [optional]—The function is called before the DOM element of the widget is removed and the widget is detached from its parent widget and dellocated. You should free the resources such as plugins, event handlers, and so on, acquired throughout the lifetime of the widget.
• beforeSetProperty(name,value) [optional] [Mashup Builder only - not at runtime]—The function is called before any property is updated in the ThingWorx Composer. You can perform validations on the new property value before it is committed. If the validation fails, you can return a message string to inform the user about the invalid input. The new property value is not be committed. If nothing is returned during the validation, then the value is assumed valid.
• afterSetProperty(name,value) [optional] [Mashup Builder only - not at runtime]—The function is called after any property is updated in the ThingWorx Composer. If you specify the value as true, the widget is rendered again in the ThingWorx Composer after the value is changed.
• afterAddBindingSource(bindingInfo) [optional]—This function is called whenever data is bound to your widget. The only field in bindingInfo is targetProperty, which is the name of the property and is bound.
• validate() [optional]—The function is called when ThingWorx Composer refreshes its to-do list. The call returns an array of result objects:
◦ severity —This is an optional property. The severity of the problem that was detected.
◦ message —This a required property. The message text may contain one or more predefined tokens, such as {target-id}. The message is replaced with a hyperlink that enables the user to navigate and select the specific widget that generated the message.
For example:
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;
}
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;
}