Configuration

Full Print.App Editor Configuration

Here, you will find all the parameters, events and methods on the PrintAppClient class. You can find a basic installation guide here.

This is how to initialize a PrintAppClient:

const printAppInstance = new PrintAppClient({
    ...parameters
});

Parameters

Property	Type		Description
domainKey	String	-	Your store domainKey. You can fetch this from your Print.App Admin
designId	String	-	The id of the design you want your customer to edit. You can fetch this from the Designs page. Click the more icon and copy the design. That should also copy the designId into your clipboard. From your server, you can also list them with GET /v2/designs.
designList	Array of strings	-	A list of designId. This is only valid if you want your customers to pick from a list of designs you specify here. The first design is always loaded as default. If this is provided, you can omit the designId parameter
designTemplate	Object	-	An object describing a sample design source to display when the editor loads. This is optional and only required if you do not want to use a pre-generated designId. More details can be found at the end of this page
projectId	String	-	This is required if you want to load the editor to edit an existing project. Remember to also set the mode to edit-project
mode	String	-	The editor mode. Valid values are: new-project: The editor should create a new project using the designId as a template. edit-project: You want to edit an existing project. This requires a projectId to be provided
custom	Boolean	-	Set this to true to let the editor know it’s a custom installation
autoShow	Boolean	-	This is used to automatically launch the editor after it initializes, without the customer clicking a customize button.
product	Object	-	Your own details of the product the customer is designing, for example { id: 'sku-123', ref: 'cart-line-7f3a' }. Saved with the project exactly as passed, and returned by the API, so your server can check that a project was made for the product being ordered. See Verify a project before fulfilling.
userId	String	-	Your id for the customer. Saved with the project and returned by the API as userId.
userData	Object	-	Customer details to save with the project: id, name, email, phone, info. Returned by the API as userData.
customValues	Object	-	Not saved with the project or returned anywhere. To attach your own data to a project, use product.
langCode	String	-	Default: en The language to load the editor in. This should be a two letter language code following the ISO 639-1 two-digit language codes. You will find a list of valid language codes supported by Print.App here

Methods

Name		Description
showApp()	-	Show the Print.App Editor
closeApp()	-	Close and hide the Print.App Editor
addEventListener(eventType, function)	-	Attaches an event listener to the Print.App Editor
removeEventListener(eventType, function)	-	Removes an eventListener from the Editor

Event types

Events are attached to the PrintAppClient after initialization using the addEventListener method.

const printAppInstance = new PrintAppClient({
    ...parameters
});

function readyFunction() {
    printAppInstance.showApp();
}
printAppInstance.addEventListener('app:ready', readyFunction);

EventType		Description
app:validation:success	-	Dispatched when the editor has completed its authentication process. This is the first action the editor makes before being ready to show any design or project. The store configuration is passed down to your event
app:validation:failed	-	Dispatched when the editor cannot validate the domainKey or the parameters passed are invalid
app:ready	-	Dispatched when the Editor has initialized and is ready to be shown
app:saved	-	Dispatched when the customer has clicked the submit button and a project is saved. Your function receives the project’s details, including its projectId and preview images: see The app:saved payload. addToCart is true when the design has Add to Cart on Save turned on. See Adding to the cart on save.
app:closed	-	The editor is closed
app:display:changed	-	Only in the Dialog Display Mode: dispatched when the customer expands the editor to full window or shrinks it back. A data object of { expanded: Boolean } is passed to your function.

The app:saved payload

Your listener receives an event whose data describes the saved project:

printAppInstance.addEventListener('app:saved', ({ data }) => {
    console.log(data.projectId, data.previews[0].url);
});

Field	Type	Description
projectId	String	The saved project. Send it to your server with the order.
mode	String	edit-project once a project is saved.
sourceDesignId	String	The design the project was made from.
previews	Array	One { url } per page: preview images of the design.
saveForLater	Boolean	true when the customer saved the design to finish later rather than submitting it.
addToCart	Boolean	true when the design has Add to Cart on Save turned on.
orderData	Array	{ name, value } pairs from objects marked Include in order details, for your cart line.
userId, userData		As passed when the editor was opened.
launchData	Object	As passed when the editor was opened.
scene	Object	Only when the design has a 3D Scene: the design rendered on it.
records	Number	Only for mail-merge designs: how many rows (copies) the order carries.
canvas, items	Object, Array	Only for gang sheets: the sheet size and its items.
base64Previews, resources, design		Only when you opened the editor with exportBase64Previews, exportResources or exportDesign set to true.

The event comes from the customer’s browser, so its contents are the customer’s to change. Before you fulfil an order, verify the projectId from your server: see Verify a project before fulfilling.

Adding to the cart on save

With Add to Cart on Save turned on in a design’s settings, the client presses the store’s Add to Cart button for the customer after the project is saved. It waits for every app:saved listener to finish first, so the project can be attached to the cart line before the add. A listener that does asynchronous work (posting the project to your server, say) must return its promise, or the add can happen before that work is done:

printAppInstance.addEventListener('app:saved', async event => {
    // returned, so the add waits for it
    await saveProjectToMyCart(event.data.projectId);
});

If your cart needs something other than a button press, take the add over. Just before it presses the button, the client dispatches a cancelable printapp:addtocart event on document. Call preventDefault() and do the add yourself:

document.addEventListener('printapp:addtocart', event => {
    event.preventDefault();
    const { projectId, data } = event.detail;   // data is the app:saved payload
    myCartPlugin.add({ projectId });
});

You can add this script to your store from the Custom JavaScript input in your store settings.

If the client cannot find your Add to Cart button, set the Cart button selector in your store settings.

Loading the editor without a designId

This feature allows you to initilize the editor without having an prior design, by describing a design template.

The parameter to pass unto the editor is an object titled designTemplate A sample value is shown in the code below with detailed comments.

designTemplate: {
	// design unit. possible values are: cm, mm, in, pt, px, ft
	"unit": "cm",

	// an array of pages in the design
	"pages": [
		{
			// page dimensions, bleed and other info
			"width": 20,
			"height": 22,
			"bleed": 0.5,

			// background color
			"background": "transparent",

			// underlay image url
			"underlay": "",

			// overlay image url
			"overlay": "",

			// page margins (if you provide an underlay)
			"offsets": {
				"top": 4,
				"left": 5.6,
				"right": 5.6,
				"bottom": 1.5
			},
		}
	]
}