Date, date/time and time functions

  • date()
  • dateLong()
  • dateMedium()
  • dateShort()
  • dateTime()
  • dateTimeLong()
  • dateTimeMedium()
  • dateTimeShort()
  • time()
  • timeLong()
  • timeMedium()
  • timeShort()

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 1-Apr-2016.

value

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

dateShort(value)

Formats a date as short string representation, for example 4/1/16.

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 1/4/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.

Note: The locale, set within the template properties, influences the output of the different Date functions; see Locale. Also see the example below.

Tip: To format a date from a date field in the record set, you can enter a custom pattern via the Helper Wizard and the Text Script Wizard; see Using the Helper Wizard, Using the Text Script Wizard, Formatting variable data and Date and time patterns. Also see the example below.

Examples

Create a Date object from a date field

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

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

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

Create a Date object from a text field

In a data mapping configuration, you can set the type of a field to Date. However, when you open a data file or database in the Designer without a data mapping configuration, all fields are treated as text (string) fields. The formatter cannot be used to format a string directly as a date.

To format such values, first convert the string into a Date object, store it in a variable, and then pass that variable to the formatter.

The following sample script demonstrates this approach. It splits a string into parts and creates a new Date object using those parts in the correct order. To construct a Date object, the values must be provided in the following order: year, month, day, and optionally hours, minutes, seconds, and milliseconds (see MDN Web Docs - Date object). If the time is omitted, it defaults to 12:00:00 AM.

Copy 
/* 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])

Note: In JavaScript, months are zero-based (0-11). January is 0. December is 11.

Another way to convert a string to a Date object is to use the Date.parse() function; see MDN Web Docs - Date parse.

The date variable can then be used as input for the date(), dateTime(), or time() functions of the formatter.

Copy 
var myDate = formatter.date(date, "MM/dd/yyyy")
results.text(myDate)

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

Using a custom locale in a Date object

By default, the date and date/time functions use the locale set in the template properties. However, you can apply a different locale when scripting the Date object by specifying an optional locale (language tag) parameter.

Copy 
var myDate = formater.dateShort(records.fields.DATE, “en-GB”)
results.text(myDate)

Note: If the specified language tag is invalid, the result is formatted using the "en-US" locale instead of the locale set in the template properties. This may lead to an unexpected date format.