Data Handling & URL Parameters

Forsta HX Platform - API Scripting Guide

Data Handling & URL Parameters

⚠️ Euro SaaS Platform Note

Data submission is handled automatically by the Forsta HX Platform. Do not use custom AJAX calls for survey submission. Use the platform's built-in data collection and export features.

Read URL Parameters (Supported):

/**
 * getUrlParameter - Extracts a parameter value from the URL query string
 * @param {string} name - The name of the URL parameter to retrieve
 * @returns {string|null} - The decoded parameter value, or null if not found
 * @description Uses regex to find the parameter in the URL.
 *              Handles both ? (first param) and & (subsequent params) prefixes.
 *              Decodes URI-encoded characters (e.g., %20 → space).
 *              Example: getUrlParameter('rid') from '?rid=123&source=email'
 */
function getUrlParameter(name) {
    // Regex matches ?name= or &name= followed by value (stops at & or #)
    var results = new RegExp('[?&]' + name + '=([^&#]*)')
        .exec(window.location.href);
    // If found, decode the value; otherwise return null
    return results ? decodeURIComponent(results[1]) : null;
}

// Pre-populate fields from URL parameters
$(document).ready(function() {
    var respondentId = getUrlParameter('rid');
    var source = getUrlParameter('source');
    
    // Set values using Forsta methods
    if (respondentId) {
        f('RespondentID').set(respondentId);
    }
    if (source) {
        f('SourceCode').set(source);
    }
});

Working with Hidden Fields:

// Store calculated values in hidden fields for data export
$(document).ready(function() {
    // Calculate and store a derived value
    var total = 0;
    var codes = f('SpendQ').domainValues();
    
    codes.forEach(function(code) {
        if (f('SpendQ').item(code).toBoolean()) {
            total += f('SpendQ').item(code).toNumber();
        }
    });
    
    // Store in hidden field for export
    f('CalculatedTotal').set(total);
    
    // Store timestamp
    f('CompletionTime').set(new Date().toISOString());
});

Cross-Question Data Transfer:

/**
 * transferData - Copies values from source questions to destination questions
 * @description Checks if source question has a value using .toBoolean(),
 *              then copies and optionally transforms the value to one or more
 *              destination questions. Useful for piping and data duplication.
 */
function transferData() {
    // Check if PatientName has a value before attempting to read it
    if (f('PatientName').toBoolean()) {
        // Get the value as a string using Forsta's .toString() method
        var name = f('PatientName').toString();
        
        // Set to destination question(s)
        f('ConfirmName').set(name);
        f('DisplayName').set(name.toUpperCase());
    }
}

// Trigger on page load or question change
$(document).ready(transferData);
f('PatientName').on('change', transferData);