Blueprint Form Designer

The Form Designer controls how sections and fields are presented to contributors during edition data entry. Instead of a single scrolling list of fields, you can organise the blueprint into tabs, arrange fields in multi-column rows, choose per-section display modes, and control which fields appear in each layout block.

The Form Designer configuration is stored per blueprint and applied across all editions that use it.

---

Concepts

FormDesignerConfig

The top-level configuration object. It holds an array of tabs, each of which contains a set of layout rows.

Tabs

Tabs appear as clickable labels at the top of the edition form. Use tabs to separate major topic areas — for example: "Status & RAG", "Schedule", "Commercial", "Risks & Actions".

Tab property	Description
id	Unique identifier (slug-style, no spaces).
label	Display text shown on the tab.
icon	Optional icon name shown beside the label.

Layout rows and cells

Inside each tab, fields are arranged in rows of cells. This is a 12-column grid system — each cell has a span value from 1 to 12 that sets how many columns it occupies.

Cell span	Effective width
12	Full width (1 column layout)
6	Half width (2 column layout)
4	One-third width (3 column layout)
3	One-quarter width (4 column layout)
Varies	Custom widths — spans in a row should add up to 12

Each cell can optionally contain a form block (a section group of fields).

Form blocks

A form block associates one blueprint section with a cell in the layout. Its properties control the display mode and formatting of that section within the cell.

Block property	Values	Description
sectionId	Section ID	Which section's fields to show in this block.
displayMode	form / table / spreadsheet	How the section's fields are rendered in this block.
title	String	Override display title for this block (defaults to section name).
collapsed	Boolean	Whether the block starts collapsed (accordion-style).
formColumns	1 / 2 / 3 / 4	Number of columns the fields are arranged in within form display mode.
formDirection	vertical / horizontal	Whether fields flow down the columns first (vertical) or across rows first (horizontal).
defaultRowCount	Number	Initial number of rows shown in table/spreadsheet mode.
showRowNumbers	Boolean	Show row number column in table/spreadsheet mode.
compactMode	Boolean	Reduces padding and font size for dense data entry.
visibleFieldIds	Field ID array	Override which fields are visible in this block (shows all by default).

---

Display modes

Form mode

The default display mode. Fields are shown as labelled input controls arranged in the configured column layout.

• Use formColumns: 1 for long rich-text fields or sections where vertical space matters.
• Use formColumns: 2 or 3 for sections with many short fields (dates, numbers, selects, toggles).
• Use formColumns: 4 only for very compact sections with short labels and inputs.
• formDirection: vertical — fills column 1 top-to-bottom, then column 2, etc. Best for logical reading order within each column.
• formDirection: horizontal — fills left-to-right across all columns in each row. Best when fields relate across the row.

Table mode

Fields are shown as a table header row with one data row. This display mode is suited to single-entry sections with many fields that benefit from a compact, columnar layout — for example, a commercial status summary row.

• showRowNumbers: false is typical for single-row sections.
• compactMode: true reduces vertical space for read-heavy pages.

Spreadsheet mode

Used for repeating-row sections. Each row in the section becomes an editable row in an inline spreadsheet with column headers. Similar to grid mode but embedded inside the tab layout.

• defaultRowCount sets how many rows are shown before the "Load more" control appears.
• showRowNumbers: true helps contributors reference specific rows in comments.
• compactMode: true increases the number of rows visible without scrolling.

---

Configuration example

The following example shows a two-tab blueprint layout:

Tab 1 — "Status Overview" with a two-column layout: RAG summary on the left (half-width), a 3-column form for schedule fields on the right.

Tab 2 — "Risk Register" with a full-width spreadsheet block for the risk register section.

{
  "tabs": [
    {
      "id": "status-overview",
      "label": "Status Overview",
      "rows": [
        {
          "id": "row-1",
          "cells": [
            {
              "id": "cell-rag",
              "span": 6,
              "block": {
                "sectionId": "rag-summary",
                "displayMode": "form",
                "title": "RAG Summary",
                "formColumns": 1,
                "formDirection": "vertical"
              }
            },
            {
              "id": "cell-schedule",
              "span": 6,
              "block": {
                "sectionId": "schedule-status",
                "displayMode": "form",
                "title": "Schedule Status",
                "formColumns": 3,
                "formDirection": "horizontal",
                "compactMode": true
              }
            }
          ]
        }
      ]
    },
    {
      "id": "risk-register",
      "label": "Risk Register",
      "rows": [
        {
          "id": "row-risks",
          "cells": [
            {
              "id": "cell-risks",
              "span": 12,
              "block": {
                "sectionId": "risks",
                "displayMode": "spreadsheet",
                "showRowNumbers": true,
                "defaultRowCount": 10,
                "compactMode": true
              }
            }
          ]
        }
      ]
    }
  ]
}

---

Opening the Form Designer

1. Open a blueprint in the blueprint designer.
2. Click the Form Designer button in the top right of the designer toolbar.
3. The Form Designer panel opens alongside the field list.
4. Add tabs using the + Add Tab button.
5. Within each tab, add rows and drag fields from the field list into the layout cells.
6. Adjust cell spans using the span control on each cell.
7. Click a block to configure its display mode, columns, and other properties in the block settings panel.
8. Click Save layout to apply the configuration.

note

If no Form Designer configuration is set, the blueprint falls back to a single-tab layout with all sections displayed one after another using displayMode: form and formColumns: 1.

---

visibleFieldIds — showing a subset of fields in a block

If a section has many fields but a particular layout block should only show some of them, use visibleFieldIds to specify which fields appear in that block.

This is useful when:

• You want to split a large section across two side-by-side blocks (left block: identity fields; right block: status fields).
• You want a compact summary tab that shows only the most important fields, with a "Details" tab showing the full set.
• Different contributor roles need to see different subsets of the same section.

Fields excluded from visibleFieldIds are still accessible via their own section in the full form view — they are not hidden from the edition, only from this specific layout block.

---

Collapsed blocks

Setting collapsed: true on a block makes it start in an accordion-collapsed state when the contributor opens the edition. This is useful for:

• Secondary detail sections that most contributors leave unchanged.
• Historical reference sections that are rarely edited each cycle.
• Large attachment or evidence sections that should not clutter the main working area.

Contributors can expand any collapsed block with a single click.

---

Best practices

• Use 2–4 tabs for most blueprints. More than 5 tabs adds navigation overhead without improving clarity.
• Keep the most-edited fields on the first tab. Contributors should not have to navigate tabs to fill in required fields.
• Use formColumns: 2 as the default. Most field pairs (e.g. Forecast Date / Baseline Date; RAG / Trend) are natural pairs and read well in 2 columns.
• Use spreadsheet mode for risk and action registers. Inline row editing in a spreadsheet block is significantly faster than form-mode row entry for list-heavy sections.
• Mark progress-blocking fields on Tab 1. Contributors should be able to see their completion status without leaving the first tab.

---

Related

• Blueprint Field Types
• Create Your First Blueprint
• Edition Form Mode
• Edition Grid Mode
• Conditional Field Visibility