Getting started with dashboard commands

See Crunch Automation basics for more information.

Crunch dashboard components

The CREATE DASHBOARD command defines a Crunch dashboard.

A Crunch dashboard presents tables and graphs from a single dataset and contains live data along with commentary in a series of ‘tiles’ arranged into sections called ‘tabs’. Crunch Automation represents the complete declarative definition of the dashboard and all of its contents in text. The simplest dashboard contains a title, a single tab, and one or more tiles.

The following image is an example script, which describes the various dashboard elements: the entire CREATE DASHBOARD command, which includes one or more TABs, one or more TILEs, and optionally, GROUPS. Note the overall nested structure whereby TILEs live inside TABs and GROUPs appear at the end, all within the overarching CREATE DASHBOARD command, which ends with a semi-colon (;).

Title

Each dashboard has a title which cannot be empty and must be unique within that dataset. This is the only property of the dashboard itself.

Tabs

Dashboards must contain at least one tab. Each tab must have a title and can contain zero or more tiles, though a tab without any tiles will be blank.

Tiles

Tiles are rectangular containers arranged in a grid of relative-sized squares (the absolute sizing of the dashboard, and therefore of each tile, depends on the size and resolution of the viewer’s display). The grid is 12 squares wide and as tall as needed to display the content.

Each tile has a title (which may be an empty string `""` but not null). Each tile must indicate its size and the type of its contents: markdown (including images), video, iframe, or analysis. Tiles cannot be empty, though a markdown tile with no content will appear as empty. The bulk of this document will describe the analyses and the ways different customizations and display options are described in the script.

Currently, CREATE DASHBOARD cannot be combined with other Crunch Automation commands used to prepare or organize and share datasets (e.g., renaming and transforming variables, moving datasets, and sharing folders).

As a reminder, Crunch Automation commands are presented in capitals for legibility but are not, in fact, case sensitive. Similarly, line breaks and indentation are added for legibility in this documentation but are ignored by the system.

Dashboard commands

CREATE DASHBOARD

CREATE DASHBOARD <dashboard name>

Dashboard scripts must begin with a CREATE DASHBOARD command. This command tells Crunch that this script will define a dashboard and that no other Crunch Automation content will be present in this script. Each dashboard must have a name and must be unique among other dashboards in this dataset. This name will appear in the header of the dashboard and in the list of dashboards to which users can navigate. The name can be changed at a later stage via the web-app.

TAB

TAB <tab name>

Dashboards must contain at least one tab as a container for the content. Dashboards with just one tab will not show any tabbed structure and will appear to the user to have no tabs. Dashboards with two or more tabs will display tabbed navigation.

A dashboard with only one tab will appear to the user to have no tabs:

A dashboard with more than one tab will display in a tabbed layout:

Tabs are useful for organizing dashboard content by theme (e.g., by region, sector, or topic), especially for larger dashboards. Each tab must have a non-empty name, even if only one tab is defined. The order in which tabs are defined in the script determines the order they appear in the application. Moving a tab (group of tiles) in the app moves the associated tab and its tiles in the script as well. Dashboards will always open starting with the first tab unless otherwise specified in the URL. Tabs can be empty, though empty tabs will appear like a blank container. Tiles cannot be placed outside of a tab. The only element of a dashboard that does not sit within a tab is the GROUPS panel (see below).

TILE

TILE "tile name" 
		[LEFT INT] [WIDTH <INT>] [HEIGHT <INT>]
		(SUBTITLE <tile subtitle>)?
		(FOOTNOTE TEXT <tile footnote>)?
		<Tile body>

A tile body consists of one of the following types:

ANALYSIS
MARKDOWN
IFRAME
VIDEO

REPLACE DASHBOARD

REPLACE DASHBOARD <existing dashboard name>

The REPLACE DASHBOARD command effectively overwrites the mentioned dashboard with the new definition of the body.

General syntax

CREATE DASHBOARD <dashboard name>
	<dashboard tab>+
	<dashboard groups>

Dashboard name

<dashboard name> — Quoted string, which is the name of the dashboard to generate.

Dashboard tabs

TAB <tab name>

<tab name> — Quoted string with the tab name, which cannot be empty.

Dashboard tiles

TILE <tile name> 
		<tile dimensions>
		(SUBTITLE <tile subtitle>)?
		<Tile body>
		(FOOTNOTE TEXT <tile footnote>)?

<Tile body> — Can include the following 4 types (non-analytical tiles):

MARKDOWN <markdown body> – Must be a triple backtick (```) quoted multiline string.
VIDEO <url> – Quoted url string, which validates that it’s a URL (not that it works).
IFRAME <url> – Quoted URL string, which validates that it’s a URL (not that it works).
Analysis – Must indicate the type of analysis to make.

Help Center