Part 1: Text

This tutorial explains the core functionality of Report Builder by walking the user step by step through the creation of a sample report. The tutorial is primarily targeted at users that have access to the InstantAtlas data catalog. However, parts of the tutorial can still be used when working off a different source of data.


Before getting starting with the tutorial make sure to read these articles first:

– Create a new report from the IA Data Catalog
– The Report Builder User Interface

For the tutorial, create a new report from the data catalog and choose ‘Wards’ as geography. Use the 1000px screen size layout option when prompted.


Add a heading

To add a heading to your report, select the text widget from the toolbox and drag it into the report. This will open the text editor where you can edit and style the content.

Delete the default text with the text of your heading, e.g. ‘Population Profile’. Highlight the text with your mouse and click on the ‘Paragraph’ drop down in the menu bar of the text editor. Give the text a heading of 1. After that, use the align center button to center the text in the widget.

Click on the floppy disk icon to save your edits. To get out of the editor, click on the ‘X’ icon. You can re-open the editor at any time by double clicking on the widget or by doing a right click and selecting ‘Edit Text’.

To center the heading on the page, right click on the text widget. Choose Width > 100%. To change the vertical size of the text box, click on the widget and use the anchors for resizing. You will notice that you can’t place the widget freely on the workspace due to the underlying grid.

Add a line

The Break/Line widget is a  good choice when you need to make the heading stand out more or to separate blocks of content. Drag the widget into your workspace and place it underneath the heading. Then do a right click on the line and set the width to 100%.

You will notice a small offset between the heading and the line:

This is caused by the padding around widgets. Right click on the text and select ‘Properties’ and go into the ‘Spacing’ tab. Adjust the margins to move both widgets closer together. You might also need to resize the heading or the line to get rid of any additional space caused by the bounding box.

Your heading should now look like this:

Note that your heading is static at the moment and will be the same for all areas of the report. In the next step, we will make the text dynamic so that it updates to the name of the selected area.


Update the heading with a dynamic variable

Certain parts of your text, like area names or indicator values depend on the selected and should change when a different area is selected by the end user. For  cases like this, Report Builder makes use of ‘substitution variables’ that will automatically update to the correct value from the data catalog. Three substitution variables are available in the text editor:

The demo report is using the ‘Feature Name’ variable to display the name of the selected area in the heading.Double click on the heading to open the text editor and click on Feature Name. Adjust the text if necessary – it should now look like this:

Once you save the text, the substitution variable #FNAMES is replaced with the name of the currently selected ward. When you switch to another area, the name will be updated automatically.


Text Box

Text boxes with indicator values

The three ‘quick fact’ boxes of the demo also make use of substitution variables to show key statistics for an area. Text boxes behave similar to simple text but have an additional “Quick picks” tab in the properties. Quick picks are a bundle of style settings, that can be applied with a simple click.

To replicate these boxes, add a Text Box widget from the toolbox. Leave the demo text as is for now and close the text editor. Instead, go into the properties of the text box and switch to the ‘Quick Picks’ tab.

Hover over the ‘Blue Box’ tile and click apply to switch to this style. The ‘Settings’ tab gives you full control over all available widget settings.

First go into the ‘Borders, Colours & Styles’ group. Set the ‘Box Border Width’ setting to 0 px and then set the ‘Background Color’ property to gray by clicking on the colored box. Pick a gray tone in the color picker and apply the settings.

Close the properties now. You can resize the text box to a smaller size if necessary.

To replace the text box content, open the text editor and delete the demo text. The quick facts box makes use of the ‘Indicator Name’ and ‘Value’ substitution variables. If you click on either of these buttons in the editor, the data catalog opens with a list of themes.

You can either click on the folder icons to expand themes or use the search box to look for a specific indicator name.

Make sure to click ‘Value’ and select the indicator ‘Persons all ages’ from ‘Population > Estimates’. This will add the indicator value to the text (#ILVALUE). Switch to a new line and use ‘Indicator Name’ to add ‘Persons all ages’ to your text (#INAME) . Both variables should look like this – they will update once the text is saved. Note that they both refer to the same indicator ID (datastore:I351).

Variables can be styled just like normal text. First, select the whole text and align it to the center. Then highlight the indicator value and make it a ‘Heading 2’. Assign it a blue color with the respective option in the text editor. Optionally you can add further text to the box, like the source or a date.


When please with the style of the first box, you can simply duplicate it for box two and three. Right click on the widget and select copy, then right click on an empty space and select paste to insert it. You may need to adjust the size or the anchoring (from the right click menu) to get all three boxes on one line.

To update the content, use the ‘Males all ages’ and ‘Females all ages’ indicators from the ‘Population / Estimates’ theme. The demo report additionally has the rate indicators (%) underneath the population count values, these can be found in the same theme.

Your report should now look like this:


Congratulations! The first half of the report is now complete. Part 2 of the tutorial will demonstrate how to add tables and charts to the report.