Design Atoms API
What and why?
In the version 4 and earlier the API allowed opening a design from PSD or IDML file and save a result on a server with an ability to receive a URL to a proof image or a print file. You had some features like an ability to prepopulate template with values or receive user’s changes. However, for more or less non-standard tasks you had to request a custom feature from us or use a clumsy eval method to run a “magical” non-documented code that modifies a design in Customer’s Canvas.
Now you have an official API to work with each element of a design loaded in the editor. It is similar to DOM API in JS – you can iterate each element of your design, query a specific element by its name, read and modify its properties, add or remove elements.
Examples
This API allows for reinventing the way of how you work with Customer’s Canvas. Just a few examples. Imagine the following scenarios:
1. You want to lock all non-text elements.
In the past you had to instruct your designers to create all your templates with <LC> markers for the items you want to lock. Now you can write a code like:
model.getAllItems()
.filter(x => x.type !== "PlainTextItem")
.forEach(elem => {
elem.locked = true;
});2. You want to generate a product design.
Earlier, even for a simple product like a single placeholder which occupies the entire surface you had to create a PSD or IDML file (for each size, etc). Now you can just use a code like this:
var surface = product.currentSurface; var placeholder = new PlaceholderItem( new RectangleF(0, 0, surface.width, surface.height) ); surface.insertItem(placeholder);
This approach also allows for writing a code which imports designs from your previous system or any other situations when you need to generate a design on the fly.
3. You want to verify the design before you save it.
Early you could get some structure containing the values entered by a user inside the finishProductDesign, however, it was not really versatile. Now you can write something like:
var stopwords = [...]; var isValid = model.getAllItems() .filter(x => x.type === "PlainTextItem") .every( x => x.text !== "" && !stopwords.some(y=>x.text.includes(y))) );
Of course, it is just a few of thousands scenarios you may implement this this new API.
Viewer control
You not always want to have a full-fledged editor with all toolbars, menus, item list, asset manager, etc. For those who prefer implementing their own editor, we have exposed the viewer control, which can be used without the Design Editor application. This way you don’t need to get involved into the most complicated part of the editor (design element manipulations) and implement your own user interface using your favorite JavaScript framework.
Note, the viewer control does not require any iframe, so it works seamlessly with your application.
Standalone usage
There are two ways to add the Design Atoms library to your application – either using it through the Customer’s Canvas iframe API or add it to your application as an npm module. The first approach is convenient when you manipulate with a design opened in the Design Editor application. The second one is great when you build a “headless” version of Customer’s Canvas (i.e. generate designs fully automatically, without visualization) or create your own editor using the Viewer control.
Server-side usage
Design Atoms can be used not only on a client side, but also on a server side. In other words, you can do the same things like described above not only in your JavaScript/TypeScript code, but also in C#.
It allows automate design manipulation in a pure .NET code when you don’t want to do anything in a browser. Also, it allows for creating your own code which stores, renders or imports the designs to Customer’s Canvas.
Code examples
We already have a large number of different APIs – IFrame API, Personalization Web API, Dynamic Image, UI Framework, Design Atoms, etc. Although we work hard on the documentation, we realize that is often not enough and you need some examples how to use certain functionality.
That’s why we have created a couple of GitHub repositories with code examples for all our APIs:
At this moment, there are not a lot of them published there yet, however, we are going to add more code examples in the future. Feel free to leave your request for the samples and we will do the best to cover the scenarios you need the most.
New configuration files and app structure
Configs
As you may know, the configuration files (clientConfig.json, AppSettings.config, etc) contain many settings and it is quite challenging to decide what settings to turn on/off. Some default values originated from early versions of Customer’s Canvas and they are not always the optimal ones.
In Customer’s Canvas 5.0 we decided to use our rich experience in configuration of Customer’s Canvas and set the optimal parameters in our point of view. Now, even if you initialize Customer’s Canvas with the default config, it will look quite nice and user-friendly!
App structure
Another thing we have improved is a default app structure. In the past, all designs, fonts, etc. were stored in the same folder with the application files. As a result, it was quite difficult to upgrade – you had to be careful not to lose your data.
The new structure makes it easy to maintain multiple versions, have them to reuse the same assets and user data.
Standard assets
We have included a selection of fonts you can get started with. Also, we have revised the standard design files.
In the future, we are going to include more assets – standard artwork, more design examples and even ready packs for various products.
