Widgets

A widget is the smallest functional element in a workflow file. It displays text, images, Design Editor, some options, and so on. They also send and receive some requests.

Widgets are embedded in panels of a step definition. In a workflow file, you describe widgets in a separate section, and then you embed them in steps like this.

{
    "widgets": [ 
        {
            "name": "my-widget", 
            ...
        }
    ],
    "steps": [
        {
            "name": "Step 1",
            "mainPanel: { "name": "my-widget" }
        }
    ]
}

Note

To learn more about the place of widgets in the structure of a workflow file, read the Structure article.

Widgets anatomy

All the widgets have the same elements. Let's consider them.

Parameter	Function
Type	A widget to be loaded. For example, checkbox or input-text.
Name	A widget identifier in a workflow file.
Title	A caption displayed in the interface over a widget.
Prompt	A hint explaining the usage of the widget. This is an optional parameter.
Description	Hidden tips with explanation for a customer. This is an optional parameter.
Params	Settings defining behavior of a widget. They may contain dynamic expressions, which return the true or false values.

These elements can be visualized as follows:

Here the numbers are:

1. title
2. prompt
3. description
4. A widget body defined through params

Now, let's see how you can define widgets.

Examples

Button widget

To create the following Button widget

You can add the following description to your workflow file.

{
    "name": "my-button",
    "type": "button",
    "params": {
        "text": "Click"
    }
}

Dynamic expressions

To make a workflow self-updating, use dynamic expressions. To learn more about the dynamic expressions, read the Dynamic expressions article.

Note

As for widgets, you can embed dynamic expressions only in params of a widget.

To illustrate dynamic expressions, let's create two widgets: one for entering text, say, my-input, and another widget for displaying the entered text, say, a my-text widget.

To implement this behavior, the my-text widget must refer to the value of my-input widget as follows:

{
    "name": "my-input",
    "type": "input-text",
    "title": "Input your text",
    "params": {
        "isTextArea": true
    }
},
{
    "name": "my-text",
    "title": "Get your text",
    "type": "static-text",
    "params": {
        "text": "{{$['my-input']._}}"
    }
}

Non-visual widgets

There are widgets which aren't displayed in the user interface. In the following example, the result of selecting a checkbox will be printed in the browser console.

{
    "widgets": [
        {
            "name": "my-checkbox",
            "type": "checkbox",
            "params": {
                "prompt": "I approve the design.",
                "value": false
            }
        },
        {
            "name": "my-trigger",
            "type": "function-trigger",
            "params": {
                "arguments": [
                    "{{ $['my-checkbox']._ }}"
                ],                
                "callback": [
                    "{{ #function(myValue) console.log('My checkbox value is ' + myValue) }}"
                ]
            }
        }
    ]
}

Widgets types

As you can mention from the examples above, all the widgets are divided into two groups: visual and non-visual. The visual widgets display Design Editor, a text, images, mockups, and so on. Non-visual widgets can exchange data with a server or manage the condition of workflow elements, which aren't widgets.

The other concept of widget types is in creating dynamic expressions.

Using values of params

If you want to use a value from widget1 in widget2, you can refer to the param you need by using dynamic expressions like this: "{{$['widget1'].params1}}".

{
    "widgets": [
        {
            "name": "widget1",
            "title": "My widget",
            "type": "...",
            "params": {
                "params1": 2
            }
        },
        {
            "name": "widget2",
            "type": "...",
            "params": {
                "text": "{{$['widget1'].params1}}"                 
            }
        }
    ]        
}

The other widgets have a value that is selected or changed by a customer. For example, they are input-text, checkbox, gallery, option, and so on.

In the following example, widget2 refers to the value of input-text. To get this value, just use the ._ syntax, not params name.

{
  "widgets": [
    {
      "name": "my-input",
      "type": "input-text",
      "title": "Input your text",
      "params": {
        "isTextArea": true
      }
    },
    {
      "name": "widget2",
      "type": "...",
      "params": {
        "text": "{{$['widget1']._}}"
      }
    }
  ]
}

---

To learn more details about dynamic expressions, read the Dynamic expressions article.Read the following articles to know more about each widget.

In this chapter