Date Formats and Patterns

There are a number of different ways in which data is stored, displayed, edited and validated in Composer forms. These are mostly useful for dates and numeric values, which can be represented in different ways. When you are using Composer, you can specify these different formats by using data patterns, such as DD/MM/YYYY or $#,###.##.

 

The different formats are:

 

 

Usually, you don't need to be aware of these patterns because they are specified in your organizational stylesheets. However, you may need to occasionally override these patterns for particular fields.

 

In most cases, users will enter dates using pop-up date editors, and so date edit format patterns are not so important. However, some users, especially "power" users and visually impaired users may prefer to enter dates using the keyboard.

 

Recommendation for Dates

For dates, we recommend that the most useful Data Format is:

 

•North America: date{M/D/YYYY}|date{M/D/YY}
 

•Elsewhere: date{D/M/YYYY}|date{D/M/YY}

 

These format will:

•accept single digit days and months with or without a leading zero (flexible)
 

•accept 2 digit or 4 digit years (flexible)
 

•for editing, will always display days and years without leading zeros (simpler)
 

•for editing, will always display years including the century (no ambiguity)

 

Working with Dates

 

Composer uses the Java library moment.js (freely distributable under the terms of the MIT license) to handle dates.

 

The date clases in the Avoka Composer Framework are:

 

•sfc.formatDate(dateObject, dateFormat)
where "dateObject" is is the raw value of the form element, sfc.getRawValue(someFormElement)
 

•sfc.getDaysDifference(startDate, endDate)
Where the startDate and endDate are raw values.
 

•sfc.getTodaysDate()
Returns today's date as YYYY-MM-DD
This is not the generation date of the form (which you access in scripts with the property formula $GENERATION{DATE} instead)
This call returns only the calendar date. To get the time of day and timezone as well, use this native JavaScript call instead, where "x" will be your date object.
 
var x = new Date();
 

•sfc.isLeapYear(year)
Where "year" is a 4-digit value. Returns true or false.
 

•sfc.isPastDate(date)
Where "date" is the raw value. Returns true or false
 

•sfc.isToday(date)
Where "date" is the raw value.
 

•sfc.parseDate(dateString, dateFormat)
Parses a date according to the given date format. Both parameters are strings. Returns a raw value.

 

Advanced Date Output Formats

The sfc methods for date handling depend on the Moment.js library. This JavaScript library can output dates in various formats, as specified by this table:

 

 

You parse an input date with sfc.parseDate (dateString, dateFormat), using the formats in the Input column of the table immediately below. The output of this call gives you a properly formatted raw date format.

 

You can use these to build the full input format specification, using other characters as punctuation. For example: YYYY-MM-DD or YYYY/MM/DD or DD/MM/YYYY or MM/DD/YYYY. Internally, Composer's raw date format is YYYY-MM-DD, or for more precision to include time of day, timezones along with the date, it uses the ISO Date Format.

 

You also can control how a date object displays using sfc.formatDate(dateObject, dateFormat), using the formats displayed in the right-hand "Output" column. As with inputs, you can concatenate these together using characters as punctuation. For example: "MMMM Do, YYYY, HH:mm a, timezone Z" formats as "May 19th, 2014, 13:27 pm, timezone +10:00", where the Z specifies the timezone as the timezone offset from GMT.

 

To return the precise time and timezone, use

 

var x= new Date;

 

and get the formatted time with our sample format with the call

 

sfc.formatDate(x, "MMMM Do, YYYY, HH:mm a, timezone Z")