Date functions

A number of global functions are available to facilitate dynamic date scripting for the browser agents. These functions are available in both the Target Window and the control scopes.

To properly import the date library, make the following call within the custom JavaScript code before using the date functions:

 gomezDate.init();

Only the following global functions work on the browser when called from a GSLv2 script:

  • gomezDate.addMonths

  • gomezDate.addDays

  • gomezDate.addWeeks

  • gomezDate.getNextWeekday

  • gomezDate.printDate

  • gomezDate.selectMonthByIndex

  • gomezDate.setDate

  • gomezDate.today

Date math

gomezDate.today()

This returns a date object representing the current day, the (same as new Date()).

gomezDate.addDays(<date>, <numDays>)

This returns a date object <numDays> later than <date>.

For example, to create an end date three days from now:

var startDate = gomezDate.today();
var endDate = gomezDate.addDays(startDate, 3);

gomezDate.addMonths(<date>, <numMonths>)

This returns a date object <numMonths> later than <date>.

Note that gomezDate.addMonths() only increments the months counter. Therefore, adding one month to March 5, 2014 yields April 5, 2014.

This is only tricky when the new date is illegal for the new month. For example, adding a month to January 31, 2014 cannot create an illegal February 31st date. In this case, any days that do not fit are extended into the next month. This behavior is JavaScript-dependen. For example:

 1/31/2014 + 1 month = 3/3/2014

There are 31 days in January, so the method increments the date by 31 days: 28 days in February plus 3 days into March.

However:

 1/31/2016 + 1 month = 3/2/2016

Because of the leap day, occurring every four years, February 2016 will have 29 days, so “one month” (31 days) extends only 2 days into March.

gomezDate.addWeeks(<date>, <numWeeks>)

This returns a date object <numWeeks> ahead of <date>.

gomezDate.getNextWeekday(<date>, <targetWeekday>)

This returns a date object representing the next instance of the given weekday.

Constants have been created for every weekday: gomezDate.SUNDAY, gomezDate.MONDAY, etc.

For example, to create dates for a trip starting on the next Wednesday and lasting until the following Sunday:

var start = gomezDate.getNextWeekday(gomezDate.today(), gomezDate.WEDNESDAY);
var end = gomezDate.getNextWeekday(start, gomezDate.SUNDAY);

Date formatting

gomezDate.printDate(<date>[, <separator>][, <type>][, custom])

Given a date, this returns a string representing the date. The default representation is MM/DD/YY; for example, September 5, 2014 is formatted as 09/05/14.

You can override the default format to provide a different separator, suppress leading 0's, return the date in European ordering, and return a four-digit year. Using the custom field, you can handle any date rearrangement (for example, in Japan, the date is often reported as YYMMDD).

Providing a value for <separator> changes the separator used between date parts.

The <type> can be any of the following values, using September 5, 2017 as the example date. Note that you do not need to specify a separator to use the default separator, a slash ( / ).

  • MDYYYY = 9/5/2017

  • MDYY = 9/5/17

  • MMDDYY = 09/05/17

  • MMDDYYYY = 09/05/2017

  • DMYYYY = 5/9/2017

  • DMYY = 5/9/17

  • DDMMYY = 05/09/17

  • DDMMYYYY = 05/09/2017

  • CUSTOM – Build your own using M, MM, D, DD, YY, YYYY, S (for Separator), plus any custom string placed into a JavaScript array. The following examples are based on the date March 5, 2017:

    var date = new Date("March 5, 2017 00:00:00");
    
    • Return the default format, 03/05/17:

      var ex31 = gomezDate.printDate(date);
      
    • Return 03.05.17:

      var ex32 = gomezDate.printDate(date, '.');
      
    • Return 3.5.2017:

      var ex33 = gomezDate.printDate(date, '.', 'MDYYYY');
      
    • Return the following (the code is a single line): 2017 was a great year, especially 3/5.

      var ex34 = gomezDate.printDate(date, '/', 'custom', ['YYYY', ' was a great year. Especially ', 'M', 'S', 'D', '.']);
      

Dates using SELECT elements

These functions are used for cases where a date is entered not as text, but as a set of SELECT elements (presumably one for month, one for date, and one for year).

gomezDate.setDate(<date>, <monthSelect>, <dateSelect>, <yearSelect>)

This is the basic function. It takes a date: three combo boxes, one each for the month, date, and year. It tries the month as the numeric value (for example, 3), and as a case-insensitive three-letter prefix (for example, mar, that matches March or Mar). It only tries the date by numeric value. It tries the year as both a four-digit year and a two-digit year (for example, either 14 or 2014).

If the date provided is invalid, a SELECT is invalid, or the value cannot be found, the function aborts by executing null.die, which does nothing on Firefox, but causes IE to throw a TypeError that stops user script execution.

In the following example, the date is September 1, 2014:

<SELECT id="month"><OPTION value="1">September</OPTION>…</SELECT>
<SELECT id="date"><OPTION value="1">1</OPTION>…</SELECT>
<SELECT id="year"><OPTION value="2014">2014</OPTION>…</SELECT>
gomezDate.setDate(date, document.getElementById('month'),
document.getElementById('date'),
document.getElementById('year'));

You may need to set fields individually; non-English sites would be the likeliest reason for this. Date and year are generally safe, but the month can be tricky. Rather than trying to provide translation tables for multiple languages, there is an index-based function available.

gomezDate.selectMonthByIndex(<date>, <monthSelect>[, offset])

Use the optional offset to index past header entries in the object list, such as:

--- select the month --- <SELECT id="month">
<OPTION value="---">--- select a month ---</OPTION>
<OPTION value="1">Janvier</OPTION>
…
<OPTION value="12">Décembre</OPTION>
</SELECT>
gomezDate.selectMonthByIndex(date,document.getElementById("month"),1);