Quick Reference Cheat Sheet

Forsta HX Platform - API Scripting Guide

Quick Reference Cheat Sheet

⭐ Standard Forsta API Methods - Use These First

Task Forsta Method (Recommended) Alternative (jQuery)
Get value f('AQ1').get() f('AQ1').val()
Set value f('AQ1').set('5') f('AQ1').val('5')
Check if field has value f('userid').toBoolean() ⭐ f('userid').val() != ''
Check if option selected f('BQ1').item('1').toBoolean() ⭐ f('BQ1').find('[value="1"]').is(':checked')
Convert to string f('userid').toString() ⭐ String(f('userid').val())
Get numeric value f('AQ1').item('1').toNumber() ⭐ parseInt(f('AQ1').val())
Get all options f('BQ1').domainValues() ⭐ f('BQ1').find('input').map(...)
Loop selected items codes.forEach(...) ⭐ f('BQ1').find(':checked').each(...)

⭐ = Forsta-only feature - cleaner and more reliable

1. Calculate Sum from Selected Checkboxes (Standard):

// Sum numeric values from selected checkboxes - USE THIS PATTERN
var total = 0; // Initialize sum to zero

// Get array of all possible option codes for this question
var codes = f('BQ4c').domainValues();

// Loop through each option code
for (var i = 0; i < codes.length; i++) {
    // Check if this specific option is currently selected
    if (f('BQ4c').item(codes[i]).toBoolean()) {
        // If selected, get its numeric value and add to total
        total = total + f('BQ4c').item(codes[i]).toNumber();
    }
}

// Set the calculated total to the TotalSpend question
f('TotalSpend').set(total);

2. Check Specific Option Selected:

// Check if option "3" is selected - Forsta method
// .item('3') accesses option with code "3"
// .toBoolean() returns true if selected
if (f('AQ1').item('3').toBoolean()) {
    f('AQ1a').show(); // Show follow-up question (jQuery)
} else {
    f('AQ1a').hide(); // Hide follow-up (jQuery)
}

3. Count Selected Items:

// Count how many checkboxes are selected - Forsta method
var count = 0; // Initialize counter

// Get all option codes for this question
var codes = f('BQ2').domainValues();

// Loop through each code using forEach
codes.forEach(function(code) {
    // Check if this option is selected
    if (f('BQ2').item(code).toBoolean()) {
        count++; // Increment counter
    }
});

// Save the count to another question
f('SelectedCount').set(count);

4. Get and Set Values:

// Use Forsta methods for get/set
var userAge = f('AQ1').get(); // Get the current value
var calculatedValue = parseInt(userAge) * 2; // Convert to int and double it

// Set the calculated value to another question
f('DoubleAge').set(calculatedValue);

5. Loop Through All Options:

// Process all possible values - Forsta method
var codes = f('CQ1').domainValues(); // Get all option codes

// Loop through each code
codes.forEach(function(code) {
    // Check if this option is selected
    if (f('CQ1').item(code).toBoolean()) {
        // Get the numeric value for this option
        var value = f('CQ1').item(code).toNumber();
        console.log('Code ' + code + ' = ' + value);
    }
});

6. Validate Selection Range:

// Ensure 2-5 selections - Forsta method
function validateRange() {
    var codes = f('DQ1').domainValues(); // Get all option codes
    var count = 0; // Initialize counter
    
    // Count how many options are selected
    codes.forEach(function(code) {
        if (f('DQ1').item(code).toBoolean()) {
            count++; // Increment if selected
        }
    });
    
    // Check if count is in valid range
    if (count < 2 || count > 5) {
        alert('Select 2-5 options');
        return false; // Validation failed
    }
    return true; // Validation passed
}

7. Show/Hide with jQuery (DOM manipulation):

// Use jQuery for show/hide - this is appropriate
f('AQ1').on('change', function() {
    var value = f('AQ1').get(); // Get with Forsta
    
    if (value == '1') {
        f('BQ1').show(); // Show with jQuery
    } else {
        f('BQ1').hide(); // Hide with jQuery
    }
});

8. Calculate Average Rating:

// Calculate average from selected ratings - Forsta method
var codes = f('RatingQ').domainValues();
var sum = 0;
var count = 0;

for (var i = 0; i < codes.length; i++) {
    if (f('RatingQ').item(codes[i]).toBoolean()) {
        sum += f('RatingQ').item(codes[i]).toNumber();
        count++;
    }
}

var average = count > 0 ? (sum / count).toFixed(2) : 0;
f('AverageRating').set(average);

9. Check if Field Has Value:

// Use .toBoolean() to check if field exists/has value
if (f('userid').toBoolean()) {
    console.log('User ID exists');
    var userID = f('userid').toString();
    console.log('User ID: ' + userID);
} else {
    console.log('No user ID found');
}

10. Convert to String and Format:

// Get value as string and manipulate
if (f('username').toBoolean()) {
    var name = f('username').toString().toLowerCase();
    var formatted = name + '@company.com';
    f('EmailAddress').set(formatted);
}

11. Loop Through Grid and Set Row Values:

// Set values for each row in a grid/loop question
var rows = f('PatientGrid').domainValues();

for (var i = 0; i < rows.length; i++) {
    var rowID = 'Patient-' + rows[i];
    f('PatientGrid').item(rows[i]).set(rowID);
}

12. Test vs Production Logic:

// Different behavior for test environment
if (isTestID()) {
    f('TestField').set('TEST-DATA');
} else {
    var realValue = calculateRealValue();
    f('TestField').set(realValue);
}