Supplementary Annex

Overview

The Supplementary Annex (supplementary_Annex) is a section type that appends a self-contained supporting-documentation block to a Structured Content document. For every line item that carries notes or images, it produces:

1. A themed header bar - item number, description, and an optional document reference subtitle
2. Installation / QC notes - one plain paragraph per note string
3. A responsive image grid - downsampled to a configurable DPI for efficient PDF file sizes

The feature is controlled by a single payload flag (features.supplementaryAnnex: true) so the same template can render with or without the annex depending on the context.

Quick Start

1 - Add the node to your template .vpdf

{
  "id": "supplementary-annex",
  "type": "structured_content",
  "props": {
    "assetPath": "Documents/SupplementaryAnnex/supplementary-annex-layout.yaml",
    "library": "assets"
  },
  "pagination": { "breakBefore": "always" }
}

2 - Upload the layout YAML to SharePoint

Store the file at the path you referenced in assetPath inside your assets library.
See the full layout reference YAML below.

3 - Add the feature flag to your payload

{
  "features": {
    "supplementaryAnnex": true
  },
  "Lines": [ "..." ]
}

When features.supplementaryAnnex is false or absent, the annex section is silently omitted - no placeholder is rendered, the page break is suppressed, and the TOC entry is not added.

Layout YAML Reference

The layout YAML is a StructuredDocument asset with documentType: supplementary-annex. It contains exactly one supplementary_Annex section.

Document-level fields

supplementary_Annex block

sections:
  - type: supplementary_Annex
    data_source:  "{{Lines}}"
    notes_field:  notes
    images_field: images
    id_field:     "No."
    name_field:   Description
    showDivider:  false
    includeInToc: true
    sectionNumbering: true
    item_template:
      - type: sub_header
        text: "Item {{item.id}} - {{item.name}}"
        subtitle: "Document {{Header.No.}} | Date {{Header.Order Date|date}}"
        style: variant_blue_bar
      - type: repeat_notes
        source: "{{item.notes}}"
        style: paragraph_block
      - type: image_grid
        source: "{{item.images}}"
        columns: 2
        target_dpi: 150
        image_quality: 80
        show_captions: true
        caption: "Documentation photo - Item {{item.id}}"

Data Binding

Items with neither notes nor images are skipped entirely - they produce no output and no TOC entry.

Layout Options

item_template Blocks

Each item is rendered by iterating the item_template array. Three block types are supported:

sub_header

Renders the themed blue primary bar for each item.

Variable tokens available in header templates:

repeat_notes

Renders one paragraph per string in the resolved notes array.

image_grid

Renders a responsive N-column photo grid. Images are fetched and downsampled at render time.

Image path formats accepted:

Inline Suppression in the Main Table

When features.supplementaryAnnex: true, the render pipeline automatically suppresses notes and images from the main hierarchical table to avoid duplication:

• The Notes column value is replaced with a styled, clickable cross-reference: See supporting documentation - Item 0371 (clicking jumps directly to the annex section for that item).
• The Images column value is cleared so the "Images:" sub-row is hidden entirely.

This behaviour is automatic - no template changes are needed.

TOC Integration

When includeInToc: true, each qualifying annex item emits a TOC entry as a sub-section under the annex document title:

2.  Supporting Documentation
    2.1  Item 0371 - Push Pier, Drive Tool, Crawlspace
    2.2  Item 0349 - Push Pier, Drive Tool, Standard
    2.3  Item 300844 - Crock Kit

Each entry is a clickable internal link that jumps to the item's header in the annex. Page numbers are generated automatically.

sectionNumbering: true adds the 2.1, 2.2 ... prefix. When false, entries appear at the sub-section indent level without numbers.

Payload Structure

{
  "features": {
    "supplementaryAnnex": true
  },
  "Header": {
    "No.": "SO-00123",
    "Order Date": "2026-03-29"
  },
  "Lines": [
    {
      "No.": "0371",
      "Description": "Push Pier - Drive Tool, Crawlspace, Galv., Shorty",
      "Type": "Item",
      "Quantity": 2,
      "notes": [
        "Install per engineered drawings Rev B.",
        "Torque to 2,500 ft-lb minimum at each pier location."
      ],
      "images": [
        "Media/Images/push-pier-crawlspace-install.png",
        "Media/Images/push-pier-crawlspace-detail.png"
      ]
    },
    {
      "No.": "0349",
      "Description": "Push Pier - Drive Tool, Standard, 19\", Galv.",
      "Type": "Item",
      "Quantity": 2,
      "notes": [
        "Verify bearing stratum before terminating."
      ],
      "images": []
    },
    {
      "No.": "300844",
      "Description": "Crock Kit - Red Basin, Gray Lid, Small",
      "Type": "Item",
      "Quantity": 40,
      "notes": [],
      "images": []
    }
  ]
}

Items 0349 and 300844 have empty notes and images arrays - they are silently skipped by the annex renderer and produce no output.

Page Break Behaviour

Add "pagination": { "breakBefore": "always" } to the structured_content node in your template to force the annex onto a new page:

{
  "id": "supplementary-annex",
  "type": "structured_content",
  "props": {
    "assetPath": "Documents/SupplementaryAnnex/supplementary-annex-layout.yaml",
    "library": "assets"
  },
  "pagination": { "breakBefore": "always" }
}

Each item header and its notes block are kept together (unbreakable) so a header bar is never stranded at the bottom of a page without its content.

templateSettings Integration

The annex honours all active templateSettings - date formatting, locale, currency, and section numbering are applied consistently with the rest of the document.

{
  "templateSettings": {
    "dateFormat": "DD MMM YYYY",
    "locale": "en-AU",
    "toc": { "enabled": true },
    "sectionNumbering": true,
    "supplementaryAnnex": {
      "titleIcon": "file-text"
    }
  }
}

Feature Flag Reference

The features key lives at the root of the payload:

{
  "features": {
    "supplementaryAnnex": true
  }
}

Related Pages

• Structured Content - the structured_content node that hosts a supplementary annex layout
• Template Settings - toc, sectionNumbering, and locale options
• Hierarchical Table - the main data table whose Notes/Images columns are suppressed when the annex is active