How to Create a Banner via QScript

Introduction

This article describes how to create a banner using a QScript. Banners allow users to combine multiple variable sets together so they can be viewed at the same time.

In most cases it is not necessary to create banners with a script because they can be created from the toolbar via Anything > Data > Variables > New > Banner. However, there may be need to automate this step in conjunction with other tasks.

Requirements

A Displayr Enterprise user license which includes the ability to add custom analysis menu items or use the Displayr API.
The importdata.zip file which includes the Phone data set that we will use for this article.
You have read How to Create a Custom QScript and How to Work with Variables via QScript.
You are using one of the methods from How to Use QScripts in Displayr.

Method

Banners are generated as new variable sets in a document's Data Sets tree. This process can in turn be replicated via QScript. Let's look at the following example:

var data_file = project.dataFiles[0];
data_file.createBanner("Demographic banner",
                       [[data_file.getQuestionByName("Age")],
                       [data_file.getQuestionByName("Gender")],
                       [data_file.getQuestionByName("Work status")]]);

We begin by declaring the data file as data_file.
We then apply the createBanner property to data_file and set the name as Demographic banner in the first argument.
The final part is to reference the name of each variable set to appear within the banner using the getQuestionName function. In this example, the banner contains three non-nested questions: Age, Gender and Work status. We can see that they are not nested by the square brackets surrounding each of the question calls.

It is also possible to nest these variable sets further by, for example, nesting Gender within Age by including both within the same square brackets:

var data_file = project.dataFiles[0];
data_file.createBanner("Demographic banner with nesting",
                      [[data_file.getQuestionByName('Age'), data_file.getQuestionByName('Gender')],
                      [data_file.getQuestionByName("Work status")]]);