In This Section

See more

Helper Functions

Listed below are helper functions that are available by default in Cordial Web Forms. 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.

Note: 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().

 

api.utils.copyToClipboard(elem)

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

Parameters:

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

Example:

api.utils.copyToClipboard(elem)
The text of the DOM element is copied to the user's clipboard
Note: 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:

  1. couponElement - Required. A DOM element object or a string containing a selector expression to match elements against.
  2. buttonSelector - Optional. A DOM element object that when clicked will copy the text in couponElement to the clipboard. Defaults to couponElement.
  3. 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.
  4. forcedTextToCopy - Optional. The text to copy to the clipboard instead of the text in couponElement.
  5. timeout - Optional. The interval between in which to copy
  6. copyMessage - Optional. Text to display when the copy action is complete.

Example:

api.utils.clickToCopy(couponElement,buttonSelector,forcedTextToCopy,timeout,copyMessage)
The text of the DOM element of couponElement is copied to the user's clipboard
Note: 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:

  1. timerData - Required. A timer data object.
    1. timerData.endDate - Required. A date object or a string value that can be converted to a date.
      timerData.cb - Required if timerData.message is not provided. A custom callback function that is passed the values for days,hours,mins, and secs. 
      timerData.message - Required if timerData.cb is not provided. 
               timerData.message.day -       Optional.
    2.             timerData.message.day.selector - Required if timerData.message.day is provided. The CSS/jQuery selector of the dom element in which to display the value for days remaining before timerData.endDate is reached.
    3.             timerData.message.day.text - Optional.  If a value is provided it must include "##" to serve as the placeholder text for the days value.
               timerData.message.hour -       Optional.
    4.             timerData.message.hour.selector - Required if timerData.message.hour is provided. The CSS/jQuery selector of the dom element in which to display the hours remaining before timerData.endDate is reached.
      1.  timerData.message.hour.text - Optional. If a value is provided it must include '##' as the placeholder text for the hours value.
      2.     timerData.message.minute - Optional. 
      3.        timerData.message.minute.selector - Required if timerData.message.minute is provided. The CSS/jQuery selector of the dom element in which to display the value for minutes remaining before timerData.endDate is reached. 
      4.         timerData.message.minute.text -  Optional. If a value is provided it must include "##" as the placeholder text for the minutes value. 
      5.         timerData.message.second - Optional. 
      6.         timerData.message.second.selector - Required if timerData.message.second is provided. The CSS/jQuery selector of the dom element in which to display the value for seconds remaining before timerData.endDate is reached.
      7.         timerData.message.second.text - Optional. If a value is provided it must include "##" as the placeholder text for the seconds value. 
      8.          timerData.message.general - Optional.   
        1. timerData.message.general.selector - Required if timerData.message.general is provided. The CSS/jQuery selector of the dom element in which to display the date time value of the timerData object.  
        2. timerData.message.general.text - Required if timerData.message.general is provided. The replacement text should include %D for timerData.message.days, %HH for timerData.message.hour, %MM for timerData.message.minute, and %SS for timerData.message.second. 
      9.         timerData.message.timerExpired - Optional. An object to store a dom selector and message to display when the countdown timer has reached timerData.message.timerExpired. 
      10.             timerData.message.timerExpired.selector - Required if timerData.message.timerExpired is provided. The dom element in which to display the value for timerData.message.timerExpired.message. 
      11.             timerData.message.timerExpired.message - Required if timerData.message.timerExpired is provided. The text to display when the countdown timer has reached timerData.endDate. 
      12.          timerData.message.timerExpiredCB -  Optional. A callback function to run when timerData.endDate has been reached. 


    Note: This function is useful for promoting time sensitive events.

    api.utils.getCookie(cookie)

    Purpose: Access a cookie's value 

    Parameters:

    1. cookie - Required. The name of the cookie.

    Example:

     

    Notes: 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:

    1. name - Required. The name of the query string parameter.

    Example:

    url = www.example.com?my_param=123
    api.utils.getQueryStringParam('my_param')
    123
    Note: 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:

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

    Example:

    api.utils.getRootLevelDomain('shop.example.com')
    example.com
    Note:

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

    Purpose: Make a GET request to an http endpoint

    Parameters:

    1. url - Required. The url of the http endpoint.
    2. async - Optional. True or false value to indicate whether the request should be made asynchronously. The default value is false.

    Example:

    api.utils.httpGet(theUrl,async)
    The response data from the http endpoint is returned as a string value
    Note: 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:

    1. 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. 
    2. email - Optional . The email address of the subscriber. If this argument is omitted the email field in the lightbox form is used.
    3. contactData -Optional . A contact data object. This object is used to create or update a contact's attributes within Cordial.
    4. eventData -Optional . Additional properties of the "lightbox_submitted" event.

    Example:

    //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
    Note:  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:

    1. obj - Required. A JavaScript object.

    Example:

    let obj = {"name": "Fred", "Occupation": null, "Age": ""}; 
    api.utils.removeEmptyKeys(obj)
    {"name": "Fred"}
    Note: 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:

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

    Example:

    api.utils.removeRule('my_id_value')
    The hidden div element with a value of "my_id_value" is removed from the web page
    Note: 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:

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

    Example:

    Note: 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:

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

    Example:

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

    1. var - Required. The name of a JavaScript variable.

    Example:

    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
    Note: 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:

    1. email - Required. The email address to validate.

    Example:

    api.utils.validateEmail('george@example.com')
    true
    Note: 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:

    1. test - Required. The function to call.
    2. run - Required. The callback function. The callback function is passed test and run as arguments. 
    3. sleep - Optional. The interval between attempts measured in milliseconds. The default value is 100 milliseconds, 1/10 of a second. 
    4. 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. 

    Example:

    api.utils.when(test, run, sleep, maxAttempts)
     
    Note: This function is helpful when you need to repeatedly test a function.

Related articles

Comments

0 comments

Please sign in to leave a comment.