`layout.json`

The path to a layout file should be site/layouts/PAGE-NAME.json.

Every layout.json file has the same format:

{
  "charts": {
    "my-gender-chart": { "kind": "donut", "field": "gender" }, 
    //    ^chart id          ^chart type     ^associated field from records.json
    ... // more charts
  },
  "columns": [
    { "title": "Cases", "children": ["my-gender-chart", ...] },
    ... // more columns
  ]
}

Field	Description
`charts`	required Contains all the charts that will be displayed on the page.
`columns`	required Groups charts into column displays.

Charts

Each item inside the charts block represents one chart in Lookout. A chart is configured like this:

{
  "charts": {
    "my-gender-chart": { "kind": "donut", "field": "gender" }, 
    //    ^chart id        ^chart type     ^associated field from records.json
    ... // more charts
  },
  "columns": [ ... ]
}

Field	Description
`kind`	required Specifies the type of chart.
`field`	required Determines which data field from `records.json` is linked to the chart.
`label`	optional Specifies the name of the chart as it appears on the dashboard.
Additional props	optional Depending on the `kind` of chart, some charts may require additional properties.

Chart sizing

Each kind of chart has a default height. (Possible heights are xs, sm, md, lg, xl, 2xl, 3xl, or 4xl.) If you want to override that height, you can add a /<height> to the end of the chart id in columns.

EXAMPLE

"columns": [
  { 
    "title": "Charts",
    "children": [
      "my-gender-chart/md", // overrides default height to medium
      "my-case-chart/lg", // overrides default height to large
      "my-age-chart", // uses default small height
    ]
  }
]

Based on the height you specify, charts might render in different layouts, or with more or less information.

To see a full list of all the different chart kinds and their required props, see Chart Types.

Columns

Each item in columns represents one column of the Lookout page. A column is configured like this:

{
  "charts": { ... },
  "columns": [
    { 
      "title": "Demographics", 
      "children": ["my-gender-chart", "my-age-chart"] 
    },
    ... // more columns
  ]
}

Field	Description	Type
`title`	required The title at the top of the column.	`string`
`children`	required A list of chart ids or template blocks contained in the column.	`string array`
`relative-width`	optional Relative width of the column compared to the others. Defaults to `1`.	`integer`

Charts in a children array are automatically ordered by Lookout. If you want them to appear in a specific order, you can group the charts within the children field.

EXAMPLE

    "children": ["my-case-chart", ["my-age-chart", "my-gender-chart"], "my-occupation-chart"]

(Note: you can also wrap a single chart in a list to exclude it from auto-grouping.)

Group Blocks

Within a column’s children, charts can be sorted into several Group Blocks that we’ve included with the template field. To use a Group Block, add a dictionary to the column’s children array with its respective fields.

Group Block	`template`	Fields
Grid	`grid`	`template`, `children`, `columns`
List	`list`	`template`, `children`
Toggle	`toggle`	`template`, `children`
Multi-Pathogen	`multi-pathogen`	`template`, `primary`, `secondary`

EXAMPLE

    "children": [
      "my-case-chart",
      {
        "template": "grid", // or "list", "toggle", etc.
        "children": ["my-age-chart", "my-gender-chart"]
      },
      "my-occupation-chart"
    ]

For all Group Blocks except Multi-Pathogen, the children field contains an array of all the chart IDs that will appear in the block.

Grid

Lays charts out in a grid pattern. This is the default group type when using auto-grouping.

The optional columns field determines how many columns the grid will span across.
The optional child-height field overrides the default height of each child.

{
  "template": "grid",
  "columns": 3, // optional, defaults to 2
  "child-height": "md", // optional, defaults to best height based on children
  "children": ["my-age-chart", "my-gender-chart"]
}

List

Lays out charts in a vertical list.

{
  "template": "list",
  "children": ["my-age-chart", "my-gender-chart"]
}

Toggle

Allows you to toggle between multiple full-sized charts in children. Any manually-specified heights in children are overriden by child-height.

{
  "template": "toggle",
  "child-height": "md", // optional, defaults to best height based on children
  "children": ["my-age-chart", "my-gender-chart"]
}

Multi Pathogen

The primary and secondary fields replace the children field for multi-pathogen Group Blocks.
required primary contains chart IDs to be displayed at a larger size.
required secondary contains chart IDs to be displayed at a smaller size. Can be empty.

{
  "template": "multi-pathogen",
  "primary": ["flua", "flub", "malaria"],
  "secondary": ["lassa", "yellowfever", "fluc"] 
}

Groups can be nested inside of other groups’ children, though we don’t recommend doing this extensively. Group blocks can optionally specify the same label property that charts have, which will hide its childrens’ labels.