How can we help?

Search

Helper functions

Overview

Listed below are Web Forms helper functions that are available by default. They are useful for accomplishing common tasks that arise when working with lightboxes. These helper functions can be utilized within the JavaScript Parent and JavaScript Box sections.

To invoke a helper function outside of Parent and Custom JS, the namespace "api" should be replaced with "PRIMER_API". For example, to set a cookie within the JS console, the function call is PRIMER_API.utils.setCookie().

Helper functions

api.utils.copyToClipboard(elem)

Purpose: Copy the contents of a DOM element to the clipboard

Parameters: elem - Required. A DOM element object or the id of a DOM element.

  • api.utils.copyToClipboard(elem)
  • The text of the DOM element is copied to the user's clipboard

This function can be used with coupons.

api.utils.clickToCopy(couponElement,[buttonSelector = couponElement,forcedTextToCopy = null,timeout = 1000,copyMessage = "Copied"])

Purpose: Copy the contents of a DOM element to the clipboard

Parameters:

  • couponElement - Required. A DOM element object or a string containing a selector expression to match elements against.
  • buttonSelector - Optional. A DOM element object that when clicked will copy the text in couponElement to the clipboard. Defaults to couponElement.
  • buttonSelector - Optional. A DOM element object or a string containing the selector of a DOM element that when clicked will copy the text in couponElement to the clipboard. Defaults to couponElement.
  • forcedTextToCopy - Optional. The text to copy to the clipboard instead of the text in couponElement.
  • timeout - Optional. The interval between in which to copy
  • copyMessage - Optional. Text to display when the copy action is complete.
  • api.utils.clickToCopy(couponElement,buttonSelector,forcedTextToCopy,timeout,copyMessage)
  • The text of the DOM element of couponElement is copied to the user's clipboard

This function can be used with coupons.

createTimer(timerData)

Purpose: Create a countdown timer that displays the amount of time remaining before the provided end date is reached. 

Parameters: timerData - Required. A timer data object.

This function is useful for promoting time sensitive events. This function is discussed in detail here: Create Timer Function 

api.utils.getCookie(cookie)

Purpose: Access a cookie's value 

Parameters: cookie - Required. The name of the cookie.

  • api.utils.getCookie('_ga')
  • GA1.2.151198680.1565803792

This function is often used in conjunction with api.utils.setCookie().

api.utils.getQueryStringParam(name)

Purpose: Access the value of a query string parameter

Parameters: name - Required. The name of the query string parameter.

  • url = www.example.com?my_param=123
    api.utils.getQueryStringParam('my_param')
  • 123

The value of the query string parameter is url decoded before being returned. 

api.utils.getRootDomain([domain = location.hostname])

Purpose: Access the root domain

Parameters: url - Optional. A domain. If the domain argument is not provided, location.hostname is used.

  • api.utils.getRootLevelDomain('shop.example.com')
  • example.com

api.utils.httpGet(url,[async =false])

Purpose: Make a GET request to an http endpoint

Parameters:

  • url - Required. The url of the http endpoint.
  • async - Optional. True or false value to indicate whether the request should be made asynchronously. The default value is false.
  • api.utils.httpGet(theUrl,async)
  • The response data from the http endpoint is returned as a string value

Only the http GET method is supported by this function.

api.utils.pushEmail(s,email,contactData,eventData)

Purpose: Import an event into Cordial called "lightbox_submitted"

Parameters:

  • s - Optional. The standard Web Forms object. When this argument is passed it allows for the data points lightbox short id, variation short id, ab test short id, lightbox name, lightbox variation name, ab test name, user guid, and client guid to be recorded within the "lightbox_submitted" event. Some of these data points may have null values depending on the lightbox configuration. These null values are removed before the "lightbox_submitted" event is imported into Cordial. 
  • email - Optional . The email address of the subscriber. If this argument is omitted the email field in the lightbox form is used.
  • contactData -Optional . A contact data object. This object is used to create or update a contact's attributes within Cordial.
  • eventData -Optional . Additional properties of the "lightbox_submitted" event.
  • //Capture email address submitted in form
    // x is the form data object. Read more here https://support.cordial.com/hc/en-us/articles/360024573472#x 
    var email = x.email;

    //Define contactData object
    var contactData = {};

    //Subscribe the contact
    contactData.channels = {};
    contactData.channels.email = {};
    contactData.channels.email.subscribeStatus = "subscribed";
    contactData.channels.email.address = email;

    //Add contact to the "welcome" list
    contactData.welcome = true;

    //Remove contact from the "test" list
    contactData.test = false;

    //Update a contact attribute
    contactData.signup_source = "Web Forms";

    //Define eventData to pass additional data to the "lightbox_submitted" event
    var eventData = {};

    //Pass the coupon code and offer text from the lightbox to the email message for consistent messaging.
    eventData.coupon_code = "FREESHIPPING";
    eventData.offer_text = "Get Free Shipping off of your first order!";

    api.utils.pushEmail(s,email,contactData,eventData)
  • An event called "lightbox_submitted" is imported into Cordial

Unauthenticated modification should be set to true for attributes used by this function (read more). Additionally, attribute keys and lists defined in the contactData object must exist or the entire request will be ignored and dropped.  In the example above, you must have a list named welcome and test. You must also have a contact attribute key of signup_source.  Data that you add to eventData object doesn't need to be predefined.  Once a signup from Web Forms comes in with new event data, that attribute is available in conditional properties for audience searching as well as accessible via SMARTY.

api.utils.removeEmptyKeys(obj)

Purpose: Remove the keys from a JavaScript object that contain empty or null values

Parameters: obj - Required. A JavaScript object.

  • let obj = {"name": "Fred", "Occupation": null, "Age": ""}; 
    api.utils.removeEmptyKeys(obj)
  • {"name": "Fred"}

This function is used internally by the api.utils.pushEmail() function so that event data points with null and empty values and not imported into Cordial.

api.utils.removeRule(id)

Purpose: Remove a hidden div element by id

Parameters: id -Required. The id of the hidden div element that is to be removed.

  • api.utils.removeRule('my_id_value')
  • The hidden div element with a value of "my_id_value" is removed from the web page

This function can be used in conjuction with the api.utils.setRule() function.

api.utils.setCookie(name, value, exdays, domain)

Purpose: Set a cookie

Parameters:

  • name - Required. The name of the cookie to set.
  • value - Required. The value of the cookie.
  • exdays - Optional. The number of days until the cookie expires.
  • domain -Optional. The domain that the cookie is available to.

Example:

  • api.utils.setCookie('my_cookie', 'value')
  • Cookies is set with the name my_cookie

This function can be used in conjunction with the api.utils.getCookie() function.

api.utils.setRule(id)

Purpose: Create a hidden div element with a specified id

Parameters: id - Required. The value of the id attribute for the hidden div element.

  • api.utils.setRule('my_id_value')
  • <div id="my_id_value" webforms="webforms_rule"  style="text-align:left;display:none;padding-left:20px"></div>

This function can be used with the HTML Exists jQuery lightbox condition.

api.utils.typeOf(var)

Purpose: Find the type of a JavaScript variable

Parameters: var - Required. The name of a JavaScript variable.

  • var my_object = {}; 
    api.utils.typeOf(my_object);

    var my_array = [];
    api.utils.typeOf(my_array);

    var my_null = null;
    api.utils.typeOf(my_null);

    var my_date = new Date();
    api.utils.typeOf(my_date);
  • object
    array
    null
    date

This function will return the actual object type such as array rather than just object.

api.utils.validateEmail(email)

Purpose: Validate an email address

Parameters: email - Required. The email address to validate.

  • api.utils.validateEmail('george@example.com')
  • true

The regular expression used is /^(([^<>()\[\]\.,;:\s@\"]+(\.[^<>()\[\]\.,;:\s@\"]+)*)|(\".+\"))@(([^<>()[\]\.,;:\s@\"]+\.)+[^<>()[\]\.,;:\s@\"]{2,})$/i

api.utils.when(test, run, sleep, maxAttempts)

Purpose: Call a function a maximum number of times at a specified interval until it is successful or the maximum number of attempts has been reached.

Parameters:

  • test - Required. The function to call.
  • run - Required. The callback function. The callback function is passed test and run as arguments. 
  • sleep - Optional. The interval between attempts measured in milliseconds. The default value is 100 milliseconds, 1/10 of a second. 
  • maxAttempts - Optional. Maximum number of attempts to try the function. If this argument is omitted the function test is called indefinitely until it is successful. 
  • api.utils.when(test, run, sleep, maxAttempts)
  • > 
     

This function is helpful when you need to repeatedly test a function.

Comments

0 comments

Please sign in to leave a comment.