A Polotno design can now be a template. Name the parts that change, then fill them from your data to make one copy per record. Designs can also carry links that stay clickable in the exported file. This release adds template variables, a panel to build templates in the editor, images that keep a good crop when they change, and links.
Fill one template with your data
Make a certificate, a badge or a postcard for each row of your data, from one design. A template variable is a named field in that design. Write {{name}} in any text, plain or rich, and the value takes the style of the token. With bindings, a variable can also set the source of an image or video, a color, or whether an element shows.
The design stores the current value of each variable. The canvas and every export draw that value, so the file you render matches what the designer sees. To make one copy per record, fill the template with resolveVariables from @polotno/schema. It returns a plain design with the values in place, and the issues it found in the record:
import { resolveVariables } from '@polotno/schema/variables';
text.set({ text: 'Dear {{first_name}},' });
photo.set({ bindings: { src: 'photo' } });
const { design, issues } = resolveVariables(store.toJSON(), {
first_name: 'Ada',
photo: 'https://example.com/ada.jpg',
});It works the same in the browser and in Node. Load the result into the editor to personalize a design when it opens, or render a batch on your server with polotno-node or any exporter. The Cloud Render API takes the template and one record in the job, and fills it the same way; with strict: true, a job that fails lists the issues in its error. A text whose value is missing and has no default keeps its {{token}}, so a broken copy looks broken. getVariables lists the fields of a template with their types, so you can build a form or a CSV header from the template itself.
Read the template variables docs.
Build templates in the editor
Template authors can build a template and try it with sample values in the editor, without code. The Variables side panel section lists every variable with its value. Change a value and the canvas redraws. Authors also edit the label, default and required flag of each variable, bind the selected element to a variable, and choose how a bound image fits its frame. Each row shows its warnings.
The section is opt-in, so your end users see it only where you add it:
import { SidePanel, DEFAULT_SECTIONS, VariablesSection } from 'polotno/side-panel';
<SidePanel store={store} sections={[...DEFAULT_SECTIONS, VariablesSection]} />;Once a design defines a variable, the tooltip of a selected text shows an insert button. The button lists the text variables with their values, creates a new one, and puts the token at the caret. Your code writes the variables with store.setVariables(), which is undoable.
Read about the Variables panel.
Images that keep a good crop
A photo that replaces a sample rarely has the shape of the sample. With fit: 'cover', a new image of any shape fills its frame without stretching. focus picks the part that stays in view, for example the faces near the top of a portrait:
image.set({ fit: 'cover', focus: { x: 0.5, y: 0.3 } });fit: 'contain' shows the whole image inside the frame instead. Fit works on images, GIFs, videos and Lottie, for a source from your data and for a photo a user uploads into the frame. Every renderer computes the crop when it draws, so the crop is the same on the canvas and in each export.
Clickable links in your exports
Exported files can now take the reader somewhere: a button opens your shop, two words start an email, a contents page jumps to another page. Give any element or group an href from code, or wrap words in <a href> in rich text:
button.set({ href: 'https://example.com/shop' });
text.set({ text: '<p>Questions? <a href="mailto:hello@example.com">Email us</a>.</p>' });A link opens a web page, starts an email or a call, or jumps to another page of the design. SVG, HTML, PDF, PPTX and email export keep links clickable. An SVG or an email holds one page, so pageUrls sends a page jump to the address where you publish that page. A link in rich text can hold a template variable, so each copy in a batch links to its own address. The PDF, SVG, PPTX, IDML and PSD importers bring the links of a file in, on the text and objects they cover.
Upgrade
npm install polotno@4.22.1 @polotno/schemaReact 18 projects use polotno@3.22.1. @polotno/schema 0.14.0 holds resolveVariables and getVariables.
Update the other Polotno packages you use to this release:
- The exporters draw template variables, fit and focus as the editor does, and SVG, HTML, PDF, PPTX and email export add links:
@polotno/svg-export0.14.0,@polotno/html-export0.13.0,@polotno/pdf-export0.18.0,@polotno/pptx-export0.14.0,@polotno/image-export0.3.0,@polotno/email-export0.2.0 and@polotno/video-export0.7.0. - The importers read links:
@polotno/pdf-import0.14.0,@polotno/svg-import0.3.0,@polotno/pptx-import0.2.0,@polotno/idml-import0.2.0 and@polotno/psd-import0.4.0. - polotno-node 3.19.1 renders with polotno 4.22.1.
One change can stop an export that worked before. @polotno/pdf-export draws a filtered SVG and blurred text as process-color images, which cannot carry a spot ink. When such an element uses an ink mapped in spotColors, the export now fails with EXPORT_FAILED (details.reason: 'spot-ink-rasterized') instead of printing without the ink. To keep a blur and a cut line, put the blur on process-color artwork and the cut line on a separate, unfiltered path. Spot color docs.
Everything else in this release is in the changelog.
