Repeating Sections

A repeating section produces one copy of a block — a table row, a slide, or a group of paragraphs — for each item in a collection. The section is enclosed in opening and closing tags that name the collection:

{{#items}} ... {{/items}}

The name inside the tags — items, placements, campaigns — is the machine name of a collection field (a nested entity or link-to-many) on the entity type the template is attached to.

Inside the section, placeholders resolve against the current item — they use the machine names defined on the nested entity type. Outside, they resolve against the top-level record.

The exact mechanics differ by template format.

DOCX — table rows

DOCX templates support two patterns for repeating table rows.

Three-row pattern

This is the clearest approach. The table contains three rows for the repeating section:

  1. A row with only {{#items}} in the first cell (opening tag row).

  2. The template row, containing the placeholders for each item.

  3. A row with only {{/items}} in the first cell (closing tag row).

During generation, the opening and closing rows are removed. The template row is duplicated once for each item in the collection, with placeholders filled from that item’s data.

Example — proposal line items:

Suppose the template is attached to a Proposal entity type that has a nested-entity field items (machine name). Each nested item has its own fields — displayName, period, frequency, price — defined on the nested entity type (see nested entities). Those nested machine names are the placeholders used inside the section:

Template table

{{#items}}

{{displayName}}

{{period}}

{{frequency}}

{{price}}

{{/items}}
Generated table

Tverskaya 12

March

Daily

45 000

Nevsky 5

March

Daily

38 000

Arbat 3

March

Weekly

12 000

If the proposal has three line items, the output table has three data rows (the tag rows are gone).

Single-row pattern

When a three-row layout is impractical, the opening and closing tags can be placed in the first and last cells of a single template row:

Template table

{{#items}} {{displayName}}

{{period}}

{{frequency}}

{{price}} {{/items}}

The opening tag must be in the first cell. The closing tag must be in the last cell. The row is duplicated for each item, with the tags removed from the output.

Which pattern to use

The three-row pattern is easier to read and maintain. Use the single-row pattern only when the template layout cannot accommodate extra rows — for example, in a tightly formatted invoice where every row must be a data row.

DOCX — multi-paragraph sections

Outside of tables, a repeating section spans a range of paragraphs. The opening tag is a paragraph by itself; the closing tag is a separate paragraph.

In this example the template is attached to a Campaign entity type whose nested-entity field placements (machine name) contains items with fields displayName, address, startDate, and endDate — all machine names defined on the nested entity type:

{{#placements}}

Display: {{displayName}}
Location: {{address}}
Period: {{startDate}} -- {{endDate}}

{{/placements}}

The paragraphs between the tags are cloned for each item. The tag paragraphs themselves are removed from the output.

This is useful for letter-style documents that list items as text blocks rather than table rows — for example, a campaign summary that describes each placement in a paragraph.

XLSX — row loops

In XLSX templates, a repeating section works at the row level within a sheet. The opening tag goes in a cell on one row; the closing tag goes in a cell on a subsequent row. The rows between them form the template block.

Using the same proposal example — items is the collection field’s machine name, and displayName, period, price are machine names on the nested entity type:

Template
A B C

5

{{#items}}

6

{{displayName}}

{{period}}

{{price}}

7

{{/items}}
Result
A B C

5

Tverskaya 12

March

45 000

6

Nevsky 5

March

38 000

7

Arbat 3

March

12 000

Rows 5 and 7 (the tag rows) are removed. Row 6 is duplicated for each item. Rows below the section shift down to accommodate the inserted rows.

Nested collections in XLSX

XLSX templates support nested repeating sections. A section inside another section produces a set of rows for each item in the inner collection, repeated for each item in the outer collection.

In this example, the entity type has a collection field campaigns (machine name), and each campaign has its own nested collection placements. campaignName is a field on the campaign; displayName, address, and price are fields on the placement — each name is the machine name defined on the respective entity type:

Template
A B C

3

{{#campaigns}}

4

Campaign: {{campaignName}}

5

{{#placements}}

6

{{displayName}}

{{address}}

{{price}}

7

{{/placements}}

8

{{/campaigns}}

The engine pre-calculates row shifts so that content below the outermost section lands in the correct position regardless of how many items the collections contain.

Formulas and row references

When rows are duplicated, Excel cell references in formulas are not automatically adjusted. If a formula references a cell by address (for example, =SUM(C2:C10)), the address remains as written in the template.

To calculate totals across a variable number of repeated rows, use an expression placeholder instead of an Excel formula, or place the formula outside the repeating section and reference a named range.

Cell styles and formulas are copied to each repeated row. For details on how formatting survives repetition and other XLSX-specific behavior, see Excel templates.

PPTX — slide loops

In PPTX templates, a repeating section works at the slide level. The opening and closing tags are placed on the same slide — typically in a text box or shape. That slide becomes the template slide.

During generation:

  1. The template slide is cloned once for each item in the collection.

  2. Placeholders on each cloned slide are filled from the corresponding item.

  3. The original template slide is removed.

If the collection is empty, the template slide is simply removed — no blank slide remains.

Example — a media kit with one slide per display:

Here the template is attached to a Media Kit entity type that has a collection field displays (machine name). Each display item has fields address, formatName, and impressionsPerDay — machine names on the nested entity type.

A template slide contains:

{{#displays}}
Location: {{address}}
Format: {{formatName}}
Audience: {{impressionsPerDay}} impressions/day
{{/displays}}

If the data contains five displays, the output deck has five slides, each filled with one display’s data.

Single-collection shortcut

When the data contains exactly one array and the template references a different collection name, the engine automatically maps the template’s name to the available array. This means a template written with {{#screens}} will work even if the data key is displays, as long as there is no ambiguity.

This automatic mapping only applies when there is exactly one array in the data. If multiple arrays are present, the collection name in the template must match the data key exactly.

Accessing outer fields inside a section

Inside a repeating section, placeholders resolve against the current item by default. To access fields from the enclosing record:

  • {{$.fieldName}} — reaches the root context (the top-level record), regardless of nesting depth.

  • {{../fieldName}} — reaches the parent context (one level up).

For example, to show the deal number alongside each line item in a proposal table:

Template row inside {{#items}}

{{$.dealNumber}}

{{displayName}}

{{price}}

Empty collections

When a collection is empty:

  • DOCX tables: the template rows (and tag rows) are removed. If the table has no other rows, the table itself remains as an empty table with headers only.

  • DOCX paragraphs: the tag paragraphs and all content paragraphs between them are removed.

  • XLSX: the tag rows and template rows are removed. Rows below shift up.

  • PPTX: the template slide is removed.

No error is raised for an empty collection.

Related pages