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.
When clicking the configurator button you will be prompted with a pop-up on top of the mashup builder. The configurator has several sections.
Configurator Sections
- Window Controller An easy way to manage the multi-window capabilities of of the configurator. This can be grabbed to move the window around in ThingWorx.
- Left side is the widget name.
- Right side is the TemplateStore thing name on which the changes will be made and the window controls: minimize, maximize and close.
- Configurator Tabs
- Configurator - a window in which all IQNOX widget can be styled
- State Formatting - change appearance of widgets based on data with the help of a query builder
- Global Styling - a way to style global UI elements such as the tooltip
- Global CSS - a CSS code editor
- Preview Widget Background color picker - will change the background of the container for the widget preview
- Template Management: Here you can create, duplicate, delete, or change the current template that is being used.
- Template Configuration Tab: This tab holds all of the controls, broken into collapsible subsections, that can be used to change different style properties of your widget.
- Custom CSS Tab: This tab is where custom CSS code for a specific template can be added. Note: This custom CSS code will only take effect if there is an instance of a widget with that specific template somewhere on the current mashup.
- Live Preview: This area shows a real-time update of what the widget looks like as you change the controls in the configuration tab.
- 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.
- Save and Cancel Changes: Whenever you are finished editing a template you can choose to save or cancel your changes.
Multi-window
In v3.3.0 we've added multi-window support, which will allow users to have multiple configurator windows open, resize them, move them around. This comes in handy when users want to copy colors or settings from another template.
These windows can be minimized, maximized and closed from top right. Double clicking the top bar will maximize the window.
Example for minimized windows
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.
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.
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 Template Management section using the provided 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.
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.
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:
- 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 multipleTemplates
need to be created. - 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.
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 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.
Clicking the button will open the same Configurator window but on the State Formatting tab. This tab is only available for supported widgets.
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.
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
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 allows applied in descending order, meaning that the last rule to match will override the previous ones.
Styling a label with state formatting with 4 different styles and values from 1-100. The following rules can be created.
<= 100
<= 75
<= 50
<= 25
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 by opening the Configurator from any widget.
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 4 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
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.
Tooltip Examples
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 button near the Copy/Paste buttons 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.
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.
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:
Number formatting, expressed in the "standard ThingWorx way":
0
- (123457) show only digits, no precision0.00
- (123456.79) shows only digits, 2 precision0.0000
- (123456.7890) shows only digits, 4 precision0,000
- (123,457) show comma and digits, no precision0,000.00
- (123,456.79) show comma and digits, 2 precision0,0.00
- (123,456.79) shortcut method, show comma and digits, 2 precision0.00
DateTime formatting, expressed in the "standard ThingWorx way":
relative:
- usesmoment.fromNow
(see https://momentjs.com/docs/#/displaying/fromnow/)- any date format expressed as
java.text.SimpleDateFormat
(see https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html) - example:
dd-MM-YYY
will result in 23-05-2021
Letter | Date or Time Component | Presentation | Examples |
---|---|---|---|
G | Era designator | Text | AD |
y | Year | Year | 1996; 96 |
Y | Week year | Year | 2009; 09 |
M | Month in year (context sensitive) | Month | July; Jul; 07 |
L | Month in year (standalone form) | Month | July; Jul; 07 |
w | Week in year | Number | 27 |
W | Week in month | Number | 2 |
D | Day in year | Number | 189 |
d | Day in month | Number | 10 |
F | Day of week in month | Number | 2 |
E | Day name in week | Text | Tuesday; Tue |
u | Day number of week (1 = Monday, ..., 7 = Sunday) | Number | 1 |
a | Am/pm marker | Text | PM |
H | Hour in day (0-23) | Number | 0 |
k | Hour in day (1-24) | Number | 24 |
K | Hour in am/pm (0-11) | Number | 0 |
h | Hour in am/pm (1-12) | Number | 12 |
m | Minute in hour | Number | 30 |
s | Second in minute | Number | 55 |
S | Millisecond | Number | 978 |
z | Time zone | General time zone | Pacific Standard Time; PST; GMT-08:00 |
Z | Time zone | RFC 822 time zone | -0800 |
X | Time zone | ISO 8601 time zone | -08; -0800; -08:00 |
Examples:
Date and Time Pattern | Result |
---|---|
yyyy.MM.dd G 'at' HH:mm:ss z | 2001.07.04 AD at 12:08:56 PDT |
EEE, MMM d, ''yy | Wed, Jul 4, '01 |
h:mm a | 12:08 PM |
hh 'o''clock' a, zzzz | 12 o'clock PM, Pacific Daylight Time |
K:mm a, z | 0:08 PM, PDT |
yyyyy.MMMMM.dd GGG hh:mm aaa | 02001.July.04 AD 12:08 PM |
EEE, d MMM yyyy HH:mm:ss Z | Wed, 4 Jul 2001 12:08:56 -0700 |
yyMMddHHmmssZ | 010704120856-0700 |
yyyy-MM-dd'T'HH:mm:ss.SSSZ | 2001-07-04T12:08:56.235-0700 |
yyyy-MM-dd'T'HH:mm:ss.SSSXXX | 2001-07-04T12:08:56.235-07:00 |
YYYY-'W'ww-u | 2001-W27-3 |
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 specifyvalue
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 stringprefix
with the bound value of the widget, and the valuesuffix
. 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 a0.0
formatting$[[0]]
($23
): prepends a $ to a0
formattingweight: [[0,0.00]] Kg
will result in weight: 123,456.79 Kgtime: [[relative:]]
will result in time: 5 hours ago
- Examples: