How to Create a Banner via QScript

This article describes how to create a banner using a QScript. Banners allow users to combine multiple questions 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 Create > Banner > Drag and Drop. However, there may be a need to automate this step in conjunction with other tasks.

Requirements

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 Q.

Method

Banners are generated as new variable sets in a project's Variables and Questions tab. 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 questions 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")]]);