Widgets

## Introduction

Widgets are visual elements embedded into Torii.

You can add widgets to your plugin using the `widgets` section within your manifest file.

Plugins that support widgets will have a Widgets tab to preview the added functionality after installation:

![Untitled](https://file.notion.so/f/f/87338a36-1044-4170-b419-f2951ec6ac10/b7a98f1b-6849-4769-9884-1989f96b9bbf/Untitled.png?id=d17d5a5d-0f18-4b66-9879-ab2a69d77070&table=block&spaceId=87338a36-1044-4170-b419-f2951ec6ac10&expirationTimestamp=1702038273003&signature=QfC3FSojA3-wHqGct81SWruh8NiEBNZ1Gq2sPoRIc5Y&downloadName=Untitled.png)

Once the plugin is installed and data is available, the widget will appear on the Overview tab when viewing an application:

![Untitled](https://file.notion.so/f/f/87338a36-1044-4170-b419-f2951ec6ac10/a89ba50c-c776-4101-8d52-dcd97125a4eb/Untitled.png?id=f4b11eb1-f92a-4c5c-9ae4-31125ad42e0b&table=block&spaceId=87338a36-1044-4170-b419-f2951ec6ac10&expirationTimestamp=1702038297372&signature=9lCl9URmYhHdgWsgl-36tii2eZnmEDfOyhtO7e5BELA&downloadName=Untitled.png)

## Widget Schema

Every element within the `widgets` section should include the following properties:

| Property | Mandatory | Description                                                                                               | Example  |
| :------- | :-------- | :-------------------------------------------------------------------------------------------------------- | :------- |
| type     | ✅         | The type of the widget. (See the Widget Types section below for more details).                            | KeyValue |
| fields   | ✅         | List of fields to be displayed within the widget. (See the Widget Fields section below for more details). |          |

### Widget Types

- KeyValue - this widget displays its list of fields as key-value pairs, where the key is the field’s label and the value is the field’s value.

![](https://file.notion.so/f/f/87338a36-1044-4170-b419-f2951ec6ac10/6ae95532-80b1-4717-a3c3-139e6e76a40d/Untitled.png?id=289578f9-12c3-460e-803f-63eedc475aec&table=block&spaceId=87338a36-1044-4170-b419-f2951ec6ac10&expirationTimestamp=1702038342406&signature=89NX93193dLouIMIsYZXtEy7j-rcmyVTENJOGeI_Uwk&downloadName=Untitled.png)

### Widget Fields

An array of fields to be displayed within the widget.

[block:parameters]
{
  "data": {
    "h-0": "Property",
    "h-1": "Mandatory",
    "h-2": "Description",
    "h-3": "Example",
    "0-0": "key",
    "0-1": "✅",
    "0-2": "A unique key, pointing to one of the keys defined within the app fields list.  \nMust match the pattern: `app.<key>`",
    "0-3": "app.username",
    "1-0": "template",
    "1-1": "",
    "1-2": "Use this if you want to alter the way the value is displayed.  \nThe format is: `{{value}}`",
    "1-3": "`{{value / 100}}`  \n  \nFor: value = 5,  \nit will show: 5 / 100"
  },
  "cols": 4,
  "rows": 2,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

## Limitations

- Widgets can only be added if the `app` section is defined within the manifest.