@aurigma/ui-framework/docs/widgets/image-carousel.md

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

ImageCarousel
=============

This widget is designed to be used for the approval page. It is similar to [StaticImage](static-image.md) but allows for displaying multiple images and has some additional features.

## General info

- **type**: `image-carousel`

## Params

- `images` - an array of [image elements](#image-elements).
- `lightbox` - enables a lightbox (a large preview window opened when you click an image). The default value is `false`.
- `timestamp` - enables timestamps. You can set this parameter to `true` if you have a problem with image caching. The default value is `false`.
- `containerColor` - the color of the image container (in CSS format). Use it if your preview images are not looking good on the default background (which may happen if you are displaying images on a mockup).
- `showIndex` - if `true`, an image number appears in the list (like **1/5**). The default value is `false`.
- `showImageHeader` - if `true`, image headers appear in the carousel. The default value is `false`.
- `imageSelectorPosition` - position of the thumbnails (`"left"` | `"bottom"` | `"right"` | `"no"`). The default value is `"bottom"`.
- `resetIndexOnUpdate` - if `true`, the first image will be selected when updating the list of images. The default value is `false`.
- `autoPlay` - image switching speed, in milliseconds. By default, this value is `0`, and the autoplay is disabled.
- `arrowButtonsEnabled` - enables arrow buttons next to the main image. The default value is `false`.


## Image elements

Each element of the `images` array is described by the following structure:

``` json
{
  "title": "Front page",
  "url": "http://example.com/api/rendering/product1.png&w=300&h=300",
  "urlHD": "http://example.com/api/rendering/product1.png&w=1200&h=1200"
}
```

It is possible to omit `urlHD`. In this case, the image used in `url` will be shown on both a thumbnail and a larger image. If you set both `urlHD` and `url`, the `url` will be used only for the thumbnail and `urlHD` for the large image.

## Example

### Simple example

``` json
{
  "name": "image-carousel",
  "type": "image-carousel",
  "params": {
    "images": [
        {
            "title": "Front Side",
            "url": "http://example.com/some/url/1/front.jpg"
        },
        {
            "title": "Back Side",
            "url": "http://example.com/some/url/1/back.jpg"
        }
    ]
  }
}
```

### Customer's Canvas proof images

Typically, you have several steps. In one step, you have a Customer's Canvas editor, and in the next step, you want to show the proof images.

Here, you need to solve two tasks: force Customer's Canvas to generate images when you go to the approval step and hook up the ImageCarousel with Customer's Canvas.

Let's see how this can be done.

``` json
{
    "widgets": [
        {
            "name": "cc",
            "type": "design-editor",
            "params": {
                // ... Customer's Canvas params are omitted to keep it brief.
            }
        },
        {
            "name": "approval-images",
            "type": "image-carousel",
            "params": {
                "lightbox": true,
                "images": {
                    "{{#each $['cc'].proofImageUrls as img}}": {
                        "url": "{{img[0]}}",
                        "title": "{{'Image ' + (index+1)}}"
                    }
                }
            }
        }
    ],
    "steps":[
        {
            "title": "Editor",
            "mainPanel": { "name": "cc" }
        },
        {
            "title": "Approval",
            "mainPanel": { "name": "approval-images" },
            "onActivate": ["{{#function $['cc'].getProofImages(800,800)}}"]
        }
    ]
}
```

## See also

- [StaticImage widget](static-image.md)
- [Customer's Canvas widget](canvas.md)
- [Dynamic Configs](../dynamic-configs.md)