QScript Functions to Generate Outputs
The functions below are designed to assist the QScript communicate to the user of the regarding changes that have been made by the QScript. The main ways of reporting on changes are to use logs, which will be shown in the box that appears at the completion of the QScript, and to add groups of tables for the questions that have been changed.
To make these functions available when writing a QScript or Rule see JavaScript Reference.
generateGroupOfSummaryTables(group_name, question_array)
This function generates a new group in the report tree with the name specified by group_name that contains a summary table for each question in the question_array. It returns the new group object.
generateSubgroupOfSummaryTables(group_name, within_group, question_array)
This function generates a new group in the input group within_group with the name specified by group_name that contains a summary table for each question in the question_array. It returns the new group object. generateSubgroupOfSummaryTables
generateGroupOfSummaryPlots(group_name, question_array)
This function generates a new group in the report tree with the name specified by group_name that contains a summary plot for each question in the question_array. It returns the new group object.
logQuestionList(message, question_array)
This function creates a new log entry that begins with the input message and then a list of the names of the questions in question_array, where each is given a new line. Logs are displayed once the script has finished running.
simpleHTMLReport(paragraphs, title, group, set_focus, web_mode)
Generates a Text item in the report group group with the elements of paragraphs as content, and the specified title. paragraphs should be an array of strings. Each string will be added as a separate line. If you want this new report to be selected in the Report tree at the conclusion of the script supply set_focus as true.
conditionallyEmptyLog(message)
If the Q version is such that we can avoid displaying blank logs then do nothing, otherwise log the message.
makeWordList(words)
Takes an array of variable names (strings) as input and returns a formatted string of the names in a comma separated list.
Source Code
includeWeb('QScript Value Attributes Functions');
// Standard styles for generating outputs
_GLOBAL_REPORT_BODY_TEXT_STYLE = { font: 'Tahoma', size: 10 };
_GLOBAL_REPORT_HEADING_STYLE = { font: 'Tahoma', size: 14 };
_GLOBAL_ITEM_HEADING_STYLE = { font: 'Tahoma', size: 20 };
// TELLING THE USER WHAT HAS BEEN DONE
function generateGroupOfSummaryTables(group_name, question_array) {
var web_mode = (!!Q.isOnTheWeb && Q.isOnTheWeb());
var num_questions = question_array.length;
var new_group = project.report.appendGroup();
new_group.name = group_name;
var new_table;
for (var j = 0; j < num_questions; j++) {
if (web_mode) {
var page = new_group.appendPage("Blank");
page.name = question_array[j].name;
new_table = page.appendTable();
}else
new_table = new_group.appendTable();
new_table.primary = question_array[j];
}
// More recent Q versions can point the user to the new items.
if (fileFormatVersion() > 8.65 && new_group.subItems.length > 0)
project.report.setSelectedRaw([new_group.subItems[0]]);
return new_group;
}
function generateSubgroupOfSummaryTables(group_name, within_group, question_array) {
var web_mode = (!!Q.isOnTheWeb && Q.isOnTheWeb());
var num_questions = question_array.length;
var new_group = within_group.appendGroup();
new_group.name = group_name;
var new_table;
for (var j = 0; j < num_questions; j++) {
if (web_mode) {
var page = new_group.appendPage("Blank");
page.name = question_array[j].name;
new_table = page.appendTable();
}else
new_table = new_group.appendTable();
new_table.primary = question_array[j];
}
return new_group;
}
function generateGroupOfSummaryPlots(group_name, question_array) {
var web_mode = (!!Q.isOnTheWeb && Q.isOnTheWeb());
var summary_group = project.report.appendGroup();
summary_group.name = group_name;
for (var i = 0; i < question_array.length; i++) {
var q = question_array[i];
var plot_type;
var q_type = q.questionType;
if (q_type == "Text" || q_type == "Text - Multi")
continue;
// Choose the appropriate plot type
if (q_type == 'Pick One') {
var non_missing_value_labels = nonMissingValueLabels(q);
var num_categories = non_missing_value_labels.length;
if (num_categories > 7)
plot_type = "Column plot";
else
plot_type = "Pie plot";
}
else if (q_type == 'Pick Any' || q_type == 'Pick Any - Compact' || q_type == 'Number - Multi' || q_type == 'Ranking')
plot_type = "Column plot";
else if (q_type == 'Experiment')
plot_type = "Bar plot";
else if (q_type == 'Number' )
plot_type = "Histogram";
else if (q_type == 'Pick One - Multi')
plot_type = "Stacked column plot";
else if (q_type == 'Pick Any - Grid' || q_type == 'Number - Grid')
plot_type = "Grid of bars plot";
else
plot_type = 'Column plot';
// Generate the plot
if (web_mode) {
var page = summary_group.appendPage("TitleOnly");
page.name = q.name;
var titleText = page.subItems[0];
titleText.text = page.name;
var plot = page.appendPlot(plot_type);
} else
var plot = summary_group.appendPlot(plot_type);
plot.primary = q;
}
// More recent Q versions can point the user to the new items.
if (fileFormatVersion() > 8.65 && summary_group.subItems.length > 0)
project.report.setSelectedRaw([summary_group.subItems[0]]);
return summary_group;
}
function logQuestionList(message, question_array) {
log(message);
log(question_array.map(function(q) { return q.name; } ).join("\r\n"));
}
// If the Q version is such that we can avoid displaying blank logs
// then do nothing, otherwise log the message. This allows us to phase
// out log messages which are not informative.
function conditionallyEmptyLog(message) {
if (fileFormatVersion() < 8.86)
log(message);
}
// Adds a text item to the top of group with the specified
// title and paragraphs. paragraphs should be an array of strings
// each of which will be added on a separate line.
// Make set_focus true if you want to change the selected items
// so that the user's view focuses on the new report page (only
// works in 4.11 and greater)
function simpleHTMLReport(paragraphs, title, group, set_focus, web_mode) {
var title_builder = Q.htmlBuilder();
title_builder.setStyle(_GLOBAL_ITEM_HEADING_STYLE);
title_builder.appendParagraph(title);
if (!web_mode)
{
var report = group.appendText();
group.moveAfter(report, null);
report.title = title_builder;
}
else
{
var title_text = group.appendText();
title_text.top = 50;
title_text.content = title_builder;
title_text.name = "Title";
var report = group.appendText();
report.top = 120;
report.name = "Content"
}
var content = Q.htmlBuilder();
content.setStyle(_GLOBAL_REPORT_BODY_TEXT_STYLE);
paragraphs.forEach(function (paragraph) {
content.appendParagraph(paragraph);
});
report.content = content;
// More recent Q versions can point the user to the report
if (fileFormatVersion() > 8.65 && set_focus)
project.report.setSelectedRaw([report]);
return report;
}
// Takes an array of variable names (strings) as input
// and returns a formatted string of the names in a
// comma separated list.
// E.g New variables 'var1', 'var2', and 'var3' created.
function makeWordList(words) {
if (Array.isArray(words) && words.length == 1){
return "New variable '" + words[0] + "' created. ";
}else if (Array.isArray(words) && words.length > 1) {
return "New variables '" + words.slice(0,words.length-1).join("', ")
+ "' and '" + words[words.length-1] + "' created. ";
}else
return "";
}