Data modes

The data mode (dataMode) decides where the product and print data come from and how much the customer can change before designing: Exact and Partial use the TronCloud catalog, Own uses the data you send. You choose it per call, so one shop can use Exact for catalog items and Own for products that aren't in the catalog. For the business view of the modes, see Integration Logic.

TIP

Examples: Exact (source) · Partial (source) · Own (source) · Codes that aren't found (source)

	Exact	Partial	Own
Product data	TronCloud catalog	TronCloud catalog	your request
You send	supplier, variant codes, printings	supplier and a model code or variant codes; printings optional	model, variants, printings with limits and images
The customer picks variants	no	yes	if you send none, or with showSelectedVariants Selected / All
The customer picks printings	only with showSelectedPrintOptions Selected / All	yes, also inside the editor	if you send none, or with showSelectedPrintOptions Selected / All
A code isn't found	error	the customer chooses instead	—
Builder	setExactProduct	setPartialProduct	setOwnProduct…, setOwnEmptyProduct
HTML attributes	yes	yes	data-td-own-product="true" (the customer enters the product) or data-td-options

If you leave dataMode out of the JSON, the editor uses Partial. The builder and the HTML attributes set it for you: with the builder, the last product setter you call decides the data mode, whatever the order of the printing calls. setDataMode() sets it explicitly — for example setPrintJob(guid, 'Edit').setDataMode('Exact') for an Edit session, which otherwise runs as Partial (see Open modes).

Identify the supplier

Exact and Partial need the supplier of the product — pass one of:

• Supplier code (supplierCode, data-td-supplier-code, first builder argument) — your own code for the supplier, e.g. the one from your ERP. You assign it in the Admin Portal under Settings → Suppliers (column Your Code / ID). It is resolved within your TronDesigner instance only. Use it when your system already has its own supplier codes.
• Supplier GUID (supplierGuid, data-td-supplier-guid, second builder argument) — the supplier's identifier in the PromoTron platform, the same for every instance. Use it when you store PromoTron identifiers anyway. If you pass both, the GUID wins.

If the supplier code isn't assigned in your instance, no product is found and the editor shows an error.

The model and variant codes are the supplier's own codes. The print position and technology codes (e.g. front / PAD03) belong to the product's print options in TronCloud; they are compared case-insensitively.

Exact mode

You specify the variants and the printings; the customer goes straight to designing and can't change them.

HTML

<button
  data-td-action="OpenCreate"
  data-td-supplier-code="PFC"
  data-td-product-codes='["10601321", "10601301"]'
  data-td-print-position-code="front"
  data-td-print-technology-code="GPE01"
>
  Design your notebook
</button>

JavaScript

window.tronDesigner
  .setExactProduct('PFC', undefined, (p) => p.addVariant('10601321').addVariant('10601301'))
  .addExactPrinting('front', 'GPE01')
  .open({ mode: 'dialog' });

JSON

window.tronDesigner.openDesigner(
  {
    openMode: 'Create',
    dataMode: 'Exact',
    printJob: {
      addProducts: { supplierCode: 'PFC', variants: [{ productCode: '10601321' }, { productCode: '10601301' }] },
      addPrintings: [{ printPositionCode: 'front', printTechnologyCode: 'GPE01' }],
    },
  },
  { mode: 'dialog' }
);

• Required: the supplier, at least one variant code and at least one printing.
• No variant selector is shown. The print option selector appears only with showSelectedPrintOptions set to Selected or All (Editor options).
• Every code must exist for the product. If one doesn't, the editor shows an error and the customer can't continue.
• If TronCloud has no mockup for a printing, the customer picks or uploads a product image and marks the print area on it before designing. Send ownBackgroundUrls on the printing to offer your own images.

Show your own codes and names

The customer and the outputs can show your SKUs and names instead of the supplier's, and you can make the print limits stricter:

window.tronDesigner
  .setExactProduct('PFC', undefined, (p) =>
    p.addVariant('10601321', 50, 'NB-RED', 'Notebook red') // productCode, quantity, code and name shown
  )
  .addExactPrintings(undefined, {
    printPositionCode: 'front',
    printTechnologyCode: 'GPE01',
    printPositionDisplayName: 'Cover', // name shown instead of the catalog name
    maxWidth: 40, // mm, stricter than the catalog limit
    maxHeight: 20,
  })
  .open({ mode: 'dialog' });

In JSON these are overrides.productCode / overrides.productName on the variant and printPositionDisplayCode, printPositionDisplayName, printTechnologyDisplayCode, printTechnologyDisplayName, maxWidth, maxHeight, … on the printing. The HTML equivalents are the data-td-*-override(s) attributes (HTML data attributes).

Partial mode

You send the product model (and optionally some variants and printings); the customer picks the rest in a selection dialog before designing.

HTML

<button data-td-action="OpenCreate" data-td-supplier-code="PFC" data-td-model-code="100860">
  Design your bottle
</button>

JavaScript

window.tronDesigner
  .setPartialProduct('PFC', undefined, (p) => p.setProductModel('100860'))
  .open({ mode: 'dialog' });

JSON

window.tronDesigner.openDesigner(
  {
    openMode: 'Create',
    dataMode: 'Partial',
    printJob: {
      addProducts: { supplierCode: 'PFC', model: { modelCode: '100860' }, variants: [] },
      addPrintings: [],
    },
  },
  { mode: 'dialog' }
);

• Required: the supplier and a model code or at least one variant code. Without a model code, the model is found from the variant codes.
• Variants and printings you send are preselected. Whether the selector appears and what it offers is set by showSelectedVariants and showSelectedPrintOptions (Editor options). With nothing sent, the customer picks from everything the product offers.
• Inside the editor the customer can add another print position and remove printings (at least one stays).
• If the product has no print options in TronCloud, the customer defines the print position and technology in the selector.
• With the builder, setPartialProduct() sets Partial even if you call addExactPrinting() first.

Keep working when catalog codes change

Catalog data changes: a color is discontinued, a print position is renamed. In Partial mode a code that isn't found doesn't stop the customer. The editor drops it, opens the selector with a warning that lists the missing codes and keeps the found ones preselected. Variants and printings are evaluated independently.

With 'Missing', the selector appears only when something is missing and then offers everything the product has, so a valid request goes straight to the editor:

window.tronDesigner.openDesigner(
  {
    openMode: 'Create',
    dataMode: 'Partial',
    editorOptions: { showSelectedVariants: 'Missing', showSelectedPrintOptions: 'Missing' },
    printJob: {
      addProducts: { supplierCode: 'PFC', variants: [{ productCode: '10601321' }, { productCode: '10601331' }] },
      addPrintings: [
        { printPositionCode: 'front', printTechnologyCode: 'GPE01' },
        { printPositionCode: 'back', printTechnologyCode: 'GPE01' },
      ],
    },
  },
  { mode: 'dialog' }
);

With the builder, pass { showSelectedVariants: 'Missing' } as the options argument of setPartialProduct() and { showSelectedPrintOptions: 'Missing' } as the options argument of addExactPrinting(). If none of the printings you sent exists, the print option selector opens with all print options, whatever the option says.

Own mode

You send the whole product: model, variants and printings with their limits and images. Nothing is looked up in TronCloud and the supplier isn't used.

HTML

<!-- To send your own product data, put the JSON arguments into data-td-options -->
<button
  data-td-options='{"openMode":"Create","dataMode":"Own","printJob":{"addProducts":{"model":{"modelCode":"MUG-01","title":"Ceramic mug"},"variants":[{"productCode":"MUG-01"}]},"addPrintings":[{"printPositionCode":"front","printPositionDisplayName":"Front","printTechnologyCode":"DIGI","printTechnologyDisplayName":"Digital print","colorMode":"CMYK"}]}}'
>
  Design your mug
</button>

JavaScript

window.tronDesigner
  .setOwnProductSingleDimension('MUG-01', 'Ceramic mug', true, 'An 11 oz ceramic mug', (p) => {
    p.addVariant('MUG-01-RED', 'Red', ['#FF0000'], 'Ceramic mug red');
    p.addVariant('MUG-01-WHITE', 'White', ['#FFFFFF'], 'Ceramic mug white');
  })
  .addOwnPrinting('front', 'Front', 'PAD03', 'Pad print', 'Pantone', 3, 50, 50, undefined, undefined, [
    'https://shop.example.com/images/mug-front.png',
  ])
  .open({ mode: 'dialog' });

JSON

window.tronDesigner.openDesigner(
  {
    openMode: 'Create',
    dataMode: 'Own',
    printJob: {
      addProducts: {
        model: { modelCode: 'MUG-01', title: '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'],
        },
      ],
    },
  },
  { mode: 'dialog' }
);

Your product	Builder	JSON addProducts
One item without variants	setOwnProductSingleVariant(modelCode, modelName, description?, quantity?)	model with dimensionsCount: 0, one variant whose productCode is the model code
Variants in one dimension (colors or sizes)	setOwnProductSingleDimension(…) + addVariant(productCode, dimension1Title, dimension1Colors?, productName?, quantity?, ownPreviewUrl?)	variants with dimension1Title (and dimension1Colors if isDimension1Color is true)
Variants in two dimensions (color × size)	setOwnProductTwoDimensions(…) + addVariant(productCode, dimension1Title, dimension2Title, …)	variants with dimension1Title and dimension2Title
Let the customer enter the product	setOwnEmptyProduct(), or the HTML attribute data-td-own-product="true"	leave addProducts (or its model) out

Each own printing needs a colorMode — Pantone (spot colors, up to maxColors), CMYK (full color), SingleColor or Colorless (e.g. engraving). Sizes are in millimeters. All fields are described in Editor arguments.

When your data is incomplete, the editor asks the customer for the rest:

• No product (addProducts or its model missing): the customer enters the product and its variants.
• No printings: the customer defines the print positions and technologies.
• Product images: for every printing the customer picks or uploads a background image and marks the print area. If you send exactly one image in ownBackgroundUrls, it is used without asking, unless alwaysShowImageSelect is true.

When a code isn't found

Situation	Variant code not found	Printing not found
Create, Exact	Error: Selected product variants not found: …	Error: Selected print options not found: …
Create, Partial	Dropped; the variant selector opens with a warning. If no code is found and you sent no model code, the product isn't found: error.	Dropped; the print option selector opens with a warning
Create, Own	— (nothing is looked up)	—
Edit, adding variants or printings	Error	Error

Errors are also written to the browser console; see Debugging and error handling.

See also

• Editor arguments — every field of addProducts and addPrintings
• JavaScript builder API — the product and printing setters
• Open modes — create, edit or view a print job
• DataMode and ArgAddProduct in the API reference