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

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

Group
=====

Use this widget to group multiple widgets together.

You probably noticed that the `steps` section of a config allows for specifying only one widget for a **main**, **tool**, or **bottom** panel. However, it is often necessary to add more than one widget to a container. This is where the **Group** widget comes into play.

You can create a Group widget - put several options, galleries, texts, checkboxes, etc. together - and add this group to the tool panel. Of course, it is possible to also do this for the bottom and main panel as well.

You can break them into multiple tabs, use an accordion layout, or even create nested groups!

## General info

- **type**: `group`

## Params

- `type` - a group type. Possible values are `vtab` (vertical tabs), `htab` (horizontal tabs), `collapsible` (accordion), and `noncollapsible` (just a plain widget list). The default value is `htab`.
- `tabs` - an array of tabs. A JSON structure of each tab is [described below](#tab-structure). By default, this is an empty array.
- `unifySelection` - if `true`, you can make all nested widgets have the unified selection no matter what tab a user opens. It is often important when you are using a group for multiple [Gallery widgets](gallery.md). The default value is `false`.

## Tab structure

The idea of the Group widget is that you organize multiple widgets into several tabs. Each tab may have a title and a list of its widgets.

``` json
{
   "id": 0,
   "icon": "au-icons:bg",
   "title": "Some tab",
   "widgets": [...]
}
```
Tabs have the following properties:

- `id` - a tab number.
- `icon` - a tab icon. The **au-icons** section is precompiled, and you can add new SVG icons there.
- `title` - the tab title.
- `opened` - a Boolean value defining the initial appearance of the group.
- `widgets` - an array that may contain any visual widget supported by the UI Framework, including other Group widgets.

Depending on the `type`, tabs are interpreted differently:

- For `vtab`, it is a vertical tab (displayed left of the group).
- For `htab`, it is a traditional horizontal tab.
- For `collapsible`, it is an accordion element. Only the active tab is expanded, all others are automatically collapsed.
- For `noncollapsible`, it is just a title in a list.

## Examples

### One-level group

This is an example of a two-tab group. On the second tab, we put two options simultaneously.

``` json
{
    "widgets": [
        {
            "name": "my-group",
            "type": "group",
            "params": {
                "type": "collapsible",
                "tabs": [
                    {
                        "title": "Backgrounds",
                        "widgets": [
                            {
                                "name": "bg-gallery",
                                "type": "gallery",
                                "params": { ... }
                            }
                        ]
                    },
                    {
                        "title": "Colors",
                        "widgets": [
                            {
                                "name": "primary-color",
                                "type": "option",
                                "params": { ... }
                            },
                            {
                                "name": "secondary-color",
                                "type": "option",
                                "params": { ... }
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "steps": [
        {
            "title": "Step 1",
            "toolPanel": { "name": "my-group" }
        }
    ]
}
```

### Nested groups

You can put a Group widget as one of the widgets inside a tab. It may be important for the galleries.

You may 

``` json
{
    "name": "my-group",
    "type": "group",
    "params": {
        "type": "htab",
        "tabs": [
            {
                "title": "Backgrounds",
                "widgets": [
                    {
                        "name": "categories",
                        "type": "group",
                        "params": {
                            "type": "collapsible",
                            "unifySelection": true,
                            "tabs": [
                                {
                                    "title": "Abstract",
                                    "widgets": [{
                                        "name": "abstract-gallery",
                                        "type": "gallery",
                                        "params": { ... }
                                    }]
                                },
                                {
                                    "title": "Gradients",
                                    "widgets": [{
                                        "name": "gradient-gallery",
                                        "type": "gallery",
                                        "params": { ... }
                                    }]
                                },
                                ...
                            ] 
                        }
                    }
                ]
            },
            {
                "title": "Colors",
                "widgets": [
                    ...
                ]
            }
        ]
    }
}
```