HTML data attributes

Turn any button into an editor launcher by adding data-td-* attributes — no JavaScript needed. Use this when your product pages are rendered on the server and the product data is available in the template. This page covers the attributes of action elements; the attributes of the <script> tag are described in Loading the integration script.

TIP

Examples: Attributes - Overview · source — Custom Properties · source

How it works

When the integration script has finished initializing, it searches the page for elements with data-td-action="OpenCreate", "OpenEdit" or "OpenView", or with a data-td-options attribute. For each element with a valid set of attributes it attaches a click handler. On click it reads the attributes, converts them into EditorArguments and opens the editor as a dialog.

• Elements without a valid set of attributes are skipped. The console shows cannot initialize element for action: openDesigner - missing required data props.
• Attribute values are read when the customer clicks, so you can change them on a registered element (for example when the customer picks another color) without re-registering it.
• The script doesn't cancel the element's default action. Use <button type="button">: a plain <button> inside a <form> would also submit the form, and an <a href> would also navigate.
• data-td-action="RenderVisualization" on an <img> does something else — it renders a logo visualization. See Logo visualizations.

There are two ways to describe what the editor opens:

Mode	Attributes	Use it for
Basic	data-td-action plus individual attributes (data-td-supplier-code, data-td-product-code, …)	Catalog products, product models, existing print jobs and an own product the customer enters.
Advanced	data-td-options with a complete EditorArguments JSON	Everything else: own product data, custom buttons, logos, result dialogs with your own texts.

If an element has data-td-options, the advanced mode wins and all basic attributes on that element are ignored.

Basic mode

Valid attribute combinations

data-td-action is always required. Add one of these combinations:

To	Add	Data mode
Open a catalog product (OpenCreate)	supplier + product + print position + print technology	Exact
Let the customer choose variants of a product model (OpenCreate)	supplier + model code; print position and technology are optional	Partial
Edit or view an existing print job (OpenEdit / OpenView)	data-td-print-job-guid	—
Let the customer enter an own product (OpenCreate)	data-td-own-product="true" — see Own products	Own

• Supplier: data-td-supplier-code (the code set in the Admin Portal under Settings → Suppliers, e.g. PFC) or data-td-supplier-guid.
• Product: data-td-product-code (one variant) or data-td-product-codes (a JSON array).
• Print position / technology: data-td-print-position-code + data-td-print-technology-code, or the JSON array forms data-td-print-position-codes + data-td-print-technology-codes.
• Model: data-td-model-code. If you also set a product code, the product code wins and the editor opens in Exact mode.

data-td-action also sets the open mode: OpenCreate → Create, OpenEdit → Edit, OpenView → View (see Open modes). Use OpenCreate with product attributes and OpenEdit/OpenView with a print job GUID; don't combine a print job GUID with product attributes.

Exact product

<button
  type="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"
>
  Design your print
</button>

Product model

<button type="button" data-td-action="OpenCreate" data-td-supplier-code="PFC" data-td-model-code="100860">
  Choose a color and design
</button>

Existing print job

<button type="button" data-td-action="OpenEdit" data-td-print-job-guid="{PRINT_JOB_GUID}">
  Edit your design
</button>

Several variants and print options

Use the plural attributes with JSON arrays. Print positions and technologies are paired by position in the array, so both arrays must have the same length:

<button
  type="button"
  data-td-action="OpenCreate"
  data-td-supplier-code="PFC"
  data-td-product-codes='["R2200D94", "R2200E13"]'
  data-td-print-position-codes='["Left chest", "Right chest"]'
  data-td-print-technology-codes='["MR07", "MR07"]'
>
  Design both sides
</button>

• data-td-product-codes takes precedence over data-td-product-code, and data-td-print-position-codes over both singular print attributes. data-td-print-technology-codes is used only together with data-td-print-position-codes. Don't mix singular and plural forms — for example, a singular technology code doesn't apply to plural position codes.
• The values must be valid JSON (double quotes inside a single-quoted attribute). Invalid JSON makes the click fail with a console error, and the editor doesn't open.

Show your own codes and names

By default the editor shows the catalog codes and names. The override attributes replace what the editor displays:

Displayed value	Single	Array (paired with the plural code attribute)
Product variant code	data-td-product-code-override	data-td-product-code-overrides
Product variant name	data-td-product-name-override	data-td-product-name-overrides
Print position code	data-td-print-position-code-override	data-td-print-position-code-overrides
Print position name	data-td-print-position-name-override	data-td-print-position-name-overrides
Print technology code	data-td-print-technology-code-override	data-td-print-technology-code-overrides
Print technology name	data-td-print-technology-name-override	data-td-print-technology-name-overrides

<button
  type="button"
  data-td-action="OpenCreate"
  data-td-supplier-code="PFC"
  data-td-product-code="10086021"
  data-td-product-code-override="OREGON-400-RED"
  data-td-product-name-override="Oregon 400 ml, red"
  data-td-print-position-code="front"
  data-td-print-technology-code="PAD03"
  data-td-print-technology-name-override="Pad print"
>
  Design your print
</button>

Attach order information and custom properties

Store your own references on the print job so you can match it to your order later (in webhooks, the REST API or getPrintJob):

Attribute	Stored in the print job as
data-td-order-code	customer.orderCode
data-td-order-title	customer.orderTitle
data-td-order-item-code	customer.orderItemCode
data-td-custom-properties	customProperties — a JSON object with string values, e.g. {"cartItemId":"4711"}. Invalid JSON is ignored.

NOTE

Earlier versions of the script saved data-td-order-title and data-td-order-code swapped. Print jobs saved by those versions keep the swapped values. If you swapped your attribute values to compensate, swap them back — see the Changelog.

<button
  type="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-order-code="SO-2026-0042"
  data-td-order-item-code="3"
  data-td-custom-properties='{"cartItemId": "4711", "campaign": "SPRING26"}'
>
  Design your print
</button>

More about linking print jobs to customers and orders: Customers and orders.

Control what happens after confirmation

data-td-result-action decides what the editor does when the customer confirms the final check of their print job:

Value	Behavior
None	The print job is saved and the customer stays in the editor.
Close	The print job is saved and the editor closes. If data-td-result-redirect-url is set, the browser then goes to that URL.
Dialog	The print job is saved and the editor shows its standard confirmation dialog. If data-td-result-redirect-url is set, the browser goes to that URL when the customer closes the dialog.

Values are case-sensitive; any other value makes the click fail with a console error. Without data-td-result-action, the result action configured in the Admin Portal (Settings → Print editor) applies. A confirmation dialog with your own texts needs advanced mode or JavaScript — see Result actions. If the customer closes the editor with × instead, there is no redirect (see Result actions).

<button
  type="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-result-action="Dialog"
  data-td-result-redirect-url="https://shop.example.com/cart"
>
  Design and add to cart
</button>

Own products

A button with data-td-action and data-td-own-product="true" opens the editor in the Own data mode, in which the customer enters the product data in the editor — the same as setOwnEmptyProduct() in the JavaScript builder:

<button type="button" data-td-action="OpenCreate" data-td-own-product="true">
  Design your own product
</button>

Own product wins over the other product attributes: if the element also has supplier, product, model or printing attributes, the script ignores them and writes a warning to the console. To send your own product data (model, variants, print areas), use advanced mode or the builder (setOwnProductSingleVariant(), …); see Data modes.

Advanced mode: data-td-options

Put a complete EditorArguments object into data-td-options. Wrap the attribute value in single quotes so you can use double quotes inside the JSON:

<button
  type="button"
  data-td-options='{
    "openMode": "Create",
    "dataMode": "Exact",
    "editorOptions": { "showSelectedVariants": "None", "showSelectedPrintOptions": "None" },
    "printJob": {
      "addProducts": {
        "supplierCode": "PFC",
        "variants": [{ "productCode": "R2200D94" }, { "productCode": "R2200E13" }]
      },
      "addPrintings": [
        { "printPositionCode": "Left chest", "printTechnologyCode": "MR07" },
        { "printPositionCode": "Right chest", "printTechnologyCode": "MR07" }
      ],
      "customProperties": { "cartItemId": "4711" }
    },
    "editor": {
      "result": { "resultAction": "Dialog", "redirectUrl": "https://shop.example.com/cart", "closeDialog": [] }
    }
  }'
>
  Design your T-shirt
</button>

• openMode and printJob are required. editorOptions defaults to None / None when omitted.
• With "resultAction": "Dialog", closeDialog is optional; without it (or with []) the editor shows the built-in texts. See Result actions.
• data-td-action isn't needed; the open mode comes from openMode.
• If the JSON can't be parsed, the click logs openDesigner is misconfigured because 'data-td-options' cannot be parsed and the editor doesn't open.
• When you generate the attribute on the server, HTML-escape the value (at least ' → ') so a value containing an apostrophe doesn't end the attribute.
• The element always opens a dialog. To show the editor inside your page, call openDesigner with { mode: 'container', … }.

The JSON structure is described in Editor arguments.

Dynamic content

The script scans the page once, when initialization finishes. What you need to do when the page changes later:

The page changes like this	What to do
You change attribute values of an element that is already registered	Nothing — values are read on click.
You add action elements after initialization (AJAX, infinite scroll, single-page app)	Call refreshRegisteredElements(), or monitor a container.
An existing element becomes valid later (e.g. you set data-td-print-job-guid after a print job was created)	Call refreshRegisteredElements(). Monitoring doesn't detect attribute changes.
You remove action elements	Nothing.

Rescan the page

refreshRegisteredElements() scans the whole document again and attaches handlers to new valid elements. Elements that are already registered don't get a second handler, so you can call it after every update. It also picks up new logo visualization images.

function onPrintJobCreated(event) {
  const editButton = document.getElementById('edit-button'); // has data-td-action="OpenEdit"
  editButton.setAttribute('data-td-print-job-guid', event.entityGuid);
  window.tronDesigner.refreshRegisteredElements();
}

If you control when your content changes, calling refreshRegisteredElements() after each change is the simplest option.

Monitor a container

To register elements automatically as they are added, give the script the id of a container. The element must exist when initialization finishes:

Script attribute

<script
  async
  src="https://app.trondesigner.com/js/website-integration.js"
  referrerpolicy="origin"
  data-td-api="https://app.trondesigner.com/api"
  data-td-api-key="{API_KEY}"
  data-td-monitored-element-id="product-list"
></script>

<div id="product-list">
  <!-- product cards with action buttons are rendered here later -->
</div>

JavaScript

// After the script is initialized and the container exists (e.g. when your view is mounted):
window.tronDesigner.subscribeElementChanges(document.getElementById('product-list'));

// When the view is destroyed:
window.tronDesigner.unsubscribeElementChanges();

While monitoring, the script watches the container's whole subtree. When an action element is added — directly or inside an added element, with appendChild(), innerHTML, insertAdjacentHTML() or a framework — it's registered; when it's removed, its handler is removed. Only child additions and removals are detected, not attribute changes. Only one container is monitored at a time: subscribeElementChanges() replaces the current one (including the one from data-td-monitored-element-id), and unsubscribeElementChanges() stops monitoring.

See also

• BasicActionElementDataAttributesNames — attribute constants (API reference)
• Data attributes reference — every attribute in one table
• JavaScript builder API — the same options from JavaScript
• Events and callbacks — get the print job GUID back