Custom properties

Attach your own metadata to a print job, show design instructions, and suggest customer brand colors in the editor. You pass all of these through printJob.customProperties using HTML attributes, the JavaScript builder, or JSON.

TIP

Example: Custom properties · source

Add custom properties

Custom properties are your own key/value pairs. TronDesigner stores them in the print job unchanged and returns them to you. Values are strings.

HTML

<button
  data-td-action="OpenCreate"
  data-td-supplier-code="PFC"
  data-td-product-code="10086021"
  data-td-print-position-code="front"
  data-td-print-technology-code="PAD03"
  data-td-custom-properties='{"cartLineId":"CL-882","campaign":"SPRING24"}'
>Design your print</button>

JavaScript

window.tronDesigner
  .addCustomProperties({ cartLineId: 'CL-882', campaign: 'SPRING24' })
  .addCustomProperty('region', 'EU')
  .setExactProduct('PFC', undefined, (p) => p.addVariant('10086021'))
  .addExactPrinting('front', 'PAD03')
  .open({ mode: 'dialog' });

JSON

{
  "openMode": "Create",
  "dataMode": "Exact",
  "printJob": {
    "customProperties": { "cartLineId": "CL-882", "campaign": "SPRING24", "region": "EU" },
    "addProducts": { "supplierCode": "PFC", "variants": [{ "productCode": "10086021" }] },
    "addPrintings": [{ "printPositionCode": "front", "printTechnologyCode": "PAD03" }]
  }
}

• data-td-custom-properties must be valid JSON; if it can't be parsed, it is silently ignored.
• customProperties belongs inside printJob, not at the top level of the editor arguments.
• In Edit mode the properties you pass are merged into the stored ones: you can add or overwrite keys, not remove them.

Show design instructions in the editor

Use the special custom property EDITOR:DESIGN_INSTRUCTION to give the customer instructions while they design their print. The editor displays its value as an informational notification labeled Design instructions: at the bottom of the design canvas, before any other informational messages. The instructions apply to the whole print job.

HTML

<button
  data-td-action="OpenCreate"
  data-td-supplier-code="PFC"
  data-td-product-code="10086021"
  data-td-print-position-code="front"
  data-td-print-technology-code="PAD03"
  data-td-custom-properties='{"EDITOR:DESIGN_INSTRUCTION":"Place your logo in the center of the print area."}'
>
  Design your print
</button>

JavaScript

window.tronDesigner
  .addCustomProperty(
    'EDITOR:DESIGN_INSTRUCTION',
    'Place your logo in the center of the print area.'
  )
  .setExactProduct('PFC', undefined, (p) => p.addVariant('10086021'))
  .addExactPrinting('front', 'PAD03')
  .open({ mode: 'dialog' });

JSON

{
  "openMode": "Create",
  "dataMode": "Exact",
  "printJob": {
    "customProperties": {
      "EDITOR:DESIGN_INSTRUCTION": "Place your logo in the center of the print area."
    },
    "addProducts": { "supplierCode": "PFC", "variants": [{ "productCode": "10086021" }] },
    "addPrintings": [{ "printPositionCode": "front", "printTechnologyCode": "PAD03" }]
  }
}

Use the key exactly as shown. The notification appears only when the value is a non-empty string. Like other custom properties, the instructions are saved with the print job. In Edit mode, pass the same key to update them, or an empty string to hide the notification. Omitting the key keeps the saved value.

Suggest design colors in the editor

Pass any number of customer brand colors using case-sensitive custom-property keys EDITOR:DESIGN_COLOR_<number>, such as EDITOR:DESIGN_COLOR_1 or EDITOR:DESIGN_COLOR_10. The suffix must be a non-negative integer. Colors are shown in numeric order; gaps are allowed. Each value has the format Source:ColorValue:

Source	Format	Example
PMS	Full color-map Pantone name	PMS:PANTONE 185 C
RGB	Six RGB or eight RGBA hexadecimal digits with #; omitted alpha means FF (opaque)	RGB:#EB002A or RGB:#EB002AFF
CMYK	Four hexadecimal channel bytes with # (0–255 per channel)	CMYK:#00F8D000

HTML

<button
  data-td-action="OpenCreate"
  data-td-supplier-code="PFC"
  data-td-product-code="10086021"
  data-td-print-position-code="front"
  data-td-print-technology-code="PAD03"
  data-td-custom-properties='{"EDITOR:DESIGN_COLOR_1":"PMS:PANTONE 185 C"}'
>Design your print</button>

JavaScript

window.tronDesigner
  .addCustomProperty('EDITOR:DESIGN_COLOR_1', 'PMS:PANTONE 185 C')
  .setExactProduct('PFC', undefined, (p) => p.addVariant('10086021'))
  .addExactPrinting('front', 'PAD03')
  .open({ mode: 'dialog' });

These properties use the same custom-property transport as your other metadata. The editor trims surrounding whitespace and ignores casing in sources and color values. It requires an exact match in the corresponding field of its color map; it does not choose the nearest color. Consequently, a syntactically valid RGB or CMYK value can still be unmatched.

Encode a CMYK value

Use CMYK:#CCMMYYKK: eight hexadecimal digits after #, grouped into four pairs in cyan, magenta, yellow, black order. Each pair is one channel byte from 00 (0%) to FF (100%). The last pair is black, not alpha. This format uses channel bytes rather than the usual four percentage values.

For example, CMYK:#00F8D000 splits into:

Channel	Hexadecimal byte	Decimal value	Approximate percentage
Cyan	00	0	0%
Magenta	F8	248	97%
Yellow	D0	208	82%
Black	00	0	0%

To express a percentage as a byte, calculate Math.round(percent * 255 / 100), convert it to hexadecimal, and pad it to two digits. For example, 100% cyan with the other channels at 0% is CMYK:#FF000000. The resulting value must still match a CMYK entry in the editor's color map exactly; rounding percentages from a color chart does not guarantee a match.

Use suggested colors

The editor displays the supplied colors in a Suggested Colors section in existing logo and text color selectors. A matched entry uses the map's equivalent color for the current selector. Invalid or unmatched entries remain visible but disabled, with an error indicator. A temporary map-loading failure allows editing to continue and offers a retry in the suggestions section.

When exactly one non-empty property is supplied and matches the map, automatic logo adaptation recolors the entire logo to that color for Pantone, CMYK, and SingleColor print modes. Colorless print modes keep their normal behavior. Multiple supplied colors prevent automatic recoloring, even if only one matches or all supplied values resolve to the same color. Empty values are ignored, and missing slot numbers are allowed.

Automatic recoloring respects the editor's logo-preprocessing setting. Recolorable logos do not require an AI vectorization license; if vectorization is necessary, the existing license requirements apply. Logos that cannot be prepared for recoloring retain normal adaptation. The existing adaptation confirmation allows the customer to accept the preview or keep the original logo.

This applies to the initial integration logo and later uploads or replacements. Reopening a saved print job, changing properties, or retrying a failed map request does not recolor logos already placed in the design. Existing Edit-mode custom-property merging still applies.

Read custom properties from a saved print job

Custom properties are returned in event.detail.customProperties of the printJob events (Events and callbacks), in getPrintJob(), and in the REST API print job. You can also find them in the Admin Portal print job detail. Custom proofreading templates can use them too. Do not put secrets into custom properties.

See also

• addCustomProperty, addCustomProperties — API reference
• Editor arguments — the full printJob object
• Customers and orders — customer, order, and cart information
• Events and callbacks — get the saved print job back