Offer several templates

A storefront can offer the customer several templates for one product and let them switch between them in the one designer, never mounting it again.

Switching to another template

When your store lets the customer try another template (another layout of the same sign, a cap instead of a sign), switch the designer to it without mounting it again:

await designer.setTemplate('graduation-sign-stars@2');

What the customer entered in a setting with a field key is shown in every setting of the new template with the same key: give the name on both templates the key name, and the name the customer typed is on the new one. A key the new template has no setting for is kept, and shows again when the customer switches back; so does whatever they entered in settings without a key. A picture’s crop is not carried, since it was framed for the other template; when the customer switches back to a picture they have not changed, its crop is back too.

A form of your own, drawn again for the new template, shows each field’s value with designer.getValue(layerId, prop): what the customer entered, carried by its key too, or the template’s own.

setTemplate() takes any template your key may read, and resolves once the new template is drawn. An upload or a resolution improvement still under way lands in the template it was started on first, then moves with the switch like any other value, so the switch waits for it. A template your key may not read rejects with an PixonautApiError, and the designer keeps the template it had. A value the new template does not allow, such as a name too long for its box, still switches: its field shows it, approve() reports what it breaks, and the preview is drawn once the customer has corrected it. An approve() still waiting for its proof when the template switches rejects with a TemplateChangedError; drop any proofToken you received before the switch and have the customer approve a new proof. A designer opened on a design to correct keeps its template.

A gallery of templates

A storefront that offers several templates can show each one with what the customer has entered, so they see their own name and photo in every layout before they pick one. renderTemplate() draws a template as a PNG, in the designer’s own render worker, so a gallery of many does not hold up the page:

const ids = ['party-sign@3', 'party-sign-stars@1', 'cap-classic@2'];

async function drawGallery() {
  const { values } = designer.getState();
  for (const id of ids) {
    const png = await designer.renderTemplate(id, { maxEdgePx: 160, values });
    thumbnail(id).src = URL.createObjectURL(png);
  }
}

// Draw again once the customer's edits settle, not on every keystroke.
let timer;
designer.on('change', () => {
  clearTimeout(timer);
  timer = setTimeout(drawGallery, 400);
});
drawGallery();

gallery.addEventListener('click', (event) => {
  const id = event.target.closest('[data-template]')?.dataset.template;
  if (id) designer.setTemplate(id);
});

Without values, the template is drawn with its own sample text and pictures. With the values of getState(), what the customer entered in a setting with a field key is carried into the template as setTemplate() carries it; a value the template does not allow is left out of the picture, and the template’s own drawn in its place. Name a viewId (and a variant) to draw the template on that view’s photo, as renderView() draws the design shown. A template is drawn for the product colour of the variant named, else the one shown: on a dark colour, with its on-dark values.

The designer keeps each picture it drew, by template, size, view, the colour’s tone and values, so asking again for one it has resolves at once. You decide when to ask: a gallery that redraws on every keystroke draws every template for every letter. A picture that cannot be drawn rejects with a TemplateRenderError.

Read the gallery’s names and previews with the client’s templates.list({ ids }).