The Multistep Editor

The ordering and personalization process can be organized on a step-by-step basis. For example, your users may:

  1. Edit the front side of the product.
  2. Select an envelope.
  3. Edit the back side.
  4. Specify any order options.

Even more complicated workflows may exist.

Multistep Editor allows you to implement such a step sequence by composing your application from widgets like from building blocks in a configuration file. That allows for the flexible Customer's Canvas even by non-programmers, no matter if you need a simple editor or a multi-step wizard.

Let's see how it looks like:

Widgets in the Multistep Editor

  • The navigation panel allows for switching the steps.
  • The main panel holds a basic widget like the canvas, preview, or visual proofing tool.
  • The left panel (tool panel) may include an option selector, context-dependent blocks, a gallery or even their combination.
  • The bottom panel allows you to enable additional widgets like a gallery.

Steps

Since the ordering process can be step-by-step, you need to associate a set of widgets in each of these containers with a step in the config. For example:

  1. The first step: the main panel displays Customer's Canvas, and the left panel displays the color options.
  2. The second step: the main panel displays an approval page, and the left panel displays the delivery options.

In some cases, configs of different steps point to the same widget, but with different settings. A typical case is when Customer's Canvas should display the first page in the first step and other pages in the other steps. Also, widget containers may remain the same at different steps, say, you can use a single left panel for all steps.

You can hide the left and bottom panels if needed.

By default, this wizard starts with the first step, but you can also override this behavior in the config.

Setting Up Widgets in Steps

For better understanding, let's see the structure of a config file.

As we explained earlier, first you place widgets on the panels and then refer to them when defining steps. The following examples illustrate how you can enable the Customer's Canvas widget.

{
   "widgets": [
        { name: "cc", type: "canvas", params: { ... } }  /* the CC widget */
    ],
    ...
    "steps": [{
        title: "Front Page",
        mainPanel: {
            name: "cc"
        }
    }]
}

Now, let's look into widgets a bit more detailed.

Widgets

A widget is a control that may appear in the main, tool, or bottom panels. For example - image editor, radio buttons, text block, etc.

Technically, a widget can be placed in any of these panels. In practice, we assume that, for example, Customer's Canvas will always be in the main panel, the options list is in the left panel, and so on.

Widget Configs

Every widget may contain the following properties:

  • type - the widget type specifying the module that the editor will load.
  • name - the name of a widget instance that can be referenced.
  • title - the name displayed in the user interface.
  • prompt - explanatory text.
  • description - help tips (appears as a tooltip).
  • params - additional parameters of this widget. By default, this is an empty objects.

Supported widgets

So far the following widgets are supported:

There is no mandatory widgets, but without certain widgets you will unlikely build a usable editor. Most likely, all your configs will contain Canvas, some Option widgets and you will configure the output from the editor through the Order widget. Use the ImageCarousel to organize a preview section.

Another important widget is Ajax - it allows receiving data from the server - list of images, dynamically generated images, or any other data you may need.

The Multistep Editor Config

The config consists of the following sections:

  • logo - the object containing a URL to the logo to insert in the steps section (see example below). You may omit it.
  • language - the localization language (like en, fr, de, nl, ru, etc.). You can find the translations in configuration/locales/default.json.
  • widgets - the definitions of all widgets.
  • steps - the definitions of every step referencing to the widgets for different panels.
  • showSteps - if false, the steps panel is hidden. Default - true.
  • vars - a container for the data you may want to use in the config.
  • defaultStep - the title of a step from which you want to start your wizard. This is the optional parameter.

Configs look as follows:

{
    "logo": {
        "src": "https://customerscanvas.com/Aurigma/Theme3/img/common/logo_cc.svg"
    },
    "language": "en",
    "widgets": [
        { name: "cc", "type": "canvas", /* other widget properties */ },
        { name: "approve", "type": "approval", /* other widget properties */ },
        { name: "options", type: "group", /* other properties */ }
    ],
    "steps": [
        /* step 1 - the personalization through Customer's Canvas */
        { 
            "title": "Personalize", 
            "mainPanel": {
                "name": "cc", /* takes the cc widget from mainPanels */
            }, 
            "toolPanel": {
                "name": "options" /* takes the options widget from toolPanels */
            }   
        },
        /* step 2 - the approval through Customer's Canvas */
        { 
            "title": "Approval", 
            "mainPanel": {
                "name": "approve" /* takes the approve widget from mainPanels */
            }
        }
    ],
    "defaultStep": "Personalize" /* refers to the title; if omitted, the wizard starts from the first step */ 
}

Note that the toolPanel is not defined in the second step. This means that nothing will be displayed in the left panel.

If there is the only step, the navigation panel will be hidden.

The config may be dynamic, i.e. you can configure how one widget settings depend on the user's input. For example, you may want to re-load a mockup in Customer's Canvas depending on the option value selected by a user.

See the Dynamic Configs reference for more details.

Passing data to the config

It is often to parametrize the config. For example, you may configure the editor to change the background image based on the user's choice in the Gallery widget. However, it is unlikely that you want to hardcode a list of backgrounds in the config.

The first approach is use the Ajax widget to fill the gallery with items. This approach is great when you want to update the list depending on the other choices.

However, quite often you may want to prefetch some data and pass it to the config before you initialize it. You can do it using the vars section.

So you are supposed to add the JSON object describing your data to the vars:

{
    "vars": {
        "bands": [
            {
                "id": 0,
                "name": "The Beatles",
                "gentre": "Rock",
                "thumbnail": "http://example.com/1.jpg"
            },
            {
                "id": 1,
                "name": "Miles Davis Quintet",
                "gentre": "Jazz",
                "thumbnail": "http://example.com/2.jpg"
            }
        ]
    },
    ...
}

Based on this variable, you can write a dynamic config which creates a proper structure of options.

{
    "widgets": [
        {
            "name": "band-gallery",
            "type": "gallery",
            "params": {
                "items": {
                    "{{#each vars.bands as band}}": {
                        "name": "{{band.id}}",
                        "title": "{{band.name + '(' + band.gentre + ')'}}",
                        "previewUrl": "{{band.thumbnail}}"
                    }
                }
            }
        }
    ]
}

All you need to do to apply another set of data is modify the vars node of the config before initializing the editor with it.