A Research Dashboard is a useful tool for data analysis and presentation. It is composed of a number of pages which can contain any number of tables and/or charts for illustrating trends within survey data. Each table or chart is designed using a set of conditions like the ones that can be used to build segments in Crosstabs or hide questions within the survey editor.
The following sections introduce the fundamentals for creating beautiful and informative dashboards. In addition to this document, you may supplement your understanding by watching the following training video on programming basic dashboards.
Duration: 25 minutes
1: Accessing the Dashboard Menu
Dashboards can be programmed and viewed within the dashboard menu, which is specific to each project. To access the dashboard menu for your project, click on the project controls in the project portal and select “Dashboards" under the Report menu:
The dashboard menu will contain a list of every dashboard created for that project, and allow you to create a new one at any time using the dashboard editor:
Click here for an overview of the dashboard menu.
To create a new dashboard, click on the "+ New Dashboard" button at the top right of the dashboard menu:
2: Overview of the Dashboard Editor
A new dashboard will be created and opened within the dashboard editor. The editor includes both a survey datamap and a creation window, along with a variety of other task options:
Actions - The “Actions” menu at the top left will allow you to save your progress, as well as quickly search for and replace pieces of code at any time during dashboard creation.
Quick Reference - Clicking on “Quick Reference” will take you to the dashboard reference guide, where you can review the definitions and syntax for basic dashboard keywords and attributes.
- Survey Elements - The survey elements tree will appear on the left side of the dashboard menu and is included for reference during programming. You can click on the arrow next to any question label to expand and view its associated row labels.
By design, the survey elements tree will not display for surveys with over 200 questions.
4. Dashboard Name - Upon creation, the system will automatically generate a random name for your dashboard, default its access settings to “Private”, and set it to the latest dashboard Compat level. Each of these items can be adjusted at any time during the life of a dashboard.
5. Privacy - A dashboard can be marked as private or public:
Private: Reporting or Crosstabs permissions are required to view the page.
Public: Anyone with a link can view the dashboard as long as the dashboard has been published.
A public dashboard does not grant any further permissions such as editing the dashboard, viewing its code or accessing the reports for the project.
6. Compat - New dashboards are set to use the latest Compat level by default, but you can change this using the drop-down menu for “Compat”. For details on dashboard Compat levels, click here.
Any time you change the Compat level of your dashboard, you will need to ensure that all of your current dashboard elements will still function properly.
7. Scripting Window - This is where you will enter the actual script for programming the dashboard.
8. All Dashboards - Click here to go back to the project dashboard menu.
9. Save & Preview - Click here to save your dashboard settings and preview the dashboard as it will appear once published.
10. Save - Click here to save your dashboard settings.
You can use the following keystrokes within the dashboard editor for easy editing:
CTRL+S to Save
SHIFT+ENTER to switch between the dashboard editor and Save & Preview windows
CTRL+SPACEBAR to see a list of suggested keywords
3: Programming a Dashboard
Dashboards are programmed using a simple line-based script where each line begins with a keyword and ends with a number of arguments separated by spaces. The basic syntax is:
While no tags are necessary for programming a dashboard, you can borrow some syntax from other languages if you prefix your code with the html keyword.
Once you have created a dashboard using the steps above, you can start building it out within the scripting window beneath the info section in the dashboard editor:
During programming, you can preview the functionality and appearance of your script at any time by clicking on the “Save & Preview” button at the bottom of the page.
The dashboard editor will interpret the hash (
#) value as a comment indicator - anything after the
# will be treated as a comment and so hidden within the script. For example, the words “Minimal Dashboard” above will only appear in the code itself, not in the dashboard.
3.1: Required Variables
Although there are many different keywords you can use to customize your dashboard, only a few are required to build one. Every dashboard requires using at least the
chart keywords and their attributes for basic functionality.
Click here for a full list of available dashboard variables.
By default, each dashboard contains one tab. The keyword
page creates new tabs, which will appear as clickable buttons at the top of the dashboard:
page Pie Chart table id=db-1 What kind of smartphone do you own? total net 2 "Top 2" rows Q3.r1-r5 net -2 "Bottom 2" page Bar Graph
page keyword has two sub-attributes,
page.subheader. Both of these sub-attributes are optional and will be displayed before any tables or charts.
page [title] page.header <title> page.subheader <title>
page Satisfaction Summary page.header How satisfied are our customers? page.subheader Quarter 4
The above script adds the title "Satisfaction Summary" to the first tab and creates two headers that display at the top of that tab:
If the number of pages in your dashboard exceeds the available screen space, they will automatically become scrollable by title:
If preferred, you can set the page titles to appear within a drop-down menu instead by adding
scrollabletabs 0 to your code:
The drop-down will only appear if you have too many pages in the tab bar.
table adds a new table to the dashboard which will pull data from a question. Each table requires both a
title and at least one
row value. The
title can be anything, and if one is not specified, the base question's title will be used. The
row adds a single row to the table, and should have both a
table [title] row <condition> [title]
table Gender of Respondents row Q1.r1 Male row Q1.r2 Female
In the second example below, a special syntax (
attr) is used to reference the base question's attributes. This is mandatory only when you need to access question attributes that are not valid Python identifiers:
table Gender of Respondents row 'Q1.attr("1")' Male row 'Q1.attr("2")' Female
For example, the following
rows contain invalid Python names and could only be referenced using the
<row label="1">Male</row> <row label="2">Female</row>
You can also use the keyword
rows to add multiple rows to a table, and these can be identified using individual row labels with name-spacing, or as ranges:
rows [row] [row] ... rows [questionLabel.startingRow]-[endingRow]
For example, the two segments below would produce the same result:
table Favorite Color rows Q2.r1 Q2.r2 Q2.r3 Q2.r4 Q2.r5 table Favorite Color rows Q2.r1-r5
To save time, the dashboard system is also equipped with an easy-to-use templating system. Consider the following example:
table Top Vehicle Satisfaction row "Q2.r1.c9 or Q2.r1.c10" Toyota row "Q2.r2.c9 or Q2.r2.c10" Ford row "Q2.r3.c9 or Q2.r3.c10" Honda row "Q2.r4.c9 or Q2.r4.c10" Tesla row "Q2.r5.c9 or Q2.r5.c10" Chevrolet
This example displays the counts of those who rated
c10 for the cars shown. The following example produces the same result and requires much less typing:
table Top Vehicle Satisfaction rows code="$.c9 or $.c10" Q2.r1-r5
This code produces the same result because the default condition logic is overridden using the
code keyword and the dollar sign (
$). The dollar sign is a copy of the default condition and everything else is additional logic.
For example, the code
rows Q2.r1-r5 produces 5 rows with the default conditions
Q2.r5. The system stores these default conditions into the dollar sign variable and enables you to extend the logic using the
code attribute. The example below produces the same result and should help you better understand how the
code attribute works, but it is not nearly as efficient as either of the two examples above:
table Top Vehicle Satisfaction row code="$.c9 or $.c10" Q2.r1 Toyota row code="$.c9 or $.c10" Q2.r2 Ford row code="$.c9 or $.c10" Q2.r3 Honda row code="$.c9 or $.c10" Q2.r4 Tesla row code="$.c9 or $.c10" Q2.r5 Chevrolet
As illustrated below, the dollar sign variable may also be used with the
base keyword. The following two examples produce the same result:
table Top Vehicle Satisfaction rows base=$.any code="$.c9 or $.c10" Q2.r1-r5 table Top Vehicle Satisfaction row base=Q2.r1.any "Q2.r1.c9 or Q2.r1.c10" Toyota row base=Q2.r2.any "Q2.r2.c9 or Q2.r2.c10" Ford row base=Q2.r3.any "Q2.r3.c9 or Q2.r3.c10" Honda row base=Q2.r4.any "Q2.r4.c9 or Q2.r4.c10" Tesla row base=Q2.r5.any "Q2.r5.c9 or Q2.r5.c10" Chevrolet
chart keyword can be used to add a chart as a visual representation of your survey data. There are two ways to add a chart, and both methods require that you specify at least its
1. The keyword
chart can be added to a
table to create a chart based on the rows within the table.
table Gender of Respondents rows Q1.r1-r2 chart Gender Pie Chart type pie
2. A standalone chart can also be added in the same way a table is added - by adding the
chart keyword with its
chart Gender Pie Chart type pie rows Q1.r1-r2
title can be anything, but its
type needs to be one of the following available types:
Vertical Bar (
Horizontal Bar (
Scatter Plot (
If you do not specify a
type for your chart, the system will default it to a
Click here to see some dynamic demonstrations of the various chart types above. Some chart types are complex and require extra scripting. Click here for more information about complex chart types and additional customization options.
3.2: Other Essential Variables
The following is a list of some other essential keywords and attributes for dashboard creation. Along with the
chart keywords, these attributes can help make your dashboard appear more robust:
Click here for a complete list of available dashboard variables and their descriptions.
You can also click on the “Quick Reference” button located in the top-left corner of the dashboard editor to conveniently reference the above keywords and more while building your dashboard.
id is a system-generated variable that will appear after every keyword and attribute you add once you have saved your dashboard:
You can change the
id to add a custom identifier (or name) to any attribute, which can then be referenced in any custom hooks that you may set up for your dashboard in future.
By default, charts, tables and html blocks sit within containers that use the full width of the screen. Dashboards use a 12-column layout and the keyword
width allows you to customize how wide each container should be displayed. The default and maximum width is 12.
Page Smartphone Owners table width=4 Gender of Respondents total rows Q1.r1-r2 chart width=8
In this example, the table takes up 33% of the width and the chart takes up 66% of the width. They are laid out on the same line, side by side, since their total widths do not exceed 12. Any combination is possible, but below are a few examples of common layouts:
sortable enables sorting on a chart.
chart Gender of Respondents rows Q1.r1 Q1.r2 sortable 1
sortable turned on, charts can be sorted by text or by counts.
By default, charts that are not standalone will be displayed after the table. Use
pos before to display the chart before the table it is created from.
table width=6 Gender of Respondents rows Q1.r1-r2 chart width=6 Pie Graph type pie pos before
transpose interchanges all rows with segments.
table width=3 Gender rows Q1.r1-r2 table width=3 Gender (transposed) rows Q1.r1-r2 transpose
pct allows you to control the precision of vertical percentages. The default precision is
pct=off to disable.
table width=3 Gender rows q1.r1-r2 table width=3 Gender rows q1.r1-r2 pct 3
This configuration will show the percentage values precisely to the thousandth decimal place:
By default, each row displays a count and vertical percentage. The keyword
counts allows you to control the displaying of the counts. The default is
counts=off to disable.
table width=3 Gender rows q1.r1-r2 table width=3 Gender rows q1.r1-r2 pct 3 counts off
This configuration hides the counts in the second table:
By default, charts and tables are displayed in both the dashboard and exported files (Excel, PDF, PowerPoint). The keyword
where allows you to specify where each table and chart should be displayed. Use "
export" to display each element only in the exported files and "
dashboard" to display it only in the dashboard.
table Gender of Respondents where export
The above configuration will show the gender table in the exported files only and hide it from the dashboard view.
4: Additional Customization
Dashboard creation doesn’t end with the basics! There are many other options available for customizing the look & feel of your dashboard. If you are interested in re-structuring your dashboard, adjusting its style, or changing your data options, click here for advanced programming instructions.
For element-specific customization, see also: