This is an old documentation. Go to the latest Customer's Canvas docs

Design Atoms Framework Overview

Design Atoms Framework is a part of Customer's Canvas SDK which allows for manipulating individual elements of a design edited in the web-to-print editor. If you think of the Design Editor as a browser, you may consider Design Atoms Framework as a DOM API. For example, you may import a template to Customer's Canvas, then use this framework to iterate all items, then find, for example, a text element named City, and change its value. You can also create a brand new design and pass it to Customer's Canvas.

Modules of the Design Atoms Framework

The Design Atoms Framework is split into the back end and font end.

A front-end component visualizes an object model and provides a graphical user interface for manipulating objects. For example, you can select, drag, resize, rotate objects, or perform in-place editing of the content.

A back-end component provides all necessary controllers for drawing objects, obtaining the necessary data, and rendering the entire object model. This module also contains controllers for converting Photoshop and InDesign templates into the Customer's Canvas object model.

The object model implements design elements for print products on both the front end and back end.

The Design Atoms Framework provides the client-side and server-side code for serialization and deserialization of the object model in the JSON format. For example, you can serialize your object model on the client side and pass it to the server within an HTTP request.

You can also save products to state files for long-term storage. For example, you can transfer these files to another computer for editing and rendering print-ready files. In terms of the Design Atoms Framework, a product is a state file loaded into Customer's Canvas.

You can start working with the object model as soon as you import the front-end modules. However, to start using this framework in full force, you need to connect your front-end code with a back end. There are two ways to get the back end - create your own backend or hook it to an existing Customer's Canvas instance.

A custom back end is a good option when you don't need an editor but rather need to manipulate designs through the JavaScript/TypeScript or C# code and render the result in your application. Also, it is the way to go if you want to create a custom editor based on the Viewer control. Another purpose is to handle the output from Customer's Canvas in a separate application.

As an example, you can download a sample project illustrating how you can use the Design Atoms Framework.

The Object Model of Customer's Canvas

The front end and back end share the same object model. It is implemented in the Aurigma.DesignAtoms.Model namespace. Here, you can find:

In this model, each surface may have several item containers. There are three default containers for the background, main area, and foreground. These containers allow you to display several designs on top of each other in a viewer.

The Front End

The @aurigma/design-atoms Node.js package represents the front-end library. To install the front end, run the following command in the command prompt in your project folder:

npm install @aurigma/design-atoms --save

After installation, you can import modules to your project and start working with the object model.

import { Product, Surface } from "@aurigma/design-atoms-model/Product";
let product = new Product([new Surface(400, 400)]);

In addition to the object model, the Design Atoms Framework implements a Viewer to visualize the object model. This front-end component provides access to design elements through a graphical user interface. In the viewer, you can switch product pages, manipulate design elements, and change their content. To integrate the viewer into your site, you can add its container as follows:

<div id="viewer-container"></div>

After that, initialize the viewer.

import { Viewer } from "@aurigma/design-atoms/Viewer/Viewer";
var viewer = new Viewer(document.getElementById("viewer-container"));
viewer.model = product;

This viewer allows you to access both a single design element and a number of selected elements. For example, you can change the color of all selected plain text elements to red as follows:

    .filter(item => item.type === "PlainTextItem")
    .forEach(textItem => textItem.color = new RgbColor("#ff0000"));

For more examples, you can refer to the following topic.

The Back End

The back-end module is responsible for:

  • Generating preview images and hi-res outputs.
  • Importing the object model from product templates (PSD and IDML files).
  • Creating a set of designs of different sizes programmatically.
  • Manipulating design elements according to custom logic.

If an existing Customer's Canvas instance does not fit your needs, you can implement your custom back end in either a Web, desktop, or console application. In this way, you can develop your back-end API for the viewer or develop custom methods to preview and generate high-resolution outputs.

The Aurigma.DesignAtoms NuGet package represents the back-end library. To install the back end, you can run the following command in the Visual Studio Package Manager Console:

Install-Package Aurigma.DesignAtoms

After installation, you can start working with the object model. For example, you can create a product from scratch as follows:

using Aurigma.DesignAtoms.Model;
var product = new Product {
    Surfaces = { new Surface(400, 400) }

When you need a back end for processing data from a browser, then create a Web application, add a reference to Aurigma.DesignAtoms, and expose the necessary endpoints. The viewer component requires the ViewerController on the back end. You can initialize this controller and connect your front end with a back end as follows:

const backendUrl = "http://<yourInstanceUrl>";
const holder = document.querySelector("#viewer-container") as HTMLDivElement;
const viewer = new Viewer({
    holderElement: holder,
    backendUrl: backendUrl,
    canvasBackground: { color: "white" }

For more details, you can refer to the following topic.

See Also