Modify Footers - Add Descriptions of Selected Data (e.g., Question Name, Skips, Filtering) from File

This QScript adds additional descriptive text to the footer of the tables and chart in the project whenever particular questions are shown (e.g., notes about the base). This allows for the addition of descriptions that are relevant only for certain questions. For example, when some questions are not shown to all respondents this QScript can be used to insert descriptions of the relevant part of the sample whenever one of those questions is shown in a table. This QScript is used to add all necessary descriptions to the project at once.

Information about the descriptive text for each question should be prepared in an Excel or CSV file according to the formatting described below. When the script runs you will be prompted to select this file.

This QScript automates the application of the rule called Modify Footers - Description of Selected Data (e.g., Question Name, Skips, Filtering). See that rule for more detail and examples of the result.

Technical details

This QScript requires that the information about which descriptive text should be included with each question is entered into a simple Excel file. You can select which file contains your footer information at the time the script is run. The file should contain two columns:

The first column should be called Question Name, and should contain some text from the name of the question.
The second column should be called Footer Text, and should contain the footer message that should be shown on tables or charts that have this question selected.

Whenever a question whose name contains the text from the first column is shown in a table or chart, then the corresponding text from the second column will be added to the footer.

The modifications are made using the rule Modify Footers - Description of Selected Data (e.g., Question Name, Skips, Filtering), and so the text can be changed later on by modifying the rule by selecting the Rules tab below a table, selecting the name of the rule, and then selecting Edit Rule.

Tips for matching descriptions

The text entered into the Question Name column will be used to match the descriptive information to the questions in your project. It is important to note the following points to make the best use of this QScript:

Question names don't have to match exactly and this offers some flexibility if you rename and make duplicate questions in your project.
You should enter question names that each only match one question in your project to avoid a description being added for the wrong question. For example, if you specify descriptive text for the question Q2. Gender by typing the text Q2 and there are also questions named Q20., Q21., etc, then the descriptive text will be applied incorrectly to these other questions. The better choice would likely be Q2.. When making duplicates of questions in your project, ensure that their names still match the text entered here for this script.
It is best to make sure that each of the question names entered here match at least one question in the project.
The question names and text can always be modified later on by selecting the Rules tab below a table, selecting the name of the rule, and then selecting Edit Rule.

How to apply this QScript

Start typing the name of the QScript into the Search features and data box in the top right of the Q window.
Click on the QScript when it appears in the QScripts and Rules section of the search results.

OR

Select Automate > Browse Online Library.
Select this QScript from the list.

Customizing the QScript

This QScript is written in JavaScript and can be customized by copying and modifying the JavaScript.

Customizing QScripts in Q4.11 and more recent versions

Start typing the name of the QScript into the Search features and data box in the top right of the Q window.
Hover your mouse over the QScript when it appears in the QScripts and Rules section of the search results.
Press Edit a Copy (bottom-left corner of the preview).
Modify the JavaScript (see QScripts for more detail on this).
Either:
- Run the QScript, by pressing the blue triangle button.
- Save the QScript and run it at a later time, using Automate > Run QScript (Macro) from File.

Customizing QScripts in older versions

Copy the JavaScript shown on this page.
Create a new text file, giving it a file extension of .QScript. See here for more information about how to do this.
Modify the JavaScript (see QScripts for more detail on this).
Run the file using Automate > Run QScript (Macro) from File.

JavaScript

includeWeb("QScript Functions to Generate Outputs");

if (!main())
	log("QScript Cancelled.");
else
	conditionallyEmptyLog("QScript Finished.");

function main() {
	includeWeb("QScript Selection Functions");
	// Import the file containing presets
	var preset_file;
	if (Q.fileFormatVersion() < 8.39) {
		preset_file = filePromptWithVerification("Please paste the path and filename of the CSV/Excel file that contains the question names and footer text. For example: C:\\Chris\\Documents\\footer.csv", "Footer info", {col_names_included: true});
	} else {
		preset_file = project.addDataFileDialog("Select Excel/CSV File Containing Question Names and Footer Text", {col_names_included: true});
	}

	// Get data from the preset file
	var preset_variables = preset_file.variables;
	if (preset_variables.length != 2) {
		log("Expected the file to contain two columns.")
		return false;
	}
	var raw_data = preset_variables.map(function (v) { return v.rawValues; });
	var presets = [];
	var n_presets = raw_data[0].length;
	for (var j = 0; j < n_presets; j++) {
		presets.push([raw_data[0][j], raw_data[1][j]]);
	}
		
	// Combine the preset options as an object that can be fed to the rule
	var parameters = {};
	presets.forEach(function (p, ind) {
		var prop_name = "ft" + ind; // Text boxes for footer text in the rule are labeled "ft0", "ft1", etc
		parameters[prop_name] = p[1];
		prop_name = "qnametext"+ ind; // Text boxes for question names
		parameters[prop_name] = p[0];
	})

	// Add the rule to the project and all current tables/plots
	var rule_man = project.rules;
	var new_rule = rule_man.newFromLibrary("Modify Footers - Description of Selected Data (e.g., Question Name, Skips, Filtering)", parameters);
	new_rule.isDefault = true;
	recursiveAddRule(project.report.subItems, new_rule);

	preset_file.remove();
	return true;
}

// Function to add a rule recursively to an array of report items
function recursiveAddRule(item_array, rule_object) {
	item_array.forEach(function (item) {
		if (item.type == "Table" || item.type == "Plot")
			item.rules.add(rule_object);
		else if (item.type == "ReportGroup")
			recursiveAddRule(item.subItems, rule_object);
	});
}