# Custom Action

Custom action widgets allow you to code an action to be performed, which will be triggered by a button or a form.

## How it Works

{{< staticImage "ux/CustomAction/Widget/CustomActionWidget.png" "Custom action widget" >}}

This widget will display a form or button that will execute the user-coded action.

In the case of using a form, the action will receive the form values and any desired logic can be applied to them.

Additionally, this widget can be configured so that the action executes within a dialog box as an independent form.

{{< staticImage "ux/CustomAction/Widget/CustomActionWidgetExecutionResult.png" "Custom action execution result" >}}

Once the execution is initiated, a progress box will appear displaying the result of the action.

The execution will be successful as long as no exception is thrown in the source code.

## Configuration

{{% ux-widget-configuration %}}

- **Description** here you will write what action will be executed when the corresponding button is pressed
- **Icon** determines the type of desired visualization: a button with an icon, an image, or a custom form. In the case of a form, it can also be specified if you want to display it as a dialog box.

{{< staticImage "ux/CustomAction/Configuration/CustomActionWidgetConfigGeneral.png" "Custom action general configuration" >}}

If it's a form, you must enter a JSON schema that determines what will be drawn.

{{< staticImage "ux/CustomAction/Configuration/CustomActionWidgetConfigSchema.png" "Custom action schema configuration" >}}

### Expert

{{< staticImage "ux/CustomAction/Configuration/CustomActionWidgetConfigExpert.png" "Custom action expert configuration" >}}

Here you can configure source code that will run before the widget is loaded, allowing for the dynamic construction of the JSON schema of the form to be displayed, thereby facilitating the construction of dynamic forms based on platform data.

{{% ux-widget-code-utils %}}

### Function

Depending of the configuration receives the following parameters:

{{% ux-widget-param-entitydata %}}

{{% ux-widget-param-relatedEntities %}}

{{% ux-widget-param-timeseriesdata %}}

{{% ux-widget-param-alarmdata %}}

#### Action code specific parameters

* *value* is the value, in string format, entered in value field when enabled

* *model* contains the custom form values data

Example:
```json
{
    "your.datastream.name": "datastreamvalue",
    "field1": "value1",
    "field2": "value2"
}
```

##### Final code structure build by the application

```javascript
async function main(entityData,alarmData,relatedEntities,timeserieData,value, model) {
  // YOUR CODE HERE WITH RETURN OR CALLBACK
}
```

#### Expert code specific parameters

* *config* receives the configuration object of the widget in order to modify it
* *callback* function used to send the new configuration to the widget

Example:
```javascript
callback(newConfig);
```
or
```javascript
return newConfig;
```

##### Final code structure build by the application

```javascript
async function main(entityData,alarmData,relatedEntities,timeserieData,config,callback) {
  // YOUR CODE HERE WITH RETURN OR CALLBACK
}
```

### Examples

{{% children sort="weight" depth="10" %}}

---