# Status widget

> [HTML Version](status-widget.html)

The widget allows you to display a visual marker on a page, app item form, or task form. For example, an icon of a specific color, short text on a colored background, etc. Users see this marker and pay attention to important information.

The **Status** widget is a universal tool that allows the system administrator to display not only the status of an app item from its page, but also custom text or an icon on a colored background, as well as the value of a variable bound to the widget.

In the widget settings, there are two ways to set define data display:

- Statically: specify a fixed color, text, icon, and background. This way, the user will see a specific visual accent, such as an exclamation point next to an important field.

- Dynamically: link widget settings to context variables. Then, write a script that will automatically change the widget's content and color based on the values of the variables bound to the widget settings. For example, on a page with a list of orders, users see the current order status, each status being assigned a different color. 

The widget can be placed in the sidebar or in the main section of a form or page. To do this, drag it from the right panel of the [interface designer](interface_designer.md) to the modeling canvas or click the **+ Widget** button.

## Configure visual markers using the Status widget

Take a look at this example of a page featuring the **Status** widget. On the page, users can see the order status and initiate the business process. Each stage has its own color:

- **New**: blue.

- **In progress**: yellow.

- **Done**: green.

(status-widget.png)

To achieve this, the system administrator creates a script that links the **Status** widget to data from the **Orders** app context. As a result, the **Status** widget will automatically display the current order status and assign the desired background color.

The configuration involves several steps:

1. [Prepare the page and the app](#page-app) whose items users will interact with on the page.

2. [Create a custom widget](#custom-widget) to display order data: title, status, and a button to initiate the process.

3. Configure the display of current order statuses using the [Status widget](#status-widget-settings).

4. [Bind the statuses](#bind-statuses) set in the **Orders** app context to the **Status** widget settings.

5. [Display a list of orders](#display-statuses) and their statuses on the page.

### Step 1: Prepare the page and app

In our use case, the **Status** widget is configured in the **Work with Orders** workspace. Make sure that in this workspace:

- The **Orders** app has configured [statuses](360009920611.md), and the **Order Processing** business process has been created associated with this app.

- The **List of Orders** page has been added.

### Step 2: Create a custom widget

To display a row with the order title, stage, and a button for processing it on the page, configure a custom widget.

To do this:

1. In the settings of the workspace with the **List of Orders** page, [create a custom widget](interface_settings.md#widgets) called **Order line**.

2. In the interface designer that opens, go to the **Context** tab and create a variable with the following parameters:

- **Display Name\***: **Order**.

- **Property Name\***: `order`.

- **Type\***: **App (one)**.

- **App\***: **Orders**.

3. Go to the **Template** tab and add a **Columns** widget consisting of three columns:

- In the first column, place the **Text Box** widget. In its settings on the **Main** tab, [create and bind](bind-field-to-widget-option.md#new-field) the **Title** context variable with the name code to the **Text** option. This will allow you to retrieve and display the order name.

- In the second column, add the **Status** widget. We'll cover its settings in more detail in the [next step](#status-widget-settings).

- In the third column, add the **Button** widget. In its settings, fill in the fields:

	- **Title / Tooltip\***: **Process order**.

	- **Action type**: **Start Process**.

	- **Business process\***: **Order processing**.

	- **Configure Input Parameters**: to launch a process instance for a specific order, bind the process and widget variables. In the window that opens, in the column with the process name, specify the process variable that stores the **Orders** app, and in the **Context** column, specify the **Order** variable from the widget context created earlier.

4. Save the settings for the custom **Order line** widget.

### Step 3: Configure the Status widget

1. Open the settings for the **Status** widget added in the [previous step](#add-status-widget).

2. In the **Main** tab, fill in the following fields:  
(status-widget-1.png)

- **Text**: the word or phrase the user will see in the widget. You can specify specific text or link it to a context variable so that its current value is displayed in the widget.  
  
In our use case, we'll configure the second option. To do this, click the **(bind_table-icon.png)** icon, then **<Not defined>**, and select **+ Create Field**. In the window that opens, create a variable called **Status Name** with the `statusName` code. We'll use it later in the script and pass the current order status from the **Orders** app context to this variable.

- **Icon**: select an icon that reflects the visual marker you want to show with the widget: an exclamation point, a gear, etc. In our use case, the icon is not required.

- **Type\***: specify whether a background is present:

	- **Primary**: the widget is displayed as a colored block with text and an icon, if specified. For our use case, we'll select this option.

	- **Secondary**: only the specified text and icon are displayed, without a background.

- **Color\***: specify a color for the background and icon. You can choose from the following standard options, each with a specific color assigned by default:

	- **Success**: green.

	- **Warning**: yellow.

	- **Error**: red.

	- **Information**: blue.

	- **Neutral**: gray.

	- **Secondary**: when selecting this option, you can specify one of the custom colors in the separate **Additional Color** field.

The colors may differ from those specified above if you've changed them using [design tokens](design-tokens.md).

You can also bind a context variable to it to configure a dynamic color change. For example, apply the **Success** option when the app item is in the **Done** status, and the **Information** option when it is in the **In Progress** status.

In our use case, we'll use the second option. To do this, click the **(bind_table-icon.png)** icon, then **<Not defined>**, and select **+ Create Field**. In the window that opens, save the variable with the default parameters. A **Color** variable of the **Category** type will appear in the **Context** tab of the interface designer. We'll use it later in the script to determine which background color to display in the widget depending on the order status.

- **Size\***: define the widget size: **Small** or **Standard**. We'll leave the default value, **Standard**.

3. In the **Events** and **System** tabs, you can configure [system settings](common_widget_settings.md) that are common to all widgets. These settings allow you to manage widget visibility and permissions, customize their behavior on hover, and more.  
  
In our use case, these settings are not required.

4. Save the **Status** widget settings.

### Step 4: Bind statuses from the Orders app to the Status widget settings

Now, write the client script. With such a script, we will send order data from the **Orders** app to the custom **Order line** widget, which includes the **Status** widget. This information is written to the context variables created in the previous steps:

- **Name** (`name`): the order name for the **Status** widget.

- **Status Name** (`statusName`): the order status for the **Text** parameter in the **Status** widget.

- **Color** (`color`): the background color of the **Status** widget.

To do this, go to the **Scripts** tab and add the following code:

````
async function onInit(): Promise<void> \{  
    if (\!Context.data.order) \{  
        return;  
    \}  
// Fetch order data  
    const order = await Context.data.order.fetch();  
    Context.data.name = order.data.\_\_name; // assign the order name to the context variable \`name\`  
    Context.data.statusName = order.data.\_\_status?.name ?? 'Unknown';  // if there is no status, assign the value 'Unknown'  
    const statuses = order.fields.\_\_status.variants; // get the order status  
// Define the color of the Status widget based on the current order status  
    Context.data.color = order.data.\_\_status?.code === statuses.done.code   
        ? Context.fields.color.variants.success  
        : order.data.\_\_status?.code === statuses.processing.code  
        ? Context.fields.color.variants.warning  
        : Context.fields.color.variants.info;  
\}

````
To make the custom **Order line** widget, which includes the **Status** widget, available for adding to pages and forms, click **Save** and **Publish** in the top toolbar of the interface designer.

### Step 5: Display a list of orders with their statuses on the page

Now, generate a list of orders based on the created custom **Order line** widget. To do this, we'll set up a [Dynamic List](dynamic-list.md) widget. Inside it, we'll place the custom **Order** **line** widget configured in the previous steps, which will retrieve the order data.

Follow these steps:

1. Open the **List of Orders** page in the interface designer.

2. The **Dynamic List **widget requires a **Table** variable to store the order data. Create it in the **Context** tab with one **App (one) **column. In this column's settings, select the **Orders** app.

3. Go to the **Template** tab and add the **Dynamic List** widget. In its settings, on the **Main** tab, in the **Data array\*** field, select the created **Table** variable. Save the settings.

4. Place the previously created **Order line** widget inside the **Dynamic List **widget.

5. Link the widget to a service table column so that data from the **Order line** widget is passed to the **Dynamic List** widget. To do this, in the **Order line** widget settings, on the **Main** tab, in the **Order** field, click the **(bind_table-icon.png)** icon, then **<Not defined>** and select **Item Table -> Order**.  
  
Save the **Order line** widget settings.

6. To display orders in the table when the page opens, go to the **Scripts** tab and add the following code:

````
async function onInit () \{  
// Get all items in the Orders app  
const ordersListItems = await Namespace.app.orders.search().all();  
  
         // Assign a value to a Table variable so it can be used  
    if (\!Context.data.table) \{  
        Context.data.table = Context.fields.table.create();  
    \}   
  
       // Create a row in the table for each Orders app item  
    for (const ordersListItem of ordersListItems) \{  
        const row = Context.data.table.insert();  
        row.order = ordersListItem;  
    \}  
  
       // Assign the value to the table again so the widget updates  
    Context.data.table = Context.data.table;  
\}

7. ````
To make the customized page available to users, click **Save** and **Publish** in the top panel of the interface designer.



As a result, the **List of Orders** page will display the names of the **Orders** app items and their statuses. Each status will have its own color.