Date, date/time and time functions

  • date()
  • dateLong()
  • dateMedium()
  • dateShort()
  • dateTime()
  • dateTimeLong()
  • dateTimeMedium()
  • dateTimeShort()
  • time()
  • timeLong()
  • timeMedium()
  • timeShort()
The locale also influences the output of the different Date functions; see Locale.
To format a date from a date field in the record set, you can enter a custom pattern via the Text Script Wizard; see Using the Text Script Wizard, Formatting variable data and Date and time patterns).

date(value, pattern)

Formats a date object using a custom pattern.

value

A Date object. A Date can contain a date and time.

pattern

String. The custom pattern may consist of pattern letters, separating symbols and quoted text, for example: "MMMM dd, yyyy"; see Date and time patterns. Note that the repetition of pattern letters determines the exact presentation.

dateLong(value)

Formats a date as long string representation, for example April 1, 2016.

value

A Date object. A Date can contain a date and time.

dateMedium(value)

Formats a date as medium string representation, for example 01/04/16.

value

A Date object. A Date can contain a date and time.

dateShort(value)

Formats a date as short string representation, for example 1-Apr-2016.

value

A Date object. A Date can contain a date and time.

dateTime(value, pattern)

Formats a date and time object using a custom pattern.

value

A Date object. A Date can contain a date and time.

pattern

String. The custom pattern may consist of pattern letters, separating symbols and quoted text, for example: "yyyy.MM.dd G 'at' HH:mm:ss z"; see Date and time patterns. Note that the repetition of pattern letters determines the exact presentation.

dateTimeLong(value)

Formats a date and time as long string representation, for example April 1, 2016 12:00:00 EDT AM.

value

A Date object. A Date can contain a date and time.

dateTimeMedium(value)

Formats a date and time as medium string representation, for example 1-Apr-2016 12:00:00 AM.

value

A Date object. A Date can contain a date and time.

dateTimeShort(value)

Formats a date and time as short string representation, for example 01/04/16 12:00 AM.

value

A Date object. A Date can contain a date and time.

time(value, pattern)

Formats a time using a custom pattern.

value

A Date object. A Date can contain a date and time.

pattern

String. The custom pattern may consist of pattern letters, separating symbols and quoted text, for example: "'at' HH:mm:ss z"; see Date and time patterns. Note that the repetition of pattern letters determines the exact presentation.

timeLong(value)

Formats a time as long string representation, for example 12:00:00 EDT AM.

value

A Date object. A Date can contain a date and time.

timeMedium(value)

Formats a time as medium string representation, for example 12:00:00 AM.

value

A Date object. A Date can contain a date and time.

timeShort(value)

Formats a time as short string representation, for example 12:00 AM.

value

A Date object. A Date can contain a date and time.

Examples

The following script passes the value of a field in the record set to the date() function. This will only work if the type of the field has been set to Date in the data mapping configuration and if the field contains a valid date.

var myDate = formatter.date(records.fields.DATE, "MM/dd/yyyy");

The custom pattern that the script provides, outputs the month and day in two digits each and the year in four digits: 05/21/2016. For more examples of formatting patterns, see Date and time patterns.

Creating a Date object from a string

In a data mapping configuration you can set the type of a field to Date, but when you open a data file or database in the Designer without a data mapping configuration, all fields are text fields (fields of the type string). The formatter cannot be used to format a string with a particular date format. The solution is to store the string in a variable as a Date object, and use the formatter with that variable.

The following sample script demonstrates this solution. It splits a string into parts and then creates a new Date object with the parts in the correct order. To construct a Date, the parts of the date must be put in the following order: year, month, day, and optionally hours, minutes, seconds, milliseconds (see https://www.w3schools.com/js/js_dates.asp and https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date.) When the time is omitted, it defaults to 12:00:00 AM.

/* Convert the string 21-12-1997 into a valid JavaScript date */
	var strDate = record.fields["date"];
	var dateParts = strDate.split("-");
	var date = new Date(dateParts[2], (dateParts[1] - 1), dateParts[0]);
JavaScript counts months from 0 to 11. January is 0. December is 11.

Another way to put a string in a Date is to use the Date.parse function; see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse.

The date variable can be used as the value in the date, dateTime or time functions of the formatter.

var myDate = formatter.date(date, "MM/dd/yyyy");

The custom pattern that the script provides, outputs the month and day in two digits each and the year in four digits: 05/21/2016. For more examples of formatting patterns, see Date and time patterns.