Skip to content
ggLowCodeGTMKit

assignParamsToString — GTM Variable Template for String

VARIABLES › STRING
assignParamsToString CORE String
Direct (.tpl) Apply (.tpl)

Assigns or replaces parameters in a query or fragment string. In default mode, only adds missing parameters. In overwrite mode, replaces existing parameters with new values.

When to Use This

String Manipulation

Transform, clean, and normalize text data for consistent downstream processing.

URL Processing

Parse, build, decode, and manipulate URLs and query parameters.

Examples

Add missing parameters
INPUT
Parameter String: ?page=home
Parameters to Assign: [{key: "utm_source", val: "website"}, {key: "utm_medium", val: "organic"}]
Case-Insensitive Matching: false
OUTPUT
?page=home&utm_source=website&utm_medium=organic
Build from empty string
INPUT
Parameter String: ?
Parameters to Assign: [{key: "utm_source", val: "website"}, {key: "utm_medium", val: "organic"}]
Case-Insensitive Matching: false
OUTPUT
?utm_source=website&utm_medium=organic

GTM Configuration

This is what you'll see when you open this variable in Google Tag Manager. Hover the icons for details.

Read-only Preview
assignParamsToString
Parameter String
Assigns or replaces parameters in a query or fragment string. In default mode, only adds missing parameters. In overwrite mode, replaces existing parameters with new values.
Parameters to Assign
📋 Parameters to add or replace in the string. Behavior depends on the Overwrite Mode setting below.

*** Add missing parameters***

*** Build from empty string***
Parameter NameParameter Value
⊖
⊖
☑️ If enabled, replaces existing parameters with new values. If disabled, only adds parameters that don't already exist (default behavior).
☑️ If enabled, parameter name comparison will ignore letter casing (e.g. utm_source = UTM_SOURCE).
Input Setup
Input Function (optional)
⚙️ Optional pre-processing function applied to the parameter string before processing (e.g., normalize case, clean URL).
Result Handling
Output Function (optional)
⚙️ Optional function to apply to the result string before returning it (e.g., str => str.toUpperCase(), str => encodeURIComponent(str)). Useful for chaining transformations on the output.

Related Variables

Same category: String

→ charAt → concatenateValues → countWordsInString → endsWith → extract → extractFirstSegment → extractNumber → fromBase64 → indexOf → left → matchAll → matchRegex → omitParamsFromString → padEnd → padStart → pickParamsFromString → replaceAll → replaceAllWithRegex → replaceFirst → right → safeSplit → sanitizeTextAndRemoveHtml → sanitizeTextLite → search → slice → split → startsWith → test → toBase64 → toCamelCase → toJsonString → toKebabCase → toLocaleLowerCase → toLocaleUpperCase → toLowerCase → toNumber → toSnakeCase → toStartCase → toString → toStringRepresentation → toUpperCase → toUpperFirst → trim → trimEnd → trimStart → truncate

Under the Hood

📜 View Implementation Code
/**
 * Assigns or replaces parameters in a query or fragment string.
 * 
 * @param {string} data.src - A string starting with "?" or "#" (e.g. "?a=1&b=2").
 * @param {Array<Object>} data.prm - Array of objects with key and val properties.
 * @param {boolean} data.ovr - If true, replaces existing params; if false, only adds missing ones.
 * @param {boolean} data.cas - Optional flag to enable case-insensitive matching.
 * @param {Function|string} [data.out] - Optional output handler.
 *
 * Direct-mode specific parameters:
 * @param {Function} [data.pre] - Optional pre-processor function.
 * 
 * @returns {string} The resulting query string with parameters updated or added.
 *
 * @framework ggLowCodeGTMKit
 */
const decodeUriComponent = require('decodeUriComponent');
const encodeUriComponent = require('encodeUriComponent');
const makeTableMap = require('makeTableMap');

const assignParamsToString = function(input, params, overwrite, caseInsensitive) {
    const inputStr = input || '';
    const paramsObj = params || {};
    const shouldOverwrite = !!overwrite;
    const caseSensitive = !!caseInsensitive;
    
    const hasPrefix = inputStr.charAt(0) === '?' || inputStr.charAt(0) === '#';
    const prefix = hasPrefix ? inputStr.charAt(0) : '';
    const raw = hasPrefix ? inputStr.slice(1) : inputStr;
    const existingParams = {};
    const pairs = raw ? raw.split('&') : [];
    
    for (let i = 0; i < pairs.length; i++) {
        const pair = pairs[i];
        if (!pair) continue;
        const eqIndex = pair.indexOf('=');
        const key = eqIndex >= 0 ? pair.slice(0, eqIndex) : pair;
        const lookupKey = caseSensitive ? key.toLowerCase() : key;
        existingParams[lookupKey] = true;
    }
    
    const resultPairs = shouldOverwrite ? [] : pairs.slice();
    
    for (let key in paramsObj) {
        if (paramsObj.hasOwnProperty(key)) {
            const lookupKey = caseSensitive ? key.toLowerCase() : key;
            if (!existingParams[lookupKey] || shouldOverwrite) {
                const encodedKey = encodeUriComponent(key);
                const encodedVal = encodeUriComponent(paramsObj[key] || '');
                resultPairs.push(encodedKey + '=' + encodedVal);
            }
        }
    }
    
    const result = resultPairs.join('&');
    return result ? (prefix + result) : prefix;
};
const safeFunction = fn => typeof fn === 'function' ? fn : x => x;
const out = safeFunction(data.out);
// ===============================================================================
// assignParamsToString - Direct mode
// ===============================================================================
const applyCast = (castFn, value) => safeFunction(castFn)(value);
const value = applyCast(data.pre, data.src);
const paramsObj = makeTableMap(data.prm, 'key', 'val');
return out(assignParamsToString(value, paramsObj, data.ovr, data.cas));
// ===============================================================================
// assignParamsToString(...)
🧪 View Test Scenarios (6 tests)
✅ '[example] Add missing parameters'
✅ Test with existing parameters - should not add duplicates
✅ Test with case-insensitive matching
✅ Test with fragment string (# prefix)
✅ '[example] Build from empty string'
✅ Test with special characters requiring encoding