Using Mashup Configuration Forms
A mashup configuration form is a custom mashup used to configure the parameters of another mashup. During design time, this form appears when the configuration icon is selected in the Properties panel of the Contained Mashup widget. You can use mashup configuration forms to make complex mashups easier to reuse and faster to set up. Instead of manually configuring each mashup instance manually, you can create a common configuration form to quickly set specific options, such as filters, thresholds, or display settings. Configuration forms reduce the time that is required for customization and enable you to maintain better consistency across mashup instances. For example, when the same mashup is used in different contexts to display different values. By standardizing options in a form, you can scale your mashup configuration to implement larger solutions with less effort.
Creating a Configuration Form for a Mashup
To add and use a mashup configuration form in Mashup Builder, you must create three mashups:
• Parent mashup—Contains the mashup you want to configure.
 | You can click the configuration icon on the Contained Mashup widget opens the configuration mashup. |
• Contained mashup—A mashup that provides the core functionality or content to be displayed and controlled by the parent mashup. It is the target of the configuration form and must include parameters for dynamic behavior.
• Configuration mashup—The mashup to use for the configuration form. This mashup is the interface for setting parameters that control the behavior of the contained mashup. It must include mashup parameters that are set to Both binding so values can be passed in and out.
• To create the parent mashup:
a. In Composer, navigate to > and create or open a mashup to use as the parent mashup.
b. In Mashup Builder, drag a Contained Mashup widget from the Widgets panel onto the canvas.
c. On the Properties panel, set the widget Name property to the contained mashup.
d. Save the mashup.
The associated configuration form opens when you click the configuration button on the properties panel.
• To create the contained mashup:
a. In Composer, navigate to > and create or open a mashup to use as the contained mashup.
b. In Mashup Builder, define the mashup layout, add widgets, and bind data as needed.
c. In the Explorer panel, select the Mashup node.
d. On the Properties panel, click the Configuration button, then define the mashup parameters.
e. For each parameter, set the Binding direction to Both, then click Done.
f. Set the ConfigurationMashup property to the configuration mashup. This makes the form accessible from the gear icon at design time.
When you set this property, mashup parameters are added to the Properties panel with a ConfigForm prefix.
g. Bind the mashup parameters to widget properties, then save the mashup.
• To create the configuration mashup:
a. In Composer, navigate to > and create a new mashup to use as the configuration form.
b. In Mashup Builder, add input widgets such as the Slider, Checkbox, or Text Field from the Widgets panel. Each widget should correspond to one or more parameters that is defined in the contained mashup.
c. On the Properties panel, click the configuration icon to create mashup parameters that match the ones in the contained mashup. Set each parameter’s Binding direction to Both.
d. Creating bindings between the mashup parameters and the input widgets
Examples: Sample Entities
The following table lists example entities for configuration forms that you can download from the PTC Support site and import into ThingWorx.
Entity Name | Description | Link |
|---|---|---|
MashupBuilder_ConfigurationDialog_CustomExtensionSample.zip | An extension that adds a custom widget and a custom configuration form. | |
MashupConfig-ExampleEntities.xml | Contains sample entities for two separate mashup examples: • A weather mashup. • A simple grid mashup. |
1. In Composer, click > . The Import dialog opens.
2. Under Import Option, select Extension, then import MashupBuilder_ConfigurationDialog_CustomExtensionSample.zip.
3. Change the Import Option to From File, then import MashupConfig-ExampleEntities.xml.
4. Click Refresh in the dialog box to refresh the Composer interface.
The sample entities are imported.
Example: Create Configuration Forms for a Weather Mashup
This example uses example data entities and the following three mashups:
A parent mashup named WeatherCustomDialogExample. It contains a Contained Mashup widget that loads the WeatherInformation mashup. During design time, you can open the configuration dialog by clicking the configuration button on the Properties panel.
A contained mashup named WeatherInformation. This mashup displays weather data that is retrieved from a service. The following image shows how the mashup appears with default settings at runtime.
In the parent mashup, the ConfigurationMashup property of the Contained Mashup widget is set to WeatherConfigMashup. This setting enables the configuration form to appear when you open the configuration dialog. In addition, the associated mashup parameters are listed with a ConfigForm prefix.
A configuration form mashup named WeatherConfigMashup. This mashup defines configurable parameters that control the behavior and content of the WeatherInformation mashup. Each mashup parameter is set to Both binding mode so values can be passed in and out at design time and runtime.
The following image shows the parameters defined for the configuration mashup:
The configuration form includes input widgets that are bound to mashup parameters. These parameters are also bound back to the Contained Mashup widget to ensure that user input is reflected in the main mashup. The following image shows how the widgets, mashup parameters, and WeatherDataConfigMashup are connected.
 | This configuration uses two-way bindings between the widgets and the mashup parameters. This allows the user interface and data to remain synchronized. When a user updates a value in the form, the mashup parameter is updated, and changes to the parameter are reflected in the widget. |
The configuration mashup includes the following widgets:
• The Toggle Button widget—Enables and disables the grid filter.
• The List Shuttle widget—Specifies the columns to display on the widget.
• The Chip Based Data Filter widget—Filters the grid data.
• The Textfield widget—Sets the mashup title.
Example: Creating a Custom Configuration Form Using a Widget Extension
The simple grid example demonstrates how to create a configuration form for a custom widget in Mashup Builder. The form enables users to configure a CountThreshold property and includes the following mashups:
• CustomDialogSupport — A mashup that uses a custom dialog to configure a simple grid.
• RowCountMashupConfigExample — A parent mashup that includes a contained mashup with the InfoTableRows widget.
◦ RowCountContainedMashup — A contained mashup configured using the RowCountMashupConfigForm.
◦ RowCountMashupConfigForm — A configuration form mashup with a Numeric Entry widget that allows users to define the row count threshold.
These mashups show two different approaches for creating configuration forms:
• A standard configuration form using a Contained Mashup widget. For more information, refer to the previous section.
• A custom configuration form that uses the TW.IDE.Dialogs API
The following JavaScript code defines a custom HTML configuration form for the InfoTableRows widget in the ide.js file:
TW.IDE.Widgets.infotablerows = function() {
var thisWidget = this;
TW.IDE.Dialogs['InfoTableRows'] = function() {
return {
afterRender: function() {
$('ux-dialog-container #countThreshold').on('change', (event) => {
thisWidget.setProperty('CountThreshold', event?.target?.value);
});
},
renderDialogHtml: function(widget, opts) {
return `<h2>Info Table Rows</h2>
<i>${widget.getProperty('Description')}</i>
<div>
<form>
<label for="countThreshold">Count-Threshold:</label>
<input type="number" id="countThreshold" name="countThreshold" value="${thisWidget.getProperty('CountThreshold')}">
</form>
</div>`;
}
};
};
this.widgetProperties = function() {
return {
name: 'InfoTableRows',
description: 'InfoTable Row Functions.',
isExtension: true,
functionWidget: false,
iconClass: 'widgets-label',
iconImage: 'label.ide.png',
customEditor: 'InfoTableRows',
customEditorMenuText: 'InfoTable Row config',
properties: {
Input: {
baseType: 'INFOTABLE',
bindingType: 'Property',
bindingDirection: 'Target',
isBindingTarget: true,
isVisible: true,
},
}
};
};
};
The InfoTableRows widget includes a custom dialog that is linked using the customEditor property. During design, you can open the configuration dialog from the widget context menu or using the Properties panel. The form supports bidirectional binding to keep the widget CountThreshold property in sync with user input.
You can use the following properties to bind and configure the configuration dialog:
• customEditor—Specifies the name of the dialog to display for the widget.
• customEditorMenuText—Specifies the label to display for the dialog in the widget context menu.
In this example, the Count-Threshold property determines how many rows must be added before triggering an action in the mashup. The configuration dialog is defined using the TW.IDE.Dialogs API, which enables you to create interactive, HTML-based forms that appear when opening the widget configuration dialog. The form includes a numeric input field for setting the threshold value.
When the user enters a threshold value such as 2 and confirms the change, the widget property is updated. This value can then be used during runtime to trigger events or determine whether specific actions should occur based on the number of rows in the data set. The dialog layout and behavior are defined using custom HTML and JavaScript, without relying on standard ThingWorx widgets. To implement a custom configuration dialog for a widget, perform the following steps:
• Use the TW.IDE.Dialogs API to define the dialog and register it under a unique key by implementing the renderDialogHtml function.
TW.IDE.Widgets.<widget-name> = function() {
var thisWidget = this;
TW.IDE.Dialogs['<widget-name>'] = function() {
return {
renderDialogHtml: function(widget, opts) {
// Add your dialog HTML code in this section.
}
}
}
}
var thisWidget = this;
TW.IDE.Dialogs['<widget-name>'] = function() {
return {
renderDialogHtml: function(widget, opts) {
// Add your dialog HTML code in this section.
}
}
}
}
• Create a form layout using HTML, with input fields for each property. For example, CountThreshold.
• Implement event handlers in the afterRender function to handle user input and update the corresponding widget properties.
• Specify the custom dialog name in the widget customEditor property within the widgetProperties function.
When the configuration dialog is implemented, users can open it from the widget panel, set property values, and apply the configuration.