Template CRUD

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

addFrame

addFrame(spreadId: string, frame: ImportFrame): Promise<iExternalModifyResult>

Adds a frame to a spread that already exists, from the same ImportFrame an import would use - so whichever of image/text/shape/pathText/document the spec carries decides what kind of frame it is. It lands on top of the frames already on the spread. Give it a jsName if a script will address it later. spreadId is the id an export reported for the spread.

Returns: Promise<iExternalModifyResult>

addSpreadToDocument

addSpreadToDocument(nameOrId: string, count?: number): Promise<iExternalDocumentResult>

Appends spreads to a document and reports their ids. Takes a document name or id.

They are laid out as the page panel’s “add after the last page” does it. In a single-page document every new spread is one page. In a facing-pages document the old back page gains its right-hand page and becomes an inside spread, and the last new spread is the new single back page - so two added to a lone cover make a folded card, 1 · 2-3 · 4. message names the pages that result.

Returns: Promise<iExternalDocumentResult>

createDocument

createDocument(doc: ImportDocument, options?: { unit?: string, progressCallback?: (x: string) => void }): Promise<iExternalDocumentResult>

Creates a document from one ImportDocument and reports the ids it made.

The same vocabulary a whole-template import uses, so everything a document can carry is available here - spreads, bleed, margins, layers, per-document form fields, background colour, facing pages, book and cover geometry. It runs the importer rather than a second creation path, which is why: anything the importer learns, this gets.

Two things it does that importTemplate would not. Existing documents are always kept - the import default replaces the image library and deletes every document, which is never what “add a document” means. And isEditable defaults to true, because the spread listing reports only editable documents, so a non-editable new document has no discoverable spread id and nothing can be added to it.

pageWidth / pageHeight are lengths in unit, which defaults to the open document’s unit: a bare number, or {value, unit} - never a unit-suffixed string, and never relative or an equation, since a page has no parent to measure against. The frame verbs take lengths the same way. An ImportSpread carries no page count (it is { id?, label?, frames? }); how many pages a spread covers is derived from its position and hasFacingPages, so one plain spread is {}. Progress is silent unless you pass progressCallback; the editor’s own overlay is the fallback otherwise, which is wrong over a buyer mid-interaction.

Returns: Promise<iExternalDocumentResult>

duplicateDocument

duplicateDocument(nameOrId: string, newName?: string, size?: iExternalDocumentSize): Promise<iExternalDocumentResult>

Copies a document - its spreads, frames, stories and per-document form fields - and optionally gives the copy a different page size. Takes a document name or id.

The copy is inserted directly after its original and never selected, so the buyer stays on the spread they are on.

newName is what to call the copy. A name addresses a document, so no two can share one - and rather than refuse, this numbers up from the name it was given: omit newName and "Front" becomes "Front 2", pass a "Back" that already exists and the copy is "Back 2". So the call never fails over a name, and the name you asked for is not guaranteed. message names the copy; there is no structured field for the name, since docId and spreadIds are what a caller needs in order to populate it. Pass undefined to skip it and give a size.

size is { width, height, unit? } - two numbers plus the unit they are written in, never a unit-suffixed string. unit defaults to the source document’s own unit and interprets the numbers only; it does not become the copy’s unit. %, %%, <% and equations are refused, because a page has no parent axis to measure against. Resizing is a real relayout of the copy’s spreads, margins, bleed and pasteboard, and it never touches the original. A document that takes its size from the DocumentSize form field cannot be given one here.

Returns: Promise<iExternalDocumentResult>

exportDocument

exportDocument(nameOrId?: string): Promise<iExternalExportResult>

One whole document as a TemplateImportTask - every spread, every frame, every resource. Takes a document name or id; defaults to the open document. Large on a multi-spread document: prefer exportSpread unless the task really spans the document.

Returns: Promise<iExternalExportResult>

exportFrame

exportFrame(frameId: string): Promise<iExternalExportResult>

One frame as a TemplateImportTask, with every property it carries. Takes a frame id, jsName or title. The cheapest read before modifyFrame, since a patch resolves against what is there.

Returns: Promise<iExternalExportResult>

exportSpread

exportSpread(spreadRef?: string): Promise<iExternalExportResult>

One spread as a TemplateImportTask: every frame with its geometry, text, image, shape and effects, plus the fonts, colours and images it references.

Takes a spread id or a "<document> / <page>" address from templateOutline; defaults to the spread on screen. This is the read half of read-modify-write, and the only way to discover the frame ids the verbs below need.

Returns: Promise<iExternalExportResult>

exportTemplate

exportTemplate(): Promise<iExternalExportResult>

The entire template as a TemplateImportTask. The complete truth and by far the biggest answer - templateOutline for structure, exportDocument or exportSpread for content.

Returns: Promise<iExternalExportResult>

modifyDocument

modifyDocument(nameOrId: string, patch: iExternalModifyDocumentPatch): Promise<iExternalDocumentResult>

Patches a document - name, page size, facing pages, buyer-editability. Takes a document name or id. Only the keys present in the patch change, all as one undo step.

facingPages re-lays the pages the way the page panel’s toggle does: the first and last spread get one page and every spread between them two, or every spread one page when it is turned off. A page that goes leaves its frames on the spread beyond the page edge; message counts them and names the pages that result.

Returns: Promise<iExternalDocumentResult>

modifyFormField

modifyFormField(nameOrId: string, patch: Partial<ImportFormField>): Promise<iExternalModifyResult>

Changes the properties of a form field that already exists - how it looks and behaves, its list entries, its table columns and its value. The counterpart to createFormField, which deliberately never overwrites.

patch is a Partial<ImportFormField> and is a patch: a key left out keeps its current value. It takes readable names - { label: "Your name", mandatory: true } - not the store’s short keys. items (list entries), tableColumns and value (a JSON array of rows on a table field) are collections and are replaced wholesale, so read the field first and send the whole array.

Refused rather than applied: name (renaming breaks every form.<name>, ${…} expression and On Change Script that names the field), and anything that is not an ImportFormField property - including the short keys of the internal store this used to take, and the internals no patch may set at all (order, document-vs-global). An out-of-range type / ui / visibility / tableUi is refused too, because a FormField rebuilt from a store falls back to a default for a value it does not recognise - which would silently reset the control instead of failing. The field must be global or on the open document; one on another document is reported.

Returns: Promise<iExternalModifyResult>

modifyFrame

modifyFrame(frameId: string, patch: Partial<ImportFrame>): Promise<iExternalModifyResult>

Position, size, anchoring and rotation, the names the frame is addressed by (jsName, title), its style classes, layer, lock, visibility and buyer step - plus the content the frame carries: text, shape, pathText, effects, basics (clipping) and image. Geometry resolves against the frame’s current size when the patch does not restate it, so moving a frame needs only left/top.

A patch throughout: what the patch does not name keeps its value, the content sub-objects included - {"shape":{"fillColor":"Navy"}} recolours the shape and keeps its path, where setFrameShape rebuilds the shape from the spec and resets what the spec omits. image is the exception and is a replace either way, the same operation as setFrameImage.

What it cannot do is give a frame a feature it does not have: a text patch needs a single-line text frame, a shape patch a frame that has a shape (name a shape to build one). Those are the set* verbs’ job, and are reported rather than silently skipped. A colour the template cannot resolve is reported too, instead of landing as black.

Returns: Promise<iExternalModifyResult>

removeDocument

removeDocument(nameOrId: string): Promise<iExternalDocumentResult>

Removes a document and its frames. Refused when it is the only one.

Returns: Promise<iExternalDocumentResult>

removeFrame

removeFrame(frameId: string): Promise<iExternalModifyResult>

Deletes a frame.

Returns: Promise<iExternalModifyResult>

removeFrameImage

removeFrameImage(frameId: string): Promise<iExternalModifyResult>

Removes the image from a frame; the frame stays where it is, carrying no image.

Returns: Promise<iExternalModifyResult>

removeSpread

removeSpread(spreadRef: string): Promise<iExternalDocumentResult>

Removes one spread and its frames. Takes a spread id or a "<document> / <page>" address. Refused when it is the last spread of its document - remove the document instead.

Returns: Promise<iExternalDocumentResult>

replaceSpread

replaceSpread(spreadId: string, task: TemplateImportTask): Promise<iExternalModifyResult>

Replaces everything on one spread with the frames of a whole TemplateImportTask - the way to put a design onto a spread that already exists, rather than a frame at a time.

What importTemplate cannot do: that only ever creates documents, so a task aimed at the open document lands as a second document beside it. Here the task’s resources (fonts, colours, images, AI images, stories, form fields) are registered first and then its frames replace the spread’s, so a design brings its own fonts and palette with it - which a run of addFrame calls cannot.

The task must hold exactly one document with one spread; more comes back as { ok: false } rather than being silently truncated. The document’s page size, bleed, layers and flags are ignored - the spread keeps the size it has and the frames are fitted to it, which is the point.

Removal and creation are one batch operation, so undo takes the whole spread back in one step.

Returns: Promise<iExternalModifyResult>

setDocumentFlags

setDocumentFlags(nameOrId: string, flags: iExternalDocumentFlags): Promise<iExternalDocumentResult>

Sets the boolean flags on a document - what the document is, rather than how it is laid out: whether its size follows a form field, whether it prints, whether the buyer may open it, whether it is a snippet. Takes a document name or id; only the keys present change, all as one undo step.

The whole patch is checked before any of it is written. A patch naming a flag this template type does not offer changes nothing and says which flag and which type - rather than applying the part it liked and leaving the document in a state the caller did not ask for. A flag already at the value you asked for is reported in message and not written again.

The flags mirror the document context menu and carry the same restrictions it shows, so anything set here is a state the designer UI can also explain and undo. isEditable is on modifyDocument too and means exactly the same thing in both - use whichever verb your other changes are already in.

Returns: Promise<iExternalDocumentResult>

setFrameEffects

setFrameEffects(frameId: string, effects: ImportEffects): Promise<iExternalModifyResult>

Replaces the frame’s opacity, blend mode and drop shadow. Opacity and blend mode fall back to their defaults when omitted, exactly as on import - modifyFrame(id, { effects: … }) patches them instead.

Returns: Promise<iExternalModifyResult>

setFrameImage

setFrameImage(frameId: string, image: ImportImage): Promise<iExternalModifyResult>

Assigns an image, whether or not the frame already carries one - so this both changes the image of an image frame and turns a frame without one into an image frame. Rebuilds the image reference, so an existing crop or scale is reset to a fresh fit/fill. image.id is a template image id, name or url, or "placeholder".

Returns: Promise<iExternalModifyResult>

setFrameShape

setFrameShape(frameId: string, shape: ImportShape): Promise<iExternalModifyResult>

Replaces the frame’s shape, rebuilt from the given spec - so a property the spec omits goes back to its default, the path included. To change part of the shape a frame already has, patch it: modifyFrame(id, { shape: { fillColor: "Navy" } }).

Returns: Promise<iExternalModifyResult>

setFrameSimpleText

setFrameSimpleText(frameId: string, text: ImportSimpleText): Promise<iExternalModifyResult>

Replaces the single-line text of a text frame - the text and the font it is set in. Fails when the frame is not a text frame. To change one property and keep the rest, patch it instead: modifyFrame(id, { text: { fillColor: "Navy" } }).

Returns: Promise<iExternalModifyResult>

setFrameTransform

setFrameTransform(frameId: string, transform: ImportTransform): Promise<iExternalModifyResult>

Replaces how the frame’s contents are bent out of their rectangle: a perspective taper, or a mesh - which is what wraps a design around a mug, a can or a bottle.

A replace: the transform the spec does not name is switched off, so {} flattens the frame again. modifyFrame(id, { transform: … }) patches it instead, keeping what it does not name.

A mesh with a cylinder in it is the one to reach for on anything round - it spaces the columns by sin(angle) and curves the two rims by different amounts, which a four-corner perspective cannot do at all.

Returns: Promise<iExternalModifyResult>

templateOutline

templateOutline(): Promise<iExternalTemplateOutline>

What exists and what it is called: documents with their page sizes, spreads with their live ids and page-number addresses, and which of each is open. No frame detail - cheap, and the first call for a host page that did not build the template itself.

Returns: Promise<iExternalTemplateOutline>