What is a repeat block?
A repeat block is a rectangle on your template that is split into a grid of equal slots. You design one slot, and Mergram fills every slot with the next row of data. Combined with grouping, it produces one PDF per group of rows instead of one PDF per row.
Use it for:
- Price lists and line sheets — one PDF per buyer, one product per slot
- Invoices with real line items — one PDF per invoice number, one line per slot
- Order summaries, statements, and packing lists — any document that lists several rows
How to add a repeat block
- Open your template in the editor and go to the page that should hold the list.
- Open the Repeat Block tab in the left sidebar and click Add repeat block. A dashed block appears in the middle of the page. Each template can have one repeat block.
- Move and resize the block so it covers the area of the list. Dragging the block also moves the fields inside it.
- Set the grid in the block toolbar: Cols and Rows on the toolbar, and gaps, fill order, height, and continuation page under More settings (the sliders icon). The readout shows how many items fit on a page.
- Drag data fields into the first slot (top-left). A field whose centre sits inside the first slot joins the block and shows a Repeat block badge. Faded copies preview the other slots.
- In the Repeat Block tab, open One PDF per and choose the column that groups rows into documents. The footer at the bottom of the tab shows how many PDFs you’ll get and what they cost.
- Click Preview to render the first group, then Mail merge… to merge every group.
The Repeat Block tab lists four numbered steps: Block, One PDF per, Fields, and Totals (optional). A closed step shows its current value, and a check once it’s done. The first step that still needs work opens by itself.
Design one slot
Lay out a single row — product name, price, image — inside the first slot. Every other slot copies that layout at its own position.
Grid settings
| Setting | What it does |
|---|---|
| Cols / Rows | Number of slots across and down (1–50 each). Items per page = cols × rows. |
| Gap X / Gap Y | Space between slots, in canvas units. |
| Fill | Across, then down fills a row of slots before moving down. Down, then across fills a column first. |
| Height | Same for every row (default) or Grow to fit text. Growing needs a single column. |
| Continue on | Same page (default) or another page of the template for the rows that don’t fit. |
Slots are the block size minus the gaps, divided evenly. The grid settings are on the block’s toolbar: select the block, then open More settings for height, continuation page, gaps, and fill order.
Rows that grow to fit
With Height: Grow to fit text, a row whose text wraps onto more lines gets taller and pushes the next rows down, like a table. The slot height becomes the smallest row height, and the space you leave around fields in the first slot is kept.
- A page holds as many rows as fit in the block, so the toolbar shows “up to” that many per page.
- A row is never split across pages: if it doesn’t fit, it starts the next page.
- A row taller than the whole block gets a page to itself and is cut off at the block’s bottom edge, ending with ”…”.
Tip
Rows that grow don’t line up with row lines printed on the template PDF. Draw only the table header and outer frame, and leave the row lines out.
Continuing on a different page
By default, rows that don’t fit go on copies of the block’s page. If page 1 has a letterhead and address above a short table, and you want the next pages to be all table, add a continuation page to your template PDF, for example page 2 with just the table header:
- Select the repeat block, open More settings, and set Continue on to Page 2. A dotted rectangle appears on page 2, at the block’s position.
- Go to page 2 and move the rectangle, or drag its top or bottom edge to make it taller. Its width always matches the block, and faded outlines show how many rows fit.
- Fields on page 2 around the rectangle, like “Page X of Y”, appear on every continuation copy. Show on works there too: a total set to Last page prints once, on the final copy.
The continuation page appears only when rows overflow, and never in its normal place in the document. Set Continue on back to Same page to remove it.
Info
The block’s page and the continuation page each hold their own fields. A total set to Last page on the block’s page doesn’t appear when the document ends on a continuation page, so put the total on both pages.
Grouping rows into documents
The One PDF per step of the Repeat Block tab controls how rows become documents. It appears once the template has a repeat block and a data source. Match mode and blank handling are under More options; they open by themselves when you’ve changed them or when some rows have a blank value.
| Option | Behavior |
|---|---|
| Column | Rows with the same value in this column go into the same PDF. Values are trimmed and case-sensitive (Acme and acme are different groups). |
| None: all rows in one document | Every row goes into a single PDF. |
| Same value anywhere | Rows with the same value form one group wherever they appear in the sheet. Groups follow the order of first appearance; rows keep sheet order. |
| Consecutive rows only | A new group starts every time the value changes, so A, A, B, A produces three documents. |
| Blanks: own document | All rows with a blank value go into one “(blank)” document. A warning shows how many rows this affects. |
| Blanks: join previous row | A blank row joins the group of the row above it — handy when only the first line of each invoice has the invoice number. |
The footer of the tab shows the result, for example 37 PDFs and 37 credits, and warns if you don’t have enough credits. The grouping is saved with the template.
How pages are built
For each group, Mergram builds one PDF:
- Pages before the block page appear once.
- The block page repeats as many times as needed to fit the group’s rows (at least once, even for an empty group). With Continue on set, the copies after the first use the continuation page instead.
- Pages after the block page appear once.
Fields outside the block use the group’s first row. On the block page you can limit them with Show on:
| Show on | Appears on |
|---|---|
| All pages | Every copy of the block page (default) |
| First page | Only the first copy |
| Last page | Only the last copy |
Totals and page numbers
Totals are calculated over every row of the group, not per page:
- In the Repeat Block tab, under Totals, choose a column.
- Drag Sum, Average, Min, or Max onto the page, outside the block. Row count needs no column.
- A total placed on the block’s page prints once, on the last page. To print it on every page instead, select it, open More settings, and change Show on.
Numbers like $1,234.50, 1.234,50 €, and (12.00) are read as amounts. Number format sets how totals are written (for example 1,234.50 or 1.234,50), and the field’s More settings adds text before or after and the number of decimals. Cells that aren’t numbers are skipped, and the Totals section warns how many there are.
Page number and Page count are in the Single Block tab under Text & page numbers. They count the pages of each output PDF, so you can write “Page 2 of 3” with a fixed text field between them.
Fixed text
Words printed on the template PDF appear on every copy of the block page. For a label that should appear on one copy only, like “Total due” on the last page, leave it off the PDF and add it as fixed text instead:
- In the Single Block tab, drag the Text chip (under Text & page numbers) onto the page.
- Type the words in the text box at the start of the field toolbar, then press
Enter. - Style it like any text field, then open the field’s More settings and set Show on, or add a condition, such as showing “PAID” only when a Status column equals
Paid.
Fixed text shows its own words on the canvas with a grey background. Data fields show their column name with a blue background.
Conditional visibility on fields inside the block is checked per row, so each slot can show or hide fields based on its own data.
Form fields
Fillable PDF form fields are filled from the group’s first row and then flattened. Grouped output is never fillable.
Merging and billing
- Each group becomes one output PDF, and each PDF costs one credit.
- Choose Multiple PDFs for one file per group, or Single PDF to combine every group into one file.
- Filename and password templates use the group’s first row, for example
Price_List_[[Customer]]. - Retrying a job skips groups that already finished, so completed documents are never charged twice.
Sending by email
The Send Emails tab sends one email per group:
- The email goes to the address in the group’s first row, with the group’s PDF attached. If rows of a group have different addresses, a warning tells you how many groups this affects.
- Subject, body, and attachment name use the group’s first row, plus group totals. Under each of them, Insert group total adds one: pick Row count, or Sum, Average, Min, or Max of a column that holds numbers, then click Insert. This adds a placeholder such as
[[count]]or[[sum:Amount]]. If your sheet has a column namedcount,[[count]]uses that column. - A placeholder that doesn’t match a column or group total, such as a typo, shows a warning, and you can’t send until you fix it.
- Each email costs one credit.
The public API works the same way: when you merge with a template that has a repeat block, the inline data is grouped by the saved column (matched by header name), and credits are checked per group.
Tips
- Sort your sheet by the grouping column if you use Consecutive rows only.
- With the same height for every row, size slots for your longest value: text is not clipped or shrunk, so long values can spill into the next slot. For a one-column table, Grow to fit text avoids this.
- Keep totals and page-level details in fields outside the block, and set totals to Last page.
- Preview renders the first group only. Pick a grouping column with a large group to check overflow pages.
Limitations
- One repeat block per template.
- Only single-column blocks can grow rows to fit text; grids always use the same height.
- Totals cover the whole group; there are no per-page subtotals.
- A grouped email goes to one address, taken from the group’s first row.
- Grouping uses one sheet; joining two sheets is not supported.
- A single output document is capped at 500 pages.