ZAFLO Merge

1 · Getting started

What the panel is for, what it needs, and how to open it.

ZAFLO Merge does the job of InDesign's own Data Merge, but it does not stop when the merged document is made. The values you place keep a link back to the row they came from, so the panel can tell you at any moment which price is out of date, which text somebody has retyped by hand in InDesign, and which article has fallen out of the spreadsheet altogether.

You work with two things: a data file (the spreadsheet) and a template (your InDesign document with the places to fill marked in it). The panel sits between them.

What you need

Installing

1. Double-click the .ccx file you were given. Creative Cloud installs the panel.
2. Restart InDesign if it was running.
3. Open the panel: menu Window › Extensions › ZAFLO Merge.

Dock it where you like. The panel is happiest wide — it is a spreadsheet, and the more columns you can see, the less you scroll.

2 · The panel

One trip around the window. Everything here comes back later in detail.

1. Data source — which spreadsheet the grid is showing. A document can hold several.
2. Six buttons — add a source, remove it, check for changes now, Field Mapping, Settings, and ⋯ which holds everything else.
3. Search and filter — type to find a row; the dropdown narrows the list to placed, changed, edited or missing rows. The red dot means something is out of sync.
4. Preview — fills the template with one record so you can look at it. The arrows step through the records.
5. Merge… — builds the merged document.
6. Column headings — click to sort, drag the edge to resize, double-click to write that placeholder into the document. The number in brackets is how many values of that column are placed.
7. The cells — the spreadsheet itself, in colour. Right-click any cell for the menu of things you can do with it.
8. The line under the grid — what the selected cell holds, what is in the document, and what state it is in, in plain words.
9. The buttons — Place, insert a placeholder, Fill on click, Update, Update All, Go to.
10. Status line — how many rows and placed fields, how many are out of sync, when the file was last checked and last saved.

3 · Your first price tag

Ten minutes, from a spreadsheet to a merged document. Do this once and the rest of the manual will read itself.

What you will build

A price tag: code, name, price, and a photo. Five records, five tags on a page.

Step 1 — the spreadsheet

Make an XLSX with a header row and one row per article:

Code will be the key — the column whose values never repeat. That is what ties a value in the document to a row in the file, so it has to be unique.

Step 2 — import it

1. Open your InDesign document.
2. In the panel press + (or ⋯ › Import Data Source…).
3. Pick the file. The dialog shows you the sheet, the first rows and the columns.
4. Set Key column to Code.
5. Press Import. The grid fills with your rows.

Step 3 — mark the template

Draw a text frame and type the placeholders into it, one per line. You can type them by hand, or put the text cursor where you want one and double-click the column heading in the panel:

<<Code>>
<<Name>>
<<Price>>

For the photo, draw an empty picture frame, select it, click the Photo column in the panel and press << >>. The frame now shows <<@Photo>> so you can see it is ready.

Step 4 — try one record

Tick Preview. The template fills with the first record; the arrows step through the others. Untick it and the placeholders come back. Nothing is linked yet — this is only a look.

Step 5 — build the merged document

1. Press Merge…
2. Records to merge: All records.
3. Records per page: Multiple records per page. Leave Columns and Rows at 0 and the panel fits as many as the page takes; the picture on the right shows you the result before anything is made.
4. Save as: choose a file name.
5. Create. The merged document opens with every record in its slot.

4 · Importing data

What the import asks for, why it sometimes refuses, and how to make a messy spreadsheet usable in one click.

The two conditions

Only two things are required of a data file, and the import will not go on without them:

The import dialog

When the import refuses

It never just says "error". The dialog lists every problem in plain words, with the Excel line numbers, and offers the fixes as buttons:

If every row would be skipped, the import stops and says so, rather than leaving you with an empty grid.

Texts that mean "empty"

Exports often write (blank) or (prázdné) into a cell that should be empty. Those count as empty. The list is in the import dialog and can be extended.

Several data sources in one document

Press + again to add another file — a leaflet can have one source for the front page and another for the inside. The dropdown at the top switches between them, and each keeps its own mapping and formats. – removes a source from the document, and its links with it.

Re-importing and checking

• ↻ reads the file again right now.
• The panel also checks on its own every ten seconds (adjustable in Settings). A changed file is recognised by its contents, not only by its time stamp, because InDesign's file access can report the time late.
• ⋯ › Re-import Data Source… opens the import dialog again, for when the structure of the file has changed and not just the values.

5 · Marking the template

Four ways to say "this is where the price goes". Use whichever suits the job; they can be mixed in one document.

1 · Placeholders in the text

Type <<Price>> where the value belongs. This is the way Data Merge works and the way Create Merged Document expects, so it is the safest choice for a template that will be merged.

Three ways to get one into the document without typing:

• Put the text cursor where it goes, click the column in the grid, press << >>.
• Double-click the column heading — the placeholder lands at the cursor.
• ⋯ › Insert Placeholders for All Columns writes them all at once, one per line, to build a template quickly.

The name between the angle brackets is the placeholder name of the column, which you can change in Field Mapping — handy when the spreadsheet column is called ArtNr_2024_final and you want <<Code>> in the document.

2 · The plain column name

A frame that simply contains the word Price also counts, as long as a column of that name exists. Useful for templates somebody else built without any placeholders. Matching ignores case, spaces and underscores, so art nr finds the column Art_Nr.

3 · A frame named after the column

Name the frame in the Layers panel after the column. The text inside is then irrelevant — the whole frame is filled. Good for tidy templates where every frame has a name anyway.

4 · A whole frame marked with << >>

Select a frame, click the column in the grid, press << >>. The frame is marked as that column's placeholder and shows <<@Photo>> (with the at sign) for a picture or a QR code, or <<Name>> for a text frame that holds one value. The frame is renamed in the Layers panel too, so you can see what is prepared.

An empty picture frame is turned into a text frame for as long as it is only a placeholder, so the mark is visible on the page. It becomes a picture frame again the moment a picture goes in, keeping its size and its fitting options.

6 · Placing values

Five ways to get data into the document, from one cell to a whole page of price tags.

One value at the text cursor

1. Click in the text where the value should go.
2. Click the cell in the grid.
3. Press Place.

The text is written and linked, and the cell turns green.

A whole record into a frame

1. Select the frame, several frames, or a group.
2. Click any cell of the row you want.
3. Press Place.

Every placeholder inside is filled from that row, and all four ways of marking are searched. The panel then says how many frames have text that no longer fits.

A picture or a QR code

Select the frame, click a cell of an image or QR column, press Place. A frame you marked as a placeholder is turned into a picture frame automatically; it does not have to be a picture frame already.

Several slots at once

A page of price tags, filled in one go:

1. Select all the slots — frames or groups, in any order.
2. Click the row you want to start from.
3. ⋯ › Fill Selected Frames From This Row…

The slots are filled with consecutive rows in reading order: page by page, top to bottom, left to right. The panel says how many slots and how many rows it is about to use and waits for your yes. Nothing has to be named or prepared.

Fill on click

Switch Fill on click on, pick a row, and every frame you then click in the document is filled from that row. Good for a leaflet whose layout is already drawn and you are walking through it with a list in your hand. The button stays lit while it is on.

7 · Colours and states

The grid is a report. Five colours and you know where you stand.

• Green — in sync. The document holds exactly what the file says.
• Red — changed in the data file. Somebody edited the spreadsheet; the document is behind.
• Orange — edited in InDesign. The text in the document no longer matches what was placed. Usually a manual correction on the page.
• Purple — the row is gone. It is placed in the document but no longer in the file.
• Grey — not placed. The value is in the file but nowhere in the document.
• Yellow edge — locked. Update leaves this field alone.

Rows that are placed but missing from the file are listed first, not buried at the end, because they are the ones that will embarrass you in print.

Reading one cell

Click a cell and the line under the grid spells it out: the column and the key, what the file says, what the document holds, and the state in words. When a value is placed in several spots, it says how many.

Finding what matters

8 · Keeping it in sync

Update, locks, unlinking, and what to do when a key changes.

Update and Update All

• Update rewrites the selected cells from the data file.
• Update All rewrites everything that is out of sync, as a single undo step. It asks first, unless you turn that off in Settings.

Both keep the character style of the field, and both leave locked fields alone.

Locking a field

Right-click a cell › Lock (never update this). The cell gets a yellow edge and neither Update nor Update All touches it. Use it for the one price the client wants worded differently, so an automatic update cannot undo the correction. Unlock it the same way.

Unlinking

Right-click a cell › Unlink (keep the text) removes the link but leaves the text in the document. Unlink the whole row does it for every field of that record. Use it when a page is finished and should stop following the data.

When the key changes in the file

If an article number changes, the old row disappears (purple) and a new one appears. The panel notices when the new row carries the same values as the lost one and offers Relink: the fields in the document are moved over to the new key, and everything stays in place.

How often it looks

Every ten seconds by default; the interval is in Settings and automatic checking can be switched off entirely. ↻ checks right now. Excel only writes to disk when the file is saved, so the panel cannot see a change until your colleague presses save — the status line shows when the file was last saved, so you can tell whether you are looking at fresh data.

9 · Field Mapping

One row per column of your spreadsheet. This is where you say what each column is and how it should look.

Open it with the Map button, or ⋯ › Field Mapping…

Under the table

10 · Formats

The spreadsheet says 1299.9. The leaflet says 1 299,90 Kč. A format profile is the difference.

Setting the format of a column

Right-click any cell of the column › Format of the column… A list of profiles appears with a live preview of that very value before and after. Pick one, press OK, and every value of the column follows it — in the grid, when placing, and in the merged document.

The same right-click menu switches a column between text and image paths, so a spreadsheet you have never seen before can be set up entirely from the grid.

What a profile can do

Two discount profiles are ready made: 49 % with a space and 49% without. New profiles are made in Settings › Formats, where a test value at the top shows what each one does.

11 · Pictures

The spreadsheet holds a code; the panel finds the file.

How a picture is looked for

The order is fixed, and the first file that exists wins:

1. The pattern of the column ({Code}, photo_{value}, even {Code}_{Colour}) in every folder, in the order the folders are listed, trying each extension in turn.
2. The same with the plain value of the cell.
3. If the name already has an extension (coffee.png), no extensions are added.
4. A full path in the cell (D:\photos\coffee.tif) is used as it stands.

An example

Folders F:\photo\main and F:\photo\backup, extensions jpg, png, tif, pattern {Code}, and the row has Code 1001. The panel tries:

F:\photo\main\1001.jpg
F:\photo\main\1001.png
F:\photo\main\1001.tif
F:\photo\backup\1001.jpg
...

The conditions

What happens when a picture is missing

The frame is left empty and the record is named in the report of the merge (Images not found: 2 (e.g. 1004 · Photo)). A merged record never keeps the picture that happened to be in the template. In the document you are working on, Settings decides whether a missing picture empties the frame or leaves what is there.

Fitting

Settings › Images sets how a picture sits in its frame — fit proportionally, fill the frame, fit the frame to the picture, or nothing — and whether it is centred. A frame marked as a placeholder keeps its own fitting options when it becomes a picture frame again.

12 · QR codes

The panel draws the code itself, as vectors, in an ink from your document. No generator, no website, no RGB.

A QR column behaves exactly like a picture column — you mark a frame, and Place, Preview and Create Merged Document fill it — except that the picture does not have to exist. It is made from the value in the cell.

Setting one up

1. Map › set the column's Type to QR code.
2. Click the colour next to it. The swatches of the document are listed with the colour itself, its ink values and a mark for a spot ink. After you choose, the row shows that colour.
3. Press Content… and say what the code should hold (below).
4. In the document, select the frame, click the column in the grid, press << >>.

Why it is a PDF, and why that matters

Each code is written as a small vector PDF into a folder called _zaflo_qr beside the data file, and that PDF is placed into the frame. This is deliberate:

• CMYK, not RGB. An SVG could only be RGB, which has no business in a print job.
• A spot ink stays a spot ink. Choose a Pantone swatch and the PDF carries a real separation; InDesign adds that ink to the document, and it separates on the plate as one colour.
• Vectors. Sharp at any size, no resolution to worry about.
• Made once. The file name is built from the text and the colour, so the same code in a thousand records is drawn once and placed a thousand times.

What the code can hold

Content… offers the same kinds InDesign's own QR generator does. Leave a field empty and the value of the cell is used.

Combining columns — {Column}

This is what makes it useful. Any field of the content may take a value from another column of the same row, written in braces:

Worked examples

How big the frame has to be

The more text, the more modules, and the more modules the smaller each one is in the same frame. The dialog tells you the size as you type (37 × 37 modules). As a rule of thumb for print at a normal reading distance:

Shorten the link if the frame is small — a redirect is better than an unreadable code. Every code is drawn with the quiet zone the standard asks for (four modules of empty space all round), so do not crop the frame tightly or put a rule against it.

Where the files go

Folder _zaflo_qr beside the data file, one PDF per unique text and colour, named after both. Delete the folder whenever you like — the codes are made again when they are needed. Keep it with the job when you hand the document over, the same as any other linked file, or package the document and InDesign collects them for you.

13 · Fields on condition

The discount flash only where there is a discount.

Any frame can be given a condition. When a record does not meet it, the frame is taken out of the merged document — and hidden in the preview, so the template itself stays whole.

Setting one

1. Select the frame (or several) in the document.
2. Right-click the cell of the column that should decide, and choose Show the selected frames only when … — that column is already filled in. (The same thing is in ⋯ › Show Only When…)
3. Pick the test and press OK.

The dialog says straight away how the first row would come out — the frame stays or the frame goes away. Always show takes the condition off again.

Examples

• A "NEW" flash: Note is new.
• A percentage badge only on discounted items: Discount is not empty.
• A "big pack" ribbon: Weight is more than 900.
• A second photo only where there is one: Photo2 is not empty.

The condition sits on the frame itself, so it travels with a copy of the frame and is evaluated again for every record in the merge. Conditions are listed in ⋯ › Check the Template…

14 · Styles for the placeholders

A template thrown together in ten minutes has everything in the basic style. One command fixes that.

⋯ › Styles for the Placeholders… walks the document and:

• gives every paragraph holding a <<Placeholder>> a paragraph style named after that placeholder,
• gives every marked frame an object style with the same name.

So three placeholders — <<Code>>, <<Name>>, <<Price>> — leave you with styles Code, Name and Price already applied. Set the price once in the Paragraph Styles panel and every price in every record follows, because the merged document keeps the styles.

Which kind of style you get

It depends on what is really in the text. A price tag is usually one paragraph with line breaks in it (Shift+Enter), not three paragraphs — and one paragraph can only carry one paragraph style.

If you would rather have paragraph styles everywhere, build the tag with real paragraph returns instead of line breaks and set the spacing with Space Before in the style.

It works on a filled document too

In a template the styles are named after the placeholders. In a document that is already filled — a merged document, or a page you placed by hand — there are no placeholders left, so the styles are named after the column each value came from. Either way you end up with a style per field, and the command can be run on a merged document after the fact.

One paragraph gets one style. If two values share a paragraph (<<Price>> per <<Unit>>), the style is named after the last one found there.

What it will not touch

Only places that still carry a basic style are changed — [Basic Paragraph], [Basic Text Frame], [None] and their equivalents in a localised InDesign, which are the ones in square brackets. Anything you have already styled yourself is left exactly as it is, and the report says how many it left alone.

A style with the right name that already exists is used, not duplicated. So you can build your styles first, name them after the placeholders, and this command will simply apply them.

Nothing looks different afterwards

A style is only a name for what is already there. When the panel makes a new style it fills it with the look of the very text or frame it was made for, and applies it without clearing the local formatting. A new object style is made with all its categories switched off, because a plain new object style in InDesign carries a black hairline and would draw a frame around every picture it touched.

A style that already exists is used as it is and never rewritten — so you can set your styles up first, name them after the columns, and the panel will simply apply them.

Doing it automatically

Settings › Styles › Give every placeholder a style of its own. With it on, a style is made and applied the moment a placeholder is created. The Name in front of the styles box adds a prefix — put ZAFLO  there and you get ZAFLO Price instead of Price, so the panel's styles never sit among yours. Create Merged Document does the same as it builds the merged document, so what comes out is already styled.

15 · Preview

Look at a record in the real template before anything is made.

Tick Preview and the template fills with the current record: placeholders, plain column names, marked frames, pictures and QR codes. The arrows step through the records, and the counter shows where you are. Untick it and the template comes back exactly as it was.

• Nothing is linked and nothing is saved — the preview is only a look.
• Frames that already hold real data are left alone, so a page that is half finished is not disturbed.
• Frames with a condition are hidden for the records they do not belong to, and shown again when the preview goes off.
• The panel remembers exactly what it replaced, including pictures, and puts it all back. If anything cannot be put back it says so rather than guessing.

16 · Create merged documents

The whole run: one record per page, or a grid of them, with a picture of the page before anything happens.

Which records

One record per page

Everything on the template spreads is repeated for every record. A two-page template makes two pages per record. Nothing else to set.

Several records per page

Everything on the first page is treated as one block and repeated in a grid.

The rest of the dialog

The report at the end

When it is done the panel says how many records went in, how many documents and PDFs were written, how many records fit on a page, which placeholder names matched no column, which pictures were not found and which snippets were missing. Read it — it is the difference between noticing a problem now and noticing it in print.

17 · A layout per record

One big tag, three small ones, a landscape one — all in the same run.

A record can bring its own layout. You build each variant once, save it as an InDesign snippet, and a column of the spreadsheet says which one each record uses.

Setting it up

1. Build one variant in InDesign with its placeholders in it.
2. Select it and choose File › Export › InDesign Snippet. Name the file after the value you will write in the spreadsheet: big.idms, small.idms.
3. Add a column to the spreadsheet — say Layout — holding big or small for each record.
4. Map › Different layout per record: set Column deciding the layout to Layout and Folder with the snippets to the folder with the .idms files.
5. Merge as usual, with Multiple records per page.

What the panel does

• Each record is given the snippet its cell names, placed into its slot and filled from that row — placeholders, pictures, QR codes and conditions all work inside a snippet.
• Every layout in play is measured first, and the grid slot is made as big as the biggest of them, so a big record cannot reach into its neighbour.
• A record whose cell is empty uses Snippet for an empty cell, or the template on the first page when that is not set.
• If no record uses the template, it is taken off the page rather than left lying under the records.
• A snippet that cannot be found is named in the report.

With no layout column set, everything works exactly as before — one template for every record.

18 · Overviews and checks

Four lists that answer the questions you actually have.

19 · Settings

Everything in the ⚙ button, in order.

20 · What is stored in the file

For the curious, and for anyone testing the panel or writing a script beside it.

Everything is inside the .indd. No side-car file, no database. Open the document somewhere else and the links are still there.

zaflo.sources.v1

The data sources: path, sheet, key columns, the mapping of every column, formats, image rules, QR settings, snippet settings.

zaflo.links.v1

The link table: for every placed value a short id and behind it the source, the key of the row, the column and the value as it was written, plus the lock. Entries like item:247 tie a frame to its id, which is how a copied frame is recognised.

zaflo.preview

What the preview replaced, so the template can be put back exactly.

zaflo.log

The last forty things the panel did, with the time.

zaflo.field · zaflo.ph · zaflo.when

Labels on a frame: the id of the value placed in it, the column it is a placeholder of, and the condition under which it belongs to a record.

A placed piece of text keeps its id in the story itself. Four ways are tried, in this order, and the first the running InDesign accepts is used: a hyperlink text source named ZAFLO:<id>, an XML element, a note, or a label on the frame. The fallback chain exists because notes and XML attributes cannot be written from every build.

Reading it from a script

var d = app.activeDocument;
$.writeln(d.extractLabel("zaflo.log"));
$.writeln(d.extractLabel("zaflo.links.v1"));
$.writeln(d.extractLabel("zaflo.sources.v1"));

ExtendScript inside doScript has no JSON, so use eval("(" + label + ")") if you want to walk the table.

What the state of a cell is made of

Three things are compared: the value in the data file now, the value stored in the link table when it was written, and the text actually in the document. Same everywhere → green. File differs → red. Document differs → orange. Row gone from the file → purple.

21 · When something goes wrong

Symptom, cause, cure.

22 · Words used here

If you have never done a data merge before, these are the only terms you need.