Skip to main content

General Features

Widget Configurator

Every IQNOX widget comes with a style configurator. Selecting an IQNOX Widget will add a button at the top of the widget properties panel.

Configurator button or Configurator button dropdown

When clicking the configurator button you will be prompted with a pop-up on top of the mashup builder. The configurator has several sections.

info

The configurator has multi-window capabilities.

Configurator Sections

  1. Widget Display Name An easy way to manage the . The configurator will show the DisplayName of the widget so you can more easily identify which widget are you modifying.
  2. TemplateStore - which template store is used on the mashup.
  3. Template Management: Here you can create, duplicate, delete, or change the current template that is being used. The ••• menu will have the options to Add, Duplicate, Delete and Modify the CSS of the selected template.
  4. State Formatting - change appearance of widgets based on data with the help of a query builder.
  5. Styling controls holds all of the controls, broken into collapsible subsections, that can be used to change different style properties of your widget.
  6. Live Preview: This area shows a real-time update of what the widget looks like as you change the controls in the configuration tab.
  7. Control Panel: Some IQNOX widgets have controls to toggle certain widget states (ex: disabled state on a button) to help preview some of your template changes. Each widget will have a different set of controls available.
  8. Preview Widget Background color picker - will change the background of the container for the widget preview. This is a temporary setting and will not reflect in the final design. Mostly used for testing how some colors look on different backgrounds.
  9. Done: Whenever you are finished editing a template you can choose to save your changes by clicking Done or cancel them by pressing the X button on top right.
  10. Confirmation Dialogue: it will prompt when the user has done some changes and presses X (close), to whether Save the changes, Cancel closing the Configurator or Don't Save which reverts the latest changes and closes the Configurator, this action cannot be undone.

Configurator overview Save changes confirmation

History support

In v3.5.0 along with the new look for the configurator, we've added history support. This means that each action you do in the configurator can be reverted. Useful for testing different styles and experimenting. History Support

Multi-window

In v3.3.0 we have added multi-window support, this feature allows users to have multiple configurator windows open, to resize them, and to move them around. This comes in handy when users want to copy colors or settings from another template.

These windows can be minimized, maximized by double clicking on an empty area in the header and closed from top right.

If the same template is used on 2 different widgets and the configurator is opened on both, the changes will reflect live from one to the other.

Multi-window

Example for minimized windows

Multi-window-minimized

States

From v3.4.0 all widgets which have states like hover, active, focus, selected, disabled, checked, unchecked, etc, will have an easier way to customize them. Configurator States

tip

If a state is not applied, it will have the same value as the default state.

The states can be saved as sets to use on other widgets. Ex: customizing a PrimaryButton and saving the states to load up in a guide widget which also has buttons.

Dynamic States Apply Set

Concurrent changes

We've implemented a Save conflict prompt so that users of the same ThingWorx instance can avoid stepping on each other's toes. This will show users that since they opened the configurator and edited a template if somebody else has been modifying the same template and saved it.

The user can choose whether to Use Local changes to the template edited by them or accept and Use Remote to accept the changes made by some other user on the platform. Who and when the template was modified is going to be shown up top in the message. Save conflict prompt

Template Property

The template property of every IQNOX widget can be changed from the properties panel of the mashup builder or from the configurator in the top section using the provided dropdown.

Template Property

Template Dropdown

The template can also be changed at runtime using the Template binding. Using bindings you can dynamically drive how a widget looks based on other conditions in your application.

Template inheritance

This feature allows users to have multiple Template Store Things and have a link between them. Now Template Stores have a property ParentTemplateStore which can be set to inherit widget templates from another Template Store Thing. Parent Template Store

This feature is useful when companies have multiple teams developing multiple applications and want one style guide to not be changed by anyone, only the Template Store which inherits the parent has editable templates, just like before.

For example, an company-wide Template Store Thing can be developed storing the enterprise style guidelines. Then, when a new project starts up, the development team would create a new Template Store Thing specific to that project, and set the ParentTemplateStore to the company-wide Store. That project can mix and match using the company-widget templates or templates that are project-specific.

To ensure that developers do not select the company-widget Template Store Thing as their template store in the mashups, is properties can be marked as read only. The configurator will show all templates originating from readonly properties as not editable. Parent Template Store Readonly

The ParentTemplate store templates are read-only, this is represented by a yellow info bar up top with a Duplicate button on it, and all controls for changing the style of the widget are disabled. Parent Template Store

This the list below we have our Child Template Store "MyAwesomeTheme". These will always be the first to show in the list.

The list under "TestStyles" are the templates from the ParentTemplateStore Thing.

List Inherited Templates

Bindings

Every IQNOX widget comes with a set of input and/or output bindings. All of the common bindings that you would find in a standard ThingWorx widget are available on the IQNOX widgets, however, additional bindings have been added to improve the mashup design process.

bindings

State Formatting BETA

State formatting is the concept of varying the visual styling of a widget depending on the data.

When using the IQNOX Widgets, the developer has two options on how to implement state formatting on a widget:

  1. Having external logic drive the value of the Template property of the widget. This effectively means that, through bindings, the styling of the widget can be changed. Note that multiple Templates need to be created.
  2. Use the new State Formatting BETA feature. This enables "overriding" certain style properties based on the data displayed by the widget. Complex rules can be created, enabling advanced state formatting.

This section covers using the second type of state formatting.

The following widgets are supported for now: Label, Bar Chart, Pie Chart, Map, and Line Chart. Support for more widgets will be coming in future releases.

note

The current version of the State formatter is BETA. This means that we are waiting to see how developers use it, and based on their feedback we will make the final changes to it. We do not expect to make any changes that break existing configurations.

State formatting is done by creating formatting rules. A formatting rule is made up of two parts:

  • conditions: A "filter" clause built out using an UI query builder, with support for nested AND/OR groups, that represents what conditions the data must match in order for the formatting to be applied. Conditions can reference any of the columns of the data that was bound into the widget.
  • formatting rules: One or more "overrides" on top of the existing template that will apply whenever the conditions are evaluated to true.

On compatible widgets, the state formatting button can be found near the Configurator button.

State formatting button

State formatting is applied on a per widget basis and will be copied along with the widget if it's copied in some other part of the mashup or other mashups.

When rules are created in the state formatting tab, the number of rules will appear on the button.

State formatting rules number

Clicking the button will open the same Configurator window but on the State Formatting tab. This tab is only available for supported widgets.

State formatting

The left side will contain the rule list, which can be duplicated, deleted, and moved. The rules are evaluated in a descending order, meaning that the next rule will overwrite the previous one.

The Save as Rule Set button will prompt you with an input to give the rule set a name, which can later be used in other widgets of the same type with the Load Rule Set button and selecting a rule set from the dropdown list.

When defining the condition for the rules, the first dropdown will reflect the datashape or value bound to the widget.

The + Add style button will prompt the users with a dropdown to add a style that they want to be modified.

Add style for Label widget

For example: Text color #000000 in the template will be overwritten by the Text color set in here. The rest of the styling will be the one set in the Template.

At the moment only some of the most important styling options are added, more can be added based on user feedback.

State formatter dynamic thresholds

note
RuleSet format:

In order to use dynamic threshold values, the configuration JSON must be bound to RuleSet property.

Replaced static values with variables must be converted to string.

Example for myThreshold variable:

   [
{
"name": "My Threshold",
"id": "5767bcca-d61c-40b5-b6df-c1635889e397",
"combinator": "and",
"rules": [
{
"id": "b4dd495e-95d9-4664-a37a-22d1b028c015",
"field": "value",
"operator": "<",
"valueSource": "value",
"value": myThreshold.toString(),
"path": [
0
],
"baseType": "NUMBER"
}
],
"style": {
"generalSettings": {
"defaultColors": [
"#FF4500"
]
},
"yAxis": {
"line": "1px solid #FF4500"
},
"thresholds": {
"textColor": "#FF4500"
}
},
"selectedStyleOptions": [
[
"generalSettings",
{
"rows": [
{
"items": {
"defaultColors": {
"context": "Markers,Region",
"displayName": "Default Colors",
"type": "COLOR_PALETTE",
"baseType": "COLOR_PALETTE"
}
}
}
]
}
],
[
"yAxis",
{
"rows": [
{
"items": {
"line": {
"context": "Region",
"displayName": "Line",
"type": "BORDER_EDITOR",
"baseType": "BORDER_CSS",
"flex": 1,
"defaultValue": "1px solid #d9d9d9"
}
}
}
]
}
],
[
"thresholds",
{
"rows": [
{
"items": {
"textColor": {
"context": "Region",
"displayName": "Text color",
"type": "COLOR_PICKER",
"baseType": "COLOR",
"flex": 2,
"defaultValue": "#353535"
}
}
}
]
}
]
],
"context": "Region"
}
]

If the operator is between/not between , value must be format like this 'value1,value2'

The default operator list is below.

[
{ name: "=", label: "=" },
{ name: "!=", label: "!=" },
{ name: "<", label: "<" },
{ name: ">", label: ">" },
{ name: "<=", label: "<=" },
{ name: ">=", label: ">=" },
{ name: "contains", label: "contains" },
{ name: "beginsWith", label: "begins with" },
{ name: "endsWith", label: "ends with" },
{ name: "doesNotContain", label: "does not contain" },
{ name: "doesNotBeginWith", label: "does not begin with" },
{ name: "doesNotEndWith", label: "does not end with" },
{ name: "null", label: "is null" },
{ name: "notNull", label: "is not null" },
{ name: "in", label: "in" },
{ name: "notIn", label: "not in" },
{ name: "between", label: "between" },
{ name: "notBetween", label: "not between" },
];

How rules are applied

Rules are applied in descending order, meaning that the last rule to match will override the previous ones.

Example

Styling a label with state formatting with 4 different styles and values from 1-100. The following rules can be created.

  1. <= 100
  2. <= 75
  3. <= 50
  4. <= 25

Theme Editor

The Theme Editor is a new feature in version 3.7 that makes it possible to edit all of the templates in a template store without requiring widgets of the appropriate types to be created in advance. Unlike the regular template editors, you can edit multiple templates and save them in bulk.

The theme editor looks similar to the regular widget template editors but gains an extra sidebar that can be used to select the widget type whose templates to edit.

Theme Editor

After making changes to a template, a different template or widget can be selected without having to commit or discard the changes to that template. The theme editor will show a badge over the save button indicating how many templates have unsaved changes. Pressing that button will cause all of those templates to be saved in bulk:

Theme Editor save badge

Next to the save button, there is a menu button that contains a few additional features:

  • A toggle for live updates
  • A link to the downloads page for the IQNOX Widgets
  • A link to this documentation

Theme Editor overflow menu

Global Styling

Not all widgets need to have a virtually infinite number of templates, but we do need to style however we want.

That is how the Global Styling got made. For UI elements such as Tooltip which need to be consistent throughout the whole app.

The Global Styling tab can be accessed via the theme editor button on top of any mashup and switching to the Global Styles tab.

Advanced Tooltip

It replaces all the tooltips set from the Tooltip property on widgets that support it. These tooltips will now have a custom styling and can be customized however the developer wants from the Global Styling tab.

The tooltip can be interacted with if the user hovers from the target widget to the tooltip directly. Useful for copying text from the tooltip or hovering to seeing values on a LineChart tooltip.

Tooltips now can be of four types:

  • Text - also the default option. Text will show based on the settings in the Global Styling and wrap based on the Max width set.
  • HTML - any HTML code that can be written with inline styles.
  • Markdown - As with any documentation nowadays, Markdown is one of the best way to display information. Basic syntax.
  • Mashup - A ready to use mashup, that works exactly like a navigation mashup, with parameters which can be bound to data.

The TooltipAnchor can be set to one of the following values:

  • Widget: default if not set. Current positioning behavior.
  • Pointer: When set, the tooltip is positioned around the mouse pointer. Useful for widgets that occupy a larger part of the screen (like the gauge).
note

TooltipHeight Can be set only on TooltipType Markdown or Mashup

TooltipWidth Is available on all TooltipType

Global Styling for tooltip will give the ability to set a maximum width to the Text and HTML tooltips.

Global Styling

Tooltip Examples

TooltipsExamples

Global CSS

A way to store the CSS that will be applied everywhere the same TemplateStore is used. This way the developer can make sure that CSS code is not duplicated and The CSS editor can be accessed from the theme editor button in the Mashup Builder.

In v3.2.0 we have introduced Monaco Editor as the code editor for CSS. The same code editor that powers VS Code. This will provide better formatting, autocomplete and it will also resume on the line you were editing last.

Open Theme Editor

Global CSS Editor

Live Updates

Accessible from the theme editor overflow menu is a toggle for enabling or disavling live updates. Enabling live updates causes it to only apply to the current browser and does not affect other users or browsers. When enabled, live updates causes any change made in any theme editor or any other configuration window to be synced with all other open browser tabs or windows. Additionally, any changes will be instantly reflected in any runtime tab or window enabling developers to see how their changes would look like in the running app without having to save or reload.

To enable live updates, use the overflow menu in the theme editor and select the Live Updates item. A warning will appear that the feature was enabled, but all thingworx browser tabs needs to be reloaded. The Reload Now button may be used for the current composer tab, but any other tabs must be reloaded manually for the change to take effect.

Live Updates Warning

To disable live updates, use the same menu item. Just like with enabling, it is required to reload any open thingworx tabs or windows for the change to take effect.

Send to runtime

When live updates are enabled, the theme editor gains a new feature called Send to runtime, available next to the save button.

Send to Runtime

Pressing this button causes the theme editor to close in the current composer window, but one will open in any locally open runtime instance of your mashups. The runtime theme editor functions the same as it does in composer, except that it no longer has the preview area, because any change is instaly reflected in the running mashup. Beyond that, all other features of the theme editor are available. Developers can edit any templates, template CSS, global styles or global CSS that they can in composer and any change they do here will be synced back to the composer and vice versa. Saving changes from this runtime theme editor is also supported.

Runtime Theme Editor

To make it easier to determine which templates are used in a mashup so that they can be modified, the runtime theme editor contains an additional Select widget button. When this is pressed, the theme editor minimizes and the developer can then select any IQNOX widget in the mashup. A message indicating this will appear on the screen. When one is selected, the theme editor reappears with the template used by that widget selected for modification.

Runtime Theme Editor

Finally, the runtime theme editor has an additional feature to permanently dock the editor window to a side of the screen. This is available in the menu and replaces the Live Updates item available in composer. The following options are available:

  • Window which is the default mode
  • Dock Left causes the theme editor to appear as a sidebar anchored to the left of the screen
  • Dock Right causes the theme editor to appear as a sidebar anchored to the right of the screen

Icon Selector

A modal popup in which the developer can search through 4 icon fonts and media entities. Search for the icon fonts is contextual, the user doesn't have to search for the exact name of the icon. Clicking the desired icon will copy a line of code that can be pasted into any IconURI property of widgets that support icon settings.

Modal can be opened from a star button near the Copy/Paste buttons in the Mashup Builder.

Icon Selector Button

Icon Selector

Format Complex

Format Complex is a powerful tool that was developed for easy formatting of different properties across multiple Widgets. It can be used to format numbers and dates, and can also be used to wrap formatted or unformatted values with a string. Here are instructions for each case:

  1. Number formatting, expressed in the "standard ThingWorx way":

    • 0 - (123457) show only digits, no precision
    • 0.00 - (123456.79) shows only digits, 2 precision
    • 0.0000 - (123456.7890) shows only digits, 4 precision
    • 0,000 - (123,457) show comma and digits, no precision
    • 0,000.00 - (123,456.79) show comma and digits, 2 precision
    • 0,0.00 - (123,456.79) shortcut method, show comma and digits, 2 precision 0.00
  2. DateTime formatting, expressed in the "standard ThingWorx way":

LetterDate or Time ComponentPresentationExamples
GEra designatorTextAD
yYearYear1996; 96
YWeek yearYear2009; 09
MMonth in year (context sensitive)MonthJuly; Jul; 07
LMonth in year (standalone form)MonthJuly; Jul; 07
wWeek in yearNumber27
WWeek in monthNumber2
DDay in yearNumber189
dDay in monthNumber10
FDay of week in monthNumber2
EDay name in weekTextTuesday; Tue
uDay number of week (1 = Monday, ..., 7 = Sunday)Number1
aAm/pm markerTextPM
HHour in day (0-23)Number0
kHour in day (1-24)Number24
KHour in am/pm (0-11)Number0
hHour in am/pm (1-12)Number12
mMinute in hourNumber30
sSecond in minuteNumber55
SMillisecondNumber978
zTime zoneGeneral time zonePacific Standard Time; PST; GMT-08:00
ZTime zoneRFC 822 time zone-0800
XTime zoneISO 8601 time zone-08; -0800; -08:00

Examples:

Date and Time PatternResult
yyyy.MM.dd G 'at' HH:mm:ss z2001.07.04 AD at 12:08:56 PDT
EEE, MMM d, ''yyWed, Jul 4, '01
h:mm a12:08 PM
hh 'o''clock' a, zzzz12 o'clock PM, Pacific Daylight Time
K:mm a, z0:08 PM, PDT
yyyyy.MMMMM.dd GGG hh:mm aaa02001.July.04 AD 12:08 PM
EEE, d MMM yyyy HH:mm:ss ZWed, 4 Jul 2001 12:08:56 -0700
yyMMddHHmmssZ010704120856-0700
yyyy-MM-dd'T'HH:mm:ss.SSSZ2001-07-04T12:08:56.235-0700
yyyy-MM-dd'T'HH:mm:ss.SSSXXX2001-07-04T12:08:56.235-07:00
YYYY-'W'ww-u2001-W27-3
  1. Complex formatting: Be able to specify a more complex formatting template, for example, to use to display units. This works by specifying a format where the intended value is enclosed in [[ and ]]. Inside the brackets, you can either specify value if you don't want the value to be changed or a format defined above if it needs to be formatted.

Examples:

  • prefix [[value]] suffix: Creates the displayed string by concatenating the string prefix with the bound value of the widget, and the value suffix. This can be used when the bound value is a plain string. Will result in prefix INPUT_VALUE suffix.
  • [[0.0]]% (23.4%): appends a % to a 0.0 formatting
  • $[[0]] ($23): prepends a $ to a 0 formatting
  • weight: [[0,0.00]] Kg will result in weight: 123,456.79 Kg
  • time: [[relative:]] will result in time: 5 hours ago

note

Due to ThingWorx platform changes and how localization tokens are handled in 9.4 and earlier, some formatting settings might turn into ??? . For that, we also allow the following syntax.

Examples:

  • prefix ((value)) suffix: Creates the displayed string by concatenating the string prefix with the bound value of the widget, and the value suffix. This can be used when the bound value is a plain string. Will result in prefix INPUT_VALUE suffix.
  • ((0.0))% (23.4%): appends a % to a 0.0 formatting
  • $((0)) ($23): prepends a $ to a 0 formatting
  • weight: ((0,0.00)) Kg will result in weight: 123,456.79 Kg
  • time: ((relative:)) will result in time: 5 hours ago