Table Selection Functions

This page contains the main QScript code for selecting rows and columns from tables, which is used by Tables - Select, Calculate - First, and Calculate - Last.

To make these functions available when writing a QScript or Rule see JavaScript Reference.

selectFromTables(default_selection_mode)

This is the main function used by the QScript Tables - Select. It works with tables the user has selected on their page and adds them as Inputs to Tables - Select Rows and Columns from Table. The one input default_selection_mode specifies which selection mode should be chosen as the default for the Inputs Select rows by and Select columns by for each table. See the documentation in Tables - Select for a full list of possible values, the default is "Selecting options below".

insertDataTable(raw_table)

This function creates either Tables - Raw Data - Variables (when argument raw_table is true), or Tables - Descriptive Statistics otherwise, from whichever variables are selected by the user.

Source Code

includeWeb('QScript Utility Functions');  // for in Displayr
includeWeb('QScript R Output Functions'); // for generateUniqueRObjectName
includeWeb('QScript Table Functions');    // for recursiveGetAllTablesInGroup
includeWeb('QScript Selection Functions');// for getAllUserSelections and validTableOrTableLikeROutput

function selectFromTables(default_selection_mode = 'Selecting options below') {
    if (Q.fileFormatVersion() < 20.00) {
        let msg = 'Sorry, you must upgrade to a Q version >= 5.12 to use this feature.' +
                  'If you are unable to upgrade, you may instead use: ' +
                  '    \'Create > Tables > Select Rows and Columns from Table\'.' +
                  'This will similiary insert a new output that you may use to select a subset' +
                  ' of rows and columns to display for any of the tables in your project.';
        log(msg);
        return false;
    }
    let selections = getAllUserSelections();
    let raw_selections = project.report.selectedRaw();
    let is_displayr = inDisplayr();
    let valid_selections;
    let group;
    if (raw_selections.length === 0 || (raw_selections.length === 1 && selections.selected_pages.length === 1)) {
        group = project.currentPage === undefined ? false : project.currentPage();
        if (!group) {
            if (!is_displayr)
                group = project.report;
            else {
                group = project.report.appendGroup();
                group.name = 'New page';
    	    }
	    }
        valid_selections = [];
    }else {
        selections = [].concat(selections.selected_tables, selections.selected_r_outputs);
        valid_selections = splitArrayIntoApplicableAndNotApplicable(selections, validTableOrTableLikeROutput);
        valid_selections = valid_selections.applicable;
        if (valid_selections.length === 0) {
            let msg = 'The current selections cannot be used with this feature. ' +
                      'Please click on the Tables and/or Calculations containing ' +
                      'tables to be selected from and rerun.';
	        log(msg);
            return false;
        }
        if (valid_selections.length < raw_selections.length)
            log('Some selections were not tables and have been ignored.');
        group = valid_selections[0].group;
    }
    let prefilled_controls = {};
    if (valid_selections.length > 1){
        let table_names = prompt('Please enter names for the ' + valid_selections.length +
                                 ' selected tables, separated by commas.');
        let cb = group.appendControl('Combobox');
        cb.top = 0;
        cb.left = 0;
        cb.placeholderText = 'Select table to show...';
        cb.selectionMode = 'SingleSelection';
        cb.whenItemListChanges = 'KeepCurrentSelection';
        cb.itemList = table_names.split(',');
        cb.selectedItems = table_names.split(',').slice(0,1);
        prefilled_controls['formTableNames'] = table_names;
        prefilled_controls['formTableSelection'] = cb.guid;
    }
    for(let i = 0; i < valid_selections.length; i++) {
       valid_selections.hiddenFromExportedViews = true;
       prefilled_controls['formTable'+(i+1)] = valid_selections[i].guid;
       prefilled_controls['formRowSelectorTbl'+(i+1)] = default_selection_mode;
       prefilled_controls['formColSelectorTbl'+(i+1)] = default_selection_mode.replace('row', 'column');
    }
    let selected_table = group.appendStandardR('Tables - Select Rows and Columns from Table', prefilled_controls);
    project.report.setSelectedRaw([selected_table]);
    return true;
}

function insertDataTable(raw_table = true) {
    if (Q.fileFormatVersion() < 20.00) {
        let msg = 'Sorry, you must upgrade to a Q version >= 5.12.0 to use this feature.' +
                  'If you are unable to upgrade, you may instead use: ' +
                  '\'Create > Tables > Raw Data - Variables\'.';
        log(msg);
        return false;
    }
    let displayr = inDisplayr();
    let selected_variables = getAllUserSelections().selected_variables;
    let page = project.currentPage === undefined ? false : project.currentPage();
    if (!page) {
        if (!displayr)
            page = project.report;
        else {
            page = project.report.appendGroup();
            page.name = 'New page';
        }
    }

    let prefilled_controls = {};
    if (selected_variables.length > 0) {
        if (!raw_table) { // warn users that text variables are ignored if found
            let has_text_vars = selected_variables.some(v => v.question.questionType.includes('Text'));
            if (has_text_vars)
                log('Selected text variables have not been included in the output as the descriptive statistics ' +
                    'are not meaningful. Consider changing their type if appropriate.');
        }
        prefilled_controls['formVariables'] = selected_variables.map(v => v.guid).join(';');
    }

    let page_name = raw_table ? 'Tables - Raw Data - Variables' : 'Tables - Descriptive Statistics';
    let table = page.appendStandardR(page_name, prefilled_controls);

    if (Q.fileFormatVersion() > 8.65)
        project.report.setSelectedRaw([table]);
    return true;
}