Canvas

A widget which integrates Customer's Canvas to the editor. As usual, it is the most important widget of the editor and it is heavily parametrized using the dynamic configs.

Note, to be able to use it, you should be familiar with Customer's Canvas IFrame API and basics of its configuration.

General info

type - canvas

Config structure

This widget is a bit outstanding compared to other widgets. It does not have its own properties. Instead, all its properties are organized in so-called commands.

A command is a first-level property of a canvas config. The following commands are supported:

Each command has its own properties you are supposed to make dynamic. As soon as the editor detects changes in a widget you a refering in a particular command, only this command is executed.

You may omit any command except of initial.

For example, you have the following commands:

{
    "name": "editor",
    "type": "canvas",
    "params": {
        "initial": { ... },
        "setBackground": {
            "url": "{{$['gallery']._.url}}"
        },
        "changeMockup": {
            "data": {
                "mockup": {
                    "down": "{{$['color']._.mockupName}}"
                }
            }
        }
    }
}

Imagine that the user choose an alternative background in the gallery widget. In this case, only setBackground command will work, neither initial nor changeMockup will be re-applied (which would happen cause it to reload all the design and do unnecessary flickering).

This way you are using these commands to associate Customer's Canvas with different widgets and do various actions when you change anything.

How to have Customer's Canvas to generate result

The most typical scenario is to organize the editor into several steps, where, for example, the first step is the Customer's Canvas and the next step is an approval page where you need to display the result and pass the hi-res PDF out of the editor.

To accomplish this, you need to tell Customer's Canvas to generate a result when you leave the design step and grab the output in the config of the approval step.

To save the result, you can call these methods:

getHiResImages(previewWidth, previewHeight) - an equivalent to editor.finishProductDesign from IFrame API.
getProofImages(previewWidth, previewHeight) - an equivalent to editor.getProofImages from IFrame API.
saveProduct() - an equivalent to editor.saveProduct from IFrame API.

After they finish working, they will return the results to the following properties of the widget:

proofImageUrls
hiResUrls
stateId
userId
userChanges

The getHiResImages changes all these properties, the getProofImages - only the proofImageUrls and saveProduct - only the stateId and userId.

The proofImageUrls and hiResUrls are arrays of the same structure as returned by IFrame API. See the documentation for the appropriate methods in Customer's Canvas for more details.

You may wonder where to call the getHiResImages method. As usual, you can do it in the onActivate of a step where you need to use the results or in onClick of a button widget.

Example

{
    "widgets": [
        {
            "name": "editor",
            "type": "canvas",
            "params": {
                "initial": { ... },
                ... // other commands
            }
        },
        {
            "name": "preview-image",
            "type": "static-image",
            "params": {
                "url": "{{$['editor'].proofImageUrls[0][0]}}"
            }
        }
    ],
    "steps": [
        {
            "name": "design",
            "title": "Design",
            "mainPanel": {"name":"editor"} 
        },
        {
            "name": "approve",
            "title": "Preview",
            "mainPanel": {"name":"preview-image"},
            "onActivate": "{{#function $['editor'].getHiResImages(800,800)}}" 
        },
    ]
}

Other methods and properties

For most use cases, the methods and properties described above are enough. However, for more complicated configs (e.g. related to the Variable Data Printing), you may be interested to use additional members:

getTags()/setTags() methods and tags property - to read/write custom data (such as Variable Data) to the state file
getVariableData() method and variableData property - to detect what particular variable fields are used in the design. It is used to build a list of variable fields.
getAllItems() method and allItems property - to read info about items in Customer's Canvas

Note, due to the declarative nature of a JSON config, the getXXX methods do not return any usable results. Instead they tell Customer's Canvas to initialize the appropriate property. When it happes, dynamic config engine is notified about changes and the config is re-applied.