Design editor

• Last updated on December 29, 2023
• •
• 4 minutes to read

This widget integrates the editor into your personalization workflow.

{
    "name": "editor",
    "type": "design-editor", 
    "params": {...}
}

Configuring the editor

This widget does not have its own properties. Instead, its configuration is organized in so-called commands to manage the Design Editor. A command is a first-level property of the params object.

Most likely you will not need to use all these commands, since they often solve a narrow problem. The only command you must define is initial, where you must pass your product definition and may change the default editor settings.

{
    "name": "editor",
    "type": "design-editor",
    "title": "Personalize your card",
    "params": {
        "initial": {
            "productDefinition": {
                "surfaces": [{
                    "width": 306,
                    "height": 396
                }]
            },
            "editorConfig": { "initialMode": "Advanced" }
        }
    }
}

Here, we defined a blank page for a 4.25 x 5.5-inch card (306 x 396 points) in productDefinition and changed the editing mode to advanced in the editorConfig.

Manipulating the editor and products

While your customer personalizes products through the user interface, you can manipulate both the editor and the products through methods provided by the Design Editor. These methods can be divided into the following basic groups:

• saving and rendering personalization results
• working with product pages
• variable data printing

To apply a method, you can call it in an onClick or onActivate block of widgets. This is how you can enable a button to add pages to the product in the editor. Here, we add the addSurface() method to the onClick block.

{
  "name": "add-page-button",
  "type": "button",
  "params": {
      "text": "Add Page",
      "onClick": [
          "{{ #function $['editor'].addSurface({ width: 306, height: 396 }) }}"
      ]
  }
}

Getting design elements

To get the results of applying those methods, you need to read properties they set. For example, you can obtain a list of all design elements in the product by calling the getAllItems() method on activating the approval step.

{
  "steps": [
      ...
    {
        "name": "Approval",
        "title": "Approval",
        "description": "Approve your design",
        "onActivate": [
            "{{ #function $['editor'].getAllItems(); }}"
        ],
        "mainPanel": {
            "name": "proof-image"
        },
        "toolPanel": {
            "name": "approve-options"
        }
    }
  ]
}

The result of this method will be set to the allItems property of the design-editor widget. For example, you can output all element names to the static-text widget as follows:

{
  "name": "items",
  "type": "static-text",
  "params": {
      "text": {
          "{{ #each $['editor'].allItems as item}}": "{{item.name}}"
      }
  }
}

Getting the personalization results

After the customer has finished with personalization, you can call methods to save the product and render the design: saveProduct(), getProofImages(), and getHiResImages().

Let's look at how you can implement the basic scenario, when the customer works in the editor first, then moves to design approval. In the following example, we defined two widgets and two steps. At the first step, we only display the Design Editor.

"steps": [
  {
      "name": "design",
      "title": "1. Design",
      "mainPanel": { "name": "editor" }
  },
    ...
]

When the customer moves to the second step, we can call the getProofImages() method on the step activation to render proof images.

"steps": [
    ...,
  {
      "name": "approve",
      "title": "2. Preview",
      "mainPanel": { " name":"preview" },
      "onActivate": "{{#function $['editor'].getProofImages(800,800)}}"
  }
]

The results of the rendering will appear in the property proofImageUrls which contains an array of images. Elements of this array correspond to pages and print areas on these pages. Since we defined the product with a page and a print area on the page, we can only display the element proofImageUrls[0][0] to approve in the slider widget.

{
  "name": "preview",
  "type": "slider",
  "params": {
      "images": [
          {
          "url": "{{$['editor'].proofImageUrls[0][0]}}"
          }
      ]
  }
}

Now, let's look at the complete code example.

{
  "widgets": [
    {
      "name": "editor",
      "type": "design-editor",
      "title": "Personalize your card",
      "params": {
        "initial": {
          "productDefinition": {
            "surfaces": [{
              "width": 306,
              "height": 396
            }]
          },
          "editorConfig": { "initialMode": "Advanced" }
        }
      }
    },
    {
      "name": "preview",
      "type": "slider",
      "params": {
        "images": [
          {
            "url": "{{$['editor'].proofImageUrls[0][0]}}"
          }
        ]
      }
    }
  ],
  "steps": [
    {
      "name": "design",
      "title": "1. Design",
      "mainPanel": { "name":"editor" }
    },
    {
      "name": "approve",
      "title": "2. Preview",
      "mainPanel": { " name":"preview" },
      "onActivate": "{{#function $['editor'].getProofImages(800,800)}}"
    }
  ]
}

Commands

The following commands are supported:

• initial - initializes the editor with product definition and config (required)
• changeMockup - replaces mockups stored in the CC backend
• modifyItems - modifies elements inside the editor
• resize - resizes the whole product or only specified items
• setBackground - replaces the background image
• setPrintArea - loads another template on a specific surface
• setRemoteMockup - replaces mockups by the specified URL
• setSerializedProduct - deserializes and loads a product into the editor
• setSurfaces - replaces a product in the editor
• setTheme - changes a theme
• swapSurfaces - swaps two surfaces in the product
• translate - moves design items on the canvas
• updateContainerSettings - updates spot colors and textures
• updateItems - updates design elements
• updateSurfaces - updates design elements

You may omit any command except initial. For more details about these commands and methods, refer to the widget reference in the developer's section.