What is IFrame API JS library?

3 minutes to read

The IFrame API (IframeApi.js) a JavaScript library used to load Design Editor frontend application to a specified <iframe> element and communicate with it from your code.

Customer's Canvas Design Editor user interface

You may do the following with a help of IframeApi.js:

Load an editor with a blank canvas.
Load an editor with a design template based on state files, InDesign or Photoshop files.
Load complex multi-page configurations consisting of multiple template files.
Load an editor not just with a design, but also with a mockup (visualization of a product).
Configure the user interface of an editor optimized for various product types.
Manipulate a design at runtime, such as adding or removing page, change mockups, updating design items, etc.
Save a personalized design as a private state file.
Populate a design with a data, e.g. prefill variable fields like name, company, phone, etc.
... and many more

Note

This library is also used as a core of design-editor widget. It means that the information about the product definition and editor configuration is still applicable for UI Framework as well. However, this documentation is focused on using the editor in context of IFrameApi.js library.

What is a product and how is it described?

There are different ways to describe the content you load into the editor (a product). The simplest one is to just specify the state file name (i.e. a design file created in the Customer's Canvas format). However, you have more options. You can describe each page (surface) and what design files are used there as well as add safety lines, spines, folding lines, etc.

See the Product definition to learn more about it.

Configuring the editor UI

The editor user interface consists of several elements. Depending on the product you personalize, some of them may make sense, but you may prefer to hide others. For example, for simple designs you may want to use as few buttons and menus as possible, while for more advanced users, you may want to enable more features.

IFrameApi.js allows you to finely tune the toolbox, toolbars, asset manager (image gallery browser), object inspector, canvas working area, etc. through the editor configuration you pass when you load the editor.

See the Editor configuration for more details.

Interacting with the Design Editor

After you load a design, you may interact with the editor using the IframeApi.js classes, methods, properties, and events. Here are some examples of what you can do:

Add/remove pages (surfaces) and toggle between them.
Change a mockup image. For example, when you edit a design on a T-shirt, you may use it to change a product color or model.
Load another design with or without merging user changes with it.
Handle events like opening modal dialogs, selecting an item, and adding/removing/updating items on a design.
Get access to the design object model and modify it.

See the IframeApi.js Reference.

Customizing the Design Editor

Sometimes you may want to adjust the look-and-feel of the Design Editor user interface to make it look more native to your website. There is no need to make several CSS manipulations. There are some simple means to configure the most important parameters such as a brand color and a preloader. Another important UI customization is the ability to localize it to different languages, if you are working in non-English speaking markets.

You can learn more about it in the User interface customization section.

Configuring proof images and print files

When the user leaves the editor, you may want to show how the result will look, and if the user is happy and submits the order, receive a PDF print file so that you can fulfill the order. The easiest way to configure this behavior is to pass the appropriate configuration when you load the editor.

All aspects of creating proof images and print files are covered in the Rendering section.

API Reference

You can find all the configuration interfaces, classes implementing the object model, and methods to manipulate the editor and products in the reference of the @aurigma/design-editor-iframe package.