@aurigma/ui-framework/docs/widgets/readme.md

A platform which allows building print product personalization editors based on Aurigma's Customer's Canvas.

# Widget Reference

A widget is a small UI element that can be inserted into a left, main, or bottom panel (or in a special [Group widget](group.md)). This section describes supported widgets, what settings they have, and how to work with them.

## Anatomy of widgets

Each widget consists of the following elements:

1. A widget header, or _title_
2. A hint explaining what the user is supposed to do with it, or _prompt_.
3. An additional description, which appears as a tooltip, or _description_.
4. A widget body.

![Widget anatomy](../images/widget-anatomy.png)

In a JSON structure, each widget contains the following properties:

- `name` - a unique widget name (in the scope of one config), which you use to refer to this widget in expressions.
- `type` - a widget type.
- `params` - widget settings, which configure its behavior. See documentation for each widget for more details.

The following properties are optional. They have the same meaning as depicted in the figure above.

- `title`
- `prompt`
- `description`


## JSON example

A widget looks like this: 

``` json
{
    "name": "stub",
    "title": "Hello world",
    "prompt": "This is a concept that I had in mind for a long time and I am happy to share it.",
    "description": "This is a concept that I had in mind for a long time and I am happy to share.",
    "type": "static-text",
    "params": {
        "text": "Hello world"
     }
}
```

## How to refer to widgets inside the config

In dynamic expressions, you may refer to widgets using the `$`. Note, it does not have anything to do with jQuery, it is just a shortcode. Alternatively, you can use such aliases as `wig` and `widget`.

Many widgets have some elements that you may select. To refer to the selected element of such a widget, you can use a `selected` property or its shorter version, `_`.

For example, to get the title of the selected item of a widget called **list**, use the following expression:

```
$['list']._.title
```