Editor arguments

The editor arguments (EditorArguments) are one JSON object that tells the editor what to open and how to behave. You pass it to openDesigner, put it in a data-td-options attribute or send it URL-encoded in the options parameter of the Integration via URL. The JavaScript builder API produces the same object.

TIP

Examples: Exact (source) · Partial (source) · Own (source) · Edit an existing print job (source) · Editor options – Missing (source)

The object at a glance

window.tronDesigner.openDesigner(
  {
    openMode: 'Create', // Create | Edit | View | OpenGallery | OpenUpload
    dataMode: 'Exact', // Exact | Partial | Own
    editorOptions: { showSelectedVariants: 'None', showSelectedPrintOptions: 'None' },
    printJob: {
      addProducts: { supplierCode: 'PFC', variants: [{ productCode: '10086021' }] },
      addPrintings: [{ printPositionCode: 'front', printTechnologyCode: 'PAD03' }],
    },
    editor: { result: { resultAction: 'Close' } },
  },
  { mode: 'dialog' }
);

Field	Required	Description
openMode	yes	Create a new print job, edit or show an existing one, or open the logo dialog. See Open modes.
dataMode	no, default Partial	Where the product data comes from: the TronCloud catalog (Exact, Partial) or your request (Own). See Data modes.
editorOptions	no	Which selection dialogs the customer sees before the editor. See Editor options.
printJob	yes	The print job to create or open. Use {} for OpenGallery and OpenUpload. See Print job.
editor	no	What happens after the customer confirms, custom buttons, proofreading template. See Editor behavior.

WARNING

All values are PascalCase strings and are compared exactly: "Create", "Exact", "None". An unrecognized open mode such as "CREATE" logs Unknown openMode "CREATE"… in the console and the editor closes right away with the close reason 'Error'.

openMode and printJob are checked before anything is shown: if one of them is missing, openDesigner() logs openDesigner: cannot open, the editor arguments need "openMode" and "printJob" … and does nothing.

What the editor checks

The editor validates the arguments when it opens. If a rule is broken, it shows an error and the customer can't continue:

Rule	Error shown
printJob.printJobGuid is set, but openMode isn't Edit or View	Invalid arguments - print job GUID can be used only in Edit or View mode
openMode is Edit or View without printJob.printJobGuid	Invalid arguments - Edit or View mode are not allowed without print job GUID
View mode with entries in addProducts.variants, removeProducts.variants, addPrintings or removePrintings	Invalid arguments - product variants and printings cannot be added or removed in View mode
Create in Exact or Partial mode without addProducts	Invalid arguments - create print job requires addProducts and addPrintings arguments
Exact without variants, or Partial without variants and model code	No product variants provided - create print job requires at least one product variant
Exact without printings	No printings provided - create print job requires at least one printing
A logo without guid and url	Failed to create print job - logo file is missing for some print options

Codes that aren't found in the catalog are handled per data mode — see Data modes.

Editor options

editorOptions (EditorOptions) controls the selection dialog the customer sees before the editor opens, when a new print job is created. showSelectedVariants applies to product variants, showSelectedPrintOptions to printings; both take the same values (ShowSelectedOptions):

Value	The selector is shown	The selector offers
None (default)	only if you passed no codes or a code wasn't found	the codes you passed that were found (everything, if you passed none)
Selected	always	only the codes you passed; the customer can deselect them but not add others
Missing	only if you passed no codes or a code wasn't found	everything the product offers; your codes are preselected
All	always	everything the product offers; your codes are preselected

• The variant selector is never shown in Exact mode, and a code that isn't found is an error there. In Exact mode only showSelectedPrintOptions: 'Selected' or 'All' shows a selector.
• In Edit and View mode no selector is shown; the options have no effect.
• If you leave editorOptions out, the script sends None for both.
• Missing works with openDesigner, data-td-options and the builder. Integration links generated through the REST API don't accept it yet.

Option	Type	Effect
showQuantityInputs	boolean	Initial state of the Enter quantities switch in the variant selector; the customer can still toggle it. Default false.
alwaysShowImageSelect	boolean	For a printing without a TronCloud mockup, the editor uses the image in ownBackgroundUrls directly when there is exactly one. true asks the customer to confirm or change the image anyway. Default false.

Print job

printJob (ArgPrintJob):

Field	Description
printJobGuid	GUID of an existing print job to open in Edit or View mode.
title	Title of the print job. In Edit mode it replaces the stored title.
languageCode	ISO 639-1 code (en, de, …) of the print job; product and print data are loaded in this language. Default: the editor language, otherwise en.
addProducts	The product and its variants (Create), or variants to add (Edit). See Products.
removeProducts	Edit mode: { variants: [{ productCode }] } to remove.
addPrintings	Printings to create (Create) or add (Edit). See Printings.
removePrintings	Edit mode: [{ printPositionCode, printTechnologyCode }] to remove.
customer	customerIdentity, customerPerson, customerCompany, customerEmail, orderTitle, orderCode, orderItemCode. In Create mode, missing customer fields fall back to the session customer; in Edit mode, missing fields keep their stored values. See Customers and orders.
customProperties	Your own string key/value pairs, returned with the print job. Edit mode merges them with the stored ones. Use EDITOR:DESIGN_INSTRUCTION to show design instructions, or EDITOR:DESIGN_COLOR_<number> to suggest design colors.
logo	{ guid } or { url } — logo placed on every printing that has no own logo, when a new print job is created (every data mode) and on printings added in Edit mode. If empty, the script uses the customer's selected logo. See Logos.

Products

addProducts (ArgAddProduct):

Field	Exact	Partial	Own
supplierCode or supplierGuid	one is required	one is required	not used
model.modelCode	—	model code; required if you pass no variants	required, your model code
model.title, model.description	—	—	product name and description
model.isDimension1Color	—	—	true if the first variant dimension is a color
model.dimensionsCount	—	—	number of variant dimensions (0, 1, 2). When set, every variant must have exactly that many dimension values (dimension1Title, dimension2Title); otherwise the editor stops with an error naming the variants
variants	at least one	optional, preselected in the variant selector	your variants

Each variant (ArgAddProductVariant):

Field	Description
productCode	Exact/Partial: the supplier's variant code. Own: your variant code.
quantity	Quantity of this variant, stored with the print job.
overrides.productCode, overrides.productName	Code and name shown in the editor and in the outputs instead of the catalog values. Own: productName is the variant name.
dimension1Title, dimension1Colors, dimension2Title, dimension2Colors	Own: e.g. "Red" and ["#FF0000"], "XL". Colors are hex values.
ownPreviewUrl	Own: URL of a preview image of the variant.

Printings

A printing is a print position plus a print technology. addPrintings is an array of ArgAddPrinting:

Field	Description
printPositionCode, printTechnologyCode	Required. The catalog codes (Exact, Partial) or your own codes (Own). The pair identifies the printing; codes are compared case-insensitively.
printPositionDisplayCode, printPositionDisplayName, printTechnologyDisplayCode, printTechnologyDisplayName	Code and name shown in the editor and in the outputs. Own: the names of your position and technology.
colorMode	Own: required. Pantone (spot colors, up to maxColors), CMYK (full color), SingleColor (one color) or Colorless (no color, e.g. engraving). Catalog printings use the color mode of the technology.
maxColors	Maximum number of colors.
maxWidth, maxHeight, maxDiameter	Maximum motive size in millimeters. For catalog printings they replace the technology limits.
maxArea	Maximum motive area (width × height) in square millimeters.
ownBackgroundUrls	URLs of product images. They are offered as the background when TronCloud has no mockup for the printing — always the case in Own mode.
logo	{ guid } or { url } — logo placed on this printing (in every data mode, and on printings added in Edit mode).
isCustom	Set by the builder (true for own printings). You don't need to send it.

Whether exceeding a limit is a warning or an error is configured in the Admin Portal (Settings → Print editor).

Editor behavior

editor (ArgEditor) overrides what is configured in the Admin Portal for this editor session:

Field	Description
result	{ resultAction: 'None' | 'Close' | 'Dialog', redirectUrl?, closeDialog? } — what happens after the customer confirms. closeDialog is an array with one { language, title, message, buttonText } per language; leave it out (or send []) to use the built-in texts. See Result actions.
buttons	Up to five custom footer buttons. See Custom editor buttons.
proofreadingArgs.templateTag	Tag of the proofreading PDF template to use instead of the configured one.

Editor features are controlled by your license and by Settings → Print editor → Behavior in the Admin Portal, not by the arguments.

Complete examples

Exact — two variants with display names, two printings

{
  "openMode": "Create",
  "dataMode": "Exact",
  "printJob": {
    "title": "Teak notebook – trade fair",
    "languageCode": "en",
    "addProducts": {
      "supplierCode": "PFC",
      "variants": [
        { "productCode": "10601321", "quantity": 50, "overrides": { "productCode": "NB-RED", "productName": "Notebook red" } },
        { "productCode": "10601301", "quantity": 50 }
      ]
    },
    "addPrintings": [
      { "printPositionCode": "front", "printTechnologyCode": "GPE01", "printPositionDisplayName": "Cover" },
      { "printPositionCode": "back", "printTechnologyCode": "GPE01", "maxWidth": 40, "maxHeight": 20 }
    ],
    "customer": { "orderCode": "ORDER-1001", "orderItemCode": "ORDER-1001-1" },
    "customProperties": { "cartItemId": "8f3c2a" }
  },
  "editor": { "result": { "resultAction": "Dialog", "redirectUrl": "https://shop.example.com/cart", "closeDialog": [] } }
}

Partial — model only, the customer picks variants and printings

{
  "openMode": "Create",
  "dataMode": "Partial",
  "editorOptions": { "showSelectedVariants": "All", "showSelectedPrintOptions": "Missing", "showQuantityInputs": true },
  "printJob": {
    "title": "Oregon bottle",
    "addProducts": { "supplierCode": "PFC", "model": { "modelCode": "100860" }, "variants": [] },
    "addPrintings": []
  }
}

Own — a product with color variants and a printing with product images

{
  "openMode": "Create",
  "dataMode": "Own",
  "printJob": {
    "addProducts": {
      "model": {
        "modelCode": "MUG-01",
        "title": "Ceramic mug",
        "description": "An 11 oz ceramic mug",
        "dimensionsCount": 1,
        "isDimension1Color": true
      },
      "variants": [
        { "productCode": "MUG-01-RED", "dimension1Title": "Red", "dimension1Colors": ["#FF0000"], "overrides": { "productName": "Ceramic mug red" } },
        { "productCode": "MUG-01-WHITE", "dimension1Title": "White", "dimension1Colors": ["#FFFFFF"], "overrides": { "productName": "Ceramic mug white" } }
      ]
    },
    "addPrintings": [
      {
        "printPositionCode": "front",
        "printPositionDisplayName": "Front",
        "printTechnologyCode": "PAD03",
        "printTechnologyDisplayName": "Pad print",
        "colorMode": "Pantone",
        "maxColors": 3,
        "maxWidth": 50,
        "maxHeight": 50,
        "ownBackgroundUrls": ["https://shop.example.com/images/mug-front.png"]
      }
    ]
  }
}

Edit — add a variant and remove a printing of an existing print job

{
  "openMode": "Edit",
  "dataMode": "Exact",
  "printJob": {
    "printJobGuid": "6f0b1c9e-2f53-4a5b-9d0e-3c1f8a7b2d44",
    "addProducts": { "variants": [{ "productCode": "10601331" }] },
    "removePrintings": [{ "printPositionCode": "back", "printTechnologyCode": "GPE01" }]
  }
}

Only the changes are sent; the variants and printings already in the print job aren't repeated. See Open modes.

Names from older documentation

Older articles and examples use names the editor doesn't read (or reads only partly). Use the current names:

Old	Current
printJob.product, printJob.printings	printJob.addProducts, printJob.addPrintings
product.modelCode	addProducts.model.modelCode
dimCount, isDim1Colors, dim1Title, dim1Colors, previewUrl	dimensionsCount, isDimension1Color, dimension1Title, dimension1Colors, ownPreviewUrl
printing overrides.printPositionCode / …Name, overrides.printTechnologyCode / …Name	printPositionDisplayCode, printPositionDisplayName, printTechnologyDisplayCode, printTechnologyDisplayName
printing overrides.maxColors, overrides.maxWidth, …	maxColors, maxWidth, … directly on the printing
printing mockup.backgroundUrls, mockup.printArea, pxToMm	ownBackgroundUrls; there is no print area configuration
closeDialog: { … }	closeDialog: [{ language, … }]
"CREATE", "EXACT", "NONE", "dialog"	"Create", "Exact", "None", "Dialog"
editor.features	not supported

See also

• EditorArguments and the related types in the API reference
• JavaScript builder API — the same arguments built step by step
• Data modes · Open modes
• HTML data attributes — data-td-options takes this JSON