LayoutPage

LayoutPage manifests describe full pages of a report. They control headers, date and measure metadata, page size/orientation, and child components.

Spec outline

apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: sales_overview_page
spec:
  titleBusinessUnit: "Sales"
  titleNamespace: _system
  titleDateStart: 2024-01-01
  titleDateEnd: 2024-03-31
  titleDateFormat: quarter
  titleDateLink: interval
  titleMeasures: []
  titleScenarios: "ac,fc,py"
  titleVariances: "dac_ac_pos"
  titleOrder: category
  titleOrderDirection: asc
  pageLayout: 2x2
  pageFormat: a4
  pageOrientation: landscape
  footerDisplayPageNumber: true
  footerText: "Internal use only"
  messageImage: "debug/concordia.png"
  messageText: "Placeholder message"
  children:
    - kind: ChartStructure
      spec: { ... }
    - kind: Table
      spec: { ... }

Key fields (see JSON schema for full list):

Title row fields: titleBusinessUnit, titleNamespace, titleDateStart, titleDateEnd, titleDateFormat, titleDateLink, titleMeasures, titleScenarios, titleVariances, titleOrder, titleOrderDirection.
Page frame fields: pageLayout, pageCustomTemplate, pageGridGap, pageFormat, pageOrientation, pageFitToContent, pageNumber, footerDisplayPageNumber, footerText.
Message row: messageImage, messageText.
Content: children – required array of layoutChild objects.

Page layouts

pageLayout controls how components are arranged. The enum includes:

full
split-horizontal, split-vertical
2x2, 3x3, 4x4
1-over-2, 1-over-3, 2-over-1, 3-over-1
custom-template

For custom-template, set pageCustomTemplate to a CSS grid-template-areas string, for example:

pageLayout: custom-template
pageCustomTemplate: |
  "a a" \
  "b c"

Minimal full-page example

---
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: kpi_dashboard
spec:
  titleBusinessUnit: "Group Controlling"
  titleNamespace: _system
  titleDateStart: 2024-01-01
  titleDateEnd: 2024-12-31
  titleDateFormat: year
  titleDateLink: none
  titleMeasures:
    - name: "Revenue"
      unit: "mEUR"
  titleScenarios: "ac,fc,py"
  pageLayout: 2x2
  pageFormat: a4
  pageOrientation: landscape
  footerDisplayPageNumber: true
  footerText: "bino – internal preview"
  children:
    - kind: ChartStructure
      spec:
        dataset: revenue_by_region
        chartTitle: "Revenue by region"
        level: category
        scenarios: ["ac1", "py1"]
        variances: ["dpy1_ac1_pos"]
    - kind: Table
      spec:
        dataset: revenue_by_customer
        tableTitle: "Top customers"
        type: list
        limit: 10

Later you can add more components or convert parts of the page into LayoutCard children.

Referencing standalone components

Instead of inlining the full spec for each child, you can reference standalone document manifests by name using the ref field. This enables component reuse across multiple pages and cleaner separation of concerns.

Basic reference

# Define a reusable chart as a standalone document
---
apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: salesTrendChart
spec:
  dataset: monthly_sales
  chartTitle: "Monthly Sales Trend"
  dateInterval: month
  level: category

---
# Reference it in a LayoutPage
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: dashboard
spec:
  pageLayout: 2x2
  children:
    - kind: ChartTime
      ref: salesTrendChart

Reference with overrides

You can override specific fields from the referenced document by providing a partial spec. The override is deep-merged with the base spec (objects merge recursively, arrays replace entirely).

children:
  - kind: ChartTime
    ref: salesTrendChart
    spec:
      chartTitle: "Q4 Sales Trend" # Override just the title
      dateInterval: quarter # Override the interval

Supported reference targets

You can reference documents of these kinds:

Text
Table
ChartStructure
ChartTime
LayoutCard
Image

Note: LayoutPage cannot be referenced. Each page must be a root document.

Missing references

By default, if a referenced document doesn’t exist, the build fails with an error. This fail-fast behavior helps catch typos, missing files, and broken references early.

Error: required reference "revenue_chart" of kind "ChartTime" not found

Constraint-filtered refs are handled differently: if a referenced document exists but was filtered out by constraints for the current artefact, the child is silently skipped. This allows constraint-based filtering to work naturally with referenced components.

Optional references

For references that may legitimately be missing (e.g., debug-only components, environment-specific features), use the optional field:

children:
  - kind: ChartTime
    ref: salesTrendChart      # Required: fails if missing
  - kind: Text
    ref: debugPanel
    optional: true            # Optional: skips gracefully if missing

When optional: true and the ref is missing, the child is skipped with an info log instead of failing the build.

When to use optional: true:

Preview/debug-only components (filtered by mode constraints)
Environment-specific features (filtered by env labels)
Format-specific components (may not exist for all output formats)

Do not use optional: true to work around typos or missing files. Always fix the actual issue instead.

Inline child constraints

Inline children can have metadata.constraints to conditionally include them based on the target artefact’s context. This allows different components to appear for different artefacts, modes, or environments.

Basic syntax

Constraints support two formats: string (concise) and structured (IDE-friendly).

apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: dashboard
spec:
  pageLayout: 2x2
  children:
    # String format - quick and readable
    - kind: Table
      metadata:
        name: prodTable
        constraints:
          - mode==build
          - labels.env==prod
      spec:
        dataset: production_data

    # Structured format - better IDE support
    - kind: Text
      metadata:
        name: debugInfo
        constraints:
          - field: mode
            operator: "=="
            value: preview
      spec:
        value: "Debug information - only visible in preview"

    # No constraints - always included
    - kind: ChartStructure
      spec:
        dataset: summary_data

Operators

Operator	Description	String Example	Structured Example
`==`	Equals	`labels.env==prod`	`{field: "labels.env", operator: "==", value: "prod"}`
`!=`	Not equals	`mode!=preview`	`{field: "mode", operator: "!=", value: "preview"}`
`in`	Value in array	`labels.env in [dev,qa]`	`{field: "labels.env", operator: "in", value: ["dev", "qa"]}`
`not-in`	Value not in array	`mode not-in [serve]`	`{field: "mode", operator: "not-in", value: ["serve"]}`

Field reference

Field Path	Description	Example Values
`mode`	Current execution mode	`build`, `preview`, `serve`
`labels.<key>`	Artefact’s `metadata.labels.<key>`	Any string value
`spec.<field>`	Artefact’s `spec.<field>`	Format, orientation, etc.

Example: Mode-specific children

spec:
  pageLayout: split-vertical
  children:
    # Only in build mode
    - kind: Table
      metadata:
        constraints:
          - mode==build
      spec:
        dataset: final_data

    # Only in preview mode
    - kind: Text
      metadata:
        constraints:
          - mode==preview
      spec:
        value: "Preview placeholder - data will appear in build"

For comprehensive constraint documentation, see Constraints and Scoped Names.