Overview

Sales events and discount coupons are frequently advertised on webform widgets. You can incentivize your website visitors to participate in a time sensitive opportunity by creating a countdown timer that displays the amount of time remaining before the offer expires. A countdown timer is a specialized type of clock that measures time intervals. The CreateTimer Helper Function assists you with creating countdown timers that appear on your lightboxes. 

Contact your Client Success Manager to get started with webforms.

api.utils.createTimer

The following sections explain how to construct the object argument for the api.utils.createTimer function as well as how to configure the DOM elements of a countdown timer within the lightbox editor.

timerData object

The api.utils.createTimer function takes a single argument of type object. For the purposes of this article, the object is given the name timerData, but the name you provide for the argument can be any valid JavaScript identifier.  The timerData object must include an endDate property.  Other properties may be optional or required depending on how the timerData object is configured.  Here is an example of the timerData object being declared within a JavaScript(Boxes) code snippet.

timerData.endDate

The timerData object must have an endDate property. If the endDate property is not present, an error notice will be returned when the api.utils.createTimer function is invoked. The value of the endDate property is used by the api.utils.createTimer function to determine the amount of time that should be displayed.  The value of the endDate property is usually set to the date and time a sales or discount offer expires. Here is an example of a Custom JavaScript(Boxes) code snippet that creates an endDate value of December 31st, 2019 11:59 pm based on the user's timezone.

The endDate value can also be a string that JavaScript can convert to a date.

timerData.message

A typical timerData object configuration contains a message property.  The message property stores the DOM elements that are used to display the days, hours, minutes, and seconds values of the countdown timer. If the endDate value of the timerData object is longer than 24 hours, it makes logical sense to include a days property in the message object. Whether to include the additional DOM elements within the message property is up to you. For example, many configurations only include message properties for days, hours and minutes.  The message property can also include a property called "general" that corresponds with a DOM element that displays the entire value of the countdown timer. Here is an example of the message object be declared within a Custom JavaScript(Boxes) code snippet.

message.[TIME-ELEMENT].selector

Every unit of time that is displayed in the countdown timer must have a selector property. For example, if you are displaying the "days" time unit, there should be a message.day.selector property set in your custom JavaScript code. The value of the message.day.selector should be set to the css class identifier of the DOM element. For instance, a commonly used value for the message.day.selector is ".days". 

message.[TIME-ELEMENT].text

The text property of message.[TIME-ELEMENT] is optional. If no value is provided the createrTimer function will attempt to take the value from the corresponding DOM element. If there is no value in the DOM element, the value of message.[TIME-ELEMENT].text will be set to "##" so that the replacement can occur. The value of the text property should contain the characters "##". These characters are used as replacement characters for the time values of the countdown timer. For example, the text element of the Hours time element might be set to "H ##" while the minute and second time elements are set to "M ##" and "S ##".

timerData.cb

The timerData object may be supplied with a property named "cb". "cb" stands for "callback" and the value of this property should be set to the name of a custom function that you create.  The callback function is responsible for populating the time element values of the countdown timer. This option is useful if you are looking to add animated effects to a countdown timer.

Create DOM Elements within the lightbox editor

Within the webform's interface you can use the Text element options to create DOM elements to display the values for days, hours, minutes, and seconds. The text value for the element should be set to "##" or to an empty string. 

Within the Metadata section the Key should be set to "class" and the Value set to something that indicates which time element portion is being displayed.  For example, if the element is displaying "hours" the value should be something like "hours" or "hour". Technically, the value can be anything as long as it matches up with the code in your custom JavaScript.  

message.general

Rather than displaying the time units of the countdown timer in individual DOM elements, the entire time value can be displayed in a single DOM element. You utilize the message property general to achieve this. The format for the general property is similar to how the days, hours, minutes, and second elements are formatted. The class value in the metadata section should match what is being referenced in the Custom JS section. 

The following format strings can be used to display the time units of the countdown timer. 

• %D - Days
• %HH - Hours
• %MM - Minutes
• %SS - Seconds

The text of the general property can be defined within the JavaScript snippet. This is done using the message.general.text property.

Or the text can be added to the general text element within the lightbox editor.