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

⊖

⊖

Add Row

Overwrite Mode

☑️ If enabled, replaces existing parameters with new values. If disabled, only adds parameters that don't already exist (default behavior).

Case-Insensitive Matching

☑️ 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