Core API

Generated reference for the iPrintessApi methods tagged #ai-api:core in printess-editor.d.ts. Custom types referenced below (parameter and return shapes) are documented on the Types reference.

addBuyerLogEntry

addBuyerLogEntry(message: string): void

Logs a message to the save token. Useful for setting user confirmation messages like “accepted low resolution” or “accepted image compliance warning”.

Parameter	Type	Description
`message`	`string`	The message you want to log to the save token. It’s automatically prefixed with the current date and time.

Returns: void

attachAllHandlers

attachAllHandlers(): void

Tells Printess to re-attach all global event-listeners; This MUST NOT be called initially. Only after you have called detachAllHandlers(); Logs error if handlers are not currently detached.

Returns: void

detachAllHandlers

detachAllHandlers(): void

Tells Printess to remove all global event-listeners Logs error if handlers are not currently attached or if scope is not initialized

Returns: void

generateContentHash

generateContentHash(options?: { formFieldsToIgnore?: string[], ignoreAllFormFields?: boolean }): string

Creates a content hash of the current design state. Can be used to track changes. When supplying formFieldsToIgnore it will filter out those form fields. Those are excluded from the hash generation. Please note that this hash can change when used on different Printess Editor versions.

Parameter	Type	Description
`options?`	`{ formFieldsToIgnore?: string[], ignoreAllFormFields?: boolean }`	Supports setting form field names to ignore during hash creation.

Returns: string

getTemplateName

getTemplateName(): string

Returns the name of the currently loaded template.

Returns: string

getTemplateTitle

getTemplateTitle(): string

Returns the title of the currently loaded template. May be an empty string if the template has no title set.

Returns: string

hasUnsavedChanges

hasUnsavedChanges(): boolean

Returns “true” if template has unsaved changes

Returns: boolean

importTemplate

importTemplate(task: TemplateImportTask, options: TemplateImportOptions): Promise<void>

Imports Printess intermediate document format

Parameter	Type	Description
`task`	`TemplateImportTask`
`options`	`TemplateImportOptions`

Returns: Promise<void>

isAttached

isAttached(): boolean

Returns if Printess is currently attached to the DOM.

Returns: boolean

isBuyer

isBuyer(): boolean

Returns if still in Buyer Mode (Design Side Only)

Returns: boolean

isBuyerDesigner

isBuyerDesigner(): boolean

Returns if Current user has elevated buyer-rights

Returns: boolean

isInDesignerMode

isInDesignerMode(): boolean

Returns true if printess has full Designer edit rights and is not running in Shop-Mode

Returns: boolean

load

load(templateNameOrSaveToken: string, mode?: "auto" | "loadAlwaysFromServer"): Promise<void>

Loads template or previously saved buyer artwork (saveToken)

Parameter	Type	Description
`templateNameOrSaveToken`	`string`	a templateName or a `saveToken` you have received from basket- or back-callback or from `save()` call
`mode?`	`“auto” \| “loadAlwaysFromServer”`

Returns: Promise<void>

Used in these examples:

loadedFromSaveToken

loadedFromSaveToken(): boolean

Returns if currently loaded template is loaded from a save token.

Returns: boolean

loadJson

This method is deprecated.

loadJson(saveToken: string): Promise<void>

Loads previously saved buyer artwork identified by a save-token.

Parameter	Type	Description
`saveToken`	`string`

Returns: Promise<void>

loadSavedShopTemplates

loadSavedShopTemplates(shopId: string, shopUserId: string, productId: string): Promise<{ entries: ISavedShopData[] }>

Load saved artwork from the shop

Parameter	Type	Description
`shopId`	`string`
`shopUserId`	`string`
`productId`	`string`

Returns: Promise<{ entries: ISavedShopData[] }>

loadTemplate

loadTemplate(templateNameOrToken: string, mergeTemplates?: iMergeTemplate[], takeOverFormFieldValues?: boolean, takeOverMatrixProduct?: boolean, clearExchangeCaches?: boolean, templateVersion?: "draft" | "published"): Promise<void>

Load a template to the Printess editor. Supports ‘exchangeId’ on document level. Docs with matching exchange-id’s will transfer all user changes.

Parameter	Type	Description
`templateNameOrToken`	`string`	can be either the name of a template (case sensitive) or the save-token received as a result of a user design save.
`mergeTemplates?`	`iMergeTemplate[]`	optional parameter to pass other templates to merge
`takeOverFormFieldValues?`	`boolean`	optional parameter to transfer global form field values from previous to next document
`takeOverMatrixProduct?`	`boolean`	optional take over the matrix product value.
`clearExchangeCaches?`	`boolean`	optional clear exchange cache and last loaded scope, so no data is exchanged when a new template is loaded. Defaults to false.
`templateVersion?`	`“draft” \| “published”`	optional the template version to load, due to backward compatibility the default is “draft”, please always use “published” in the live shops.

Returns: Promise<void>

loadTemplateAndFormFields

loadTemplateAndFormFields(
    templateName: string,
    mergeTemplates?: iMergeTemplate[] | null,
    formFields?: iFormFieldNameValue[] | null,
    snippetPriceCategoryLabels?: string[] | null,
    formFieldProperties?: iFormFieldProperty[] | null,
    clearExchangeCaches?: boolean,
    templateVersion?: "draft" | "published"): Promise<void>

Load a template to the Printess editor and sets form fields. Supports ‘exchangeId’ on document level. Docs with matching exchange-id’s will transfer all user changes.

Parameter	Type	Description
`templateName`	`string`	can be either the name of a template (case sensitive) or the save-token received as a result of a user design save.
`mergeTemplates?`	`iMergeTemplate[] \| null`	optional parameter to pass other templates to merge
`formFields?`	`iFormFieldNameValue[] \| null`	optional parameter to pass global form field values
`snippetPriceCategoryLabels?`	`string[] \| null`	optional parameter to pass snippetPriceCategoryLabels
`formFieldProperties?`	`iFormFieldProperty[] \| null`	optional form field properties to adjust after load
`clearExchangeCaches?`	`boolean`	optional clear exchange cache and last loaded scope, so no data is exchanged when a new template is loaded. Defaults to false.
`templateVersion?`	`“draft” \| “published”`	optional the template version to load, due to backward compatibility the default is “draft”, please always use “published” in the live shops.

Returns: Promise<void>

Used in these examples:

Load different templates after initializing

loadTemplateWithExchangeToken

loadTemplateWithExchangeToken(templateName: string, saveToken: string, publishedVersion?: boolean): Promise<void>

Loads template first and then exchange state from save-token.

Parameter	Type	Description
`templateName`	`string`	name of template to load
`saveToken`	`string`	save-token to extract exchange state from
`publishedVersion?`	`boolean`	optional, default is true.

Returns: Promise<void>

persistExchangeState

persistExchangeState(frames?: boolean, documents?: boolean, formFields?: boolean): Promise<void>

Should be called before redirecting to a new template. Will save the current state to the browser storage and apply it automatically to the next loaded template Applies Frame and Document exchange-ids as well as template-wide form fields

Parameter	Type	Description
`frames?`	`boolean`	(default true) add frame exchange-ids (image, text, story)
`documents?`	`boolean`	(default true) add documents with exchange-ids
`formFields?`	`boolean`	(default true) add all user-defined form fields on template level

Returns: Promise<void>

save

save(): Promise<string>

Saves current artwork

Returns: Promise<string> — saveToken which you can pass on attachPrintess() or load()

saveAndPublish

This method is deprecated.

saveAndPublish(name: string): Promise<void>

Saves and publishes the template.

Parameter	Type	Description
`name`	`string`	The name you want to save the template under.

Returns: Promise<void>

saveJson

This method is deprecated.

saveJson(): Promise<string>

Saves current artwork and returns a save-token.

Returns: Promise<string>

saveTemplateToShop

saveTemplateToShop(savedShopData: ISavedShopData): Promise<void>

Saves current artwork to the shop

Parameter	Type	Description
`savedShopData`	`ISavedShopData`	relevant shop data for saving artwork

Returns: Promise<void>

setCallbacks

setCallbacks(p: printessCallbacks): void

Reassign/change callbacks originally set in attachPrintess().

Parameter	Type	Description
`p`	`printessCallbacks`

Returns: void

shopToken

shopToken(): string

retrieves the current shop token

Returns: string

showAlertOnClose

showAlertOnClose(): boolean

Indicates if UI should show an alert prompt when user attempts to leave the buyer-side

Returns: boolean

showSaveAndCloseButton

showSaveAndCloseButton(): boolean

Returns if UI should display a button to save and close the current work in the buyer side

Returns: boolean

showSaveButton

showSaveButton(): boolean

Returns if UI should display a button to save the current work in the buyer side

Returns: boolean

unexpireJson

unexpireJson(saveToken: string): Promise<void>

Expects a previously saved buyer artwork identified by a saveToken and ensures that this work will never be deleted from DB

Parameter	Type	Description
`saveToken`	`string`

Returns: Promise<void>