Create a custom variable

This guide will walk you through how to create a custom variable template. When this variable is used, it will take an array of values and return them as a comma delimited string.

1. To begin your first variable template, click Templates in the left navigation and click the New button under the Variable Templates section.

2. In the Info tab, define the variable's Name and Description.

   Name is what will be presented to users when they go to implement this variable throughout the Tag Manager user interface.

   Description is just what it sounds like - a brief (200 characters or less) description of what this variable does.

3. Click Refresh to preview your template.

   To the right of the field inputs, there is a Template Preview window. Every time a change is made in the editor, the Refresh button will appear. Click Refresh to see what your changes do to the appearance of your variable.

4. Click Fields to add fields to your variable template.

   The Template Editor's Fields tab lets you create and edit fields in the variable template. Fields are used to enter custom data, such as an account ID. You can add the standard form elements like text fields, drop down menus, radio buttons, and checkboxes.

5. Click Add Field and select Simple table. Replace the default name (e.g. "simpleTable1") with "list". In the Template Preview, click Refresh.

   Repeat this step for a Text Input and call it "array", two Checkboxes called "use_array" and "sort", and a Text Input called "delimiter". For "delimiter", give it a default value of "," by clicking the gear icon, toggling "Default value" to on, and then filling in the new Default Value input field.

6. Click the Code tab and enter sandboxed JavaScript in the editor:

   var input = data.array;
   
   if (!data.use_array) {
     input = [];
     for (var i = 0; i < data.list.length; i++) {
       input.push(data.list[i].values);
     }
   }
   
   if (data.sort) {
     input.sort();
   }
   
   return input.join(data.delimiter || ',');
   

   The code for this variable is fairly straightforward, but there are a few things worth pointing out.

   • data fields.

     There are a few fields that are being accessed off of the data global. data will contain the values that you set up in the previous step. That's why we're able to access data.use_array, data.sort, data.list, and data.delimiter.

   • delimiter is set to a default value of "," if data.delimiter is not provided. It's a good practice to set default values for a field if one makes sense. This makes it easier for users to use the variable template, since they don't have to fill out every field in order to use the variable.

7. Click Save to save your progress. This will load any detected permissions into the Template Editor.

   Some Template APIs have permissions associated with them that dictate what they can or cannot do. When you use a template API such as sendPixel in your code, Tag Manager will show relevant permissions in the Permissions tab.

8. In the Template Preview tab, add some values for the "values" input, click Run Code, and look at the Console to see the output for your variable.

   If there are any errors, they will appear in the Console window.

9. Click Save, and close the Template Editor

   The variable template should now be ready for use.