infimum.dk > DHTML F.A.Q. > Date Formatter

Date Formatter

This simple date formatter is inspired by the Java SimpleDateFormatter class. It is used by first creating a formatter from a format, and then applying the formatter to a date:

var myFormatter = new DateFormatter("yyyy-MM-dd HH:mm:ss");
var now = new Date();
var xmaseve = new Date(now.getFullYear(),12-1,24);
alert(myFormatter.format(now) + "\n" + myFormtter.format(xmaseve));

The format interprets sequences of similar letters as a field. The number of letters decide the minimum width of the field. Numeric values are padded to that width. In some cases (month and day-of-week) lengths of three results in the three letter abbreviation of the month or week-day, while a length of four or more results in the unabbreviated name.

Numeric values followed by a "." will be written as ordinals. E.g., the format "MM." for the month December will result in "12th".

The formatter depends on a "locale" for language and country dependent information: names of days and months, whether to use AM/PM, and how to write ordinals. The default is English names and ordinals with AM/PM, but it can be changed by creating a new locale-object.

Unrecognized letters and non-letters are inserted verbatim in the result. The recognized letters are:

LetterMeaningComment
y Year If the field is shorter than three letters, then the century is discarded. I.e., for the year 1972, the format "yy" results in "72".
M Month MMM gives the three-letter abbreviation of the month (e.g., "Jan"). MMMM (and longer) gives the full name of the month (e.g., "January").
d Day of month
D Day of week One or two D's gives the number of the day in the week, from 1 to 7. Three D's gives the three-letter abbreviation for the day (e.g., "Mon"), while four or more D's gives the full name (e.g., "Monday").
H Hours, between 0 and 23.
h Hours, between 1 and 12 If the current locale doesn't use AM/PM, it is equivalent to H.
A AM/PM AM or PM if the current locale uses it, otherwise nothing
m Minutes
s Seconds
\ A verbatim word or symbol If followed by a word, a backslash or a full stop, recognized letters and symbols are not interpreted.
E.g., "\\the d. \\of MMMM" gives "the 28th of March".

The code for DateFormatter is available as DateFormatter.js.

Example Use





Custom Locales

The date formatter is parameterized with a locale that defines the region and language specific parts of the formatting. The default locale uses English names and notation as well as calendar conventions (Sunday as first day of week).

To create a custom locale, just make an object with the same attributes and methods as the default locale:

PropertyTypeMeaning
month String array Array with names of months
shortMonth String array Array with three-letter abbreviations of names of months
day String array Array with names of week days, Sunday first
shortDay String array Array with three-letter abbreviations of names of week days, Sunday first
firstDayOfWeek number number of first day of week, 0=Sunday, 1=Monday, ..., 6=Saturday
usesAmPm boolean true if time is displayed using AM/PM
AmPm String array The strings used to represent AM and PM,in that order. Can be omitted if usesAmPm is false.
toOrdinal function Maps number to the corresponding ordinal (e.g. 42 into 42nd in English).

Example locale for Danish language and calendar:

var localeDKDA = {
month: ["januar","februar","marts","april","maj","juni",
"juli","august","september","oktober","november","december"],
shortMonth: ["jan","feb","mar","apr","maj","jun","jul",
"aug","sep","okt","nov","dec"],
day: ["søndag","mandag","tirsdag","onsdag","torsdag","fredag","lørdag"],
shortDay: ["søn","man","tir","ons","tor","fre","lør"],
firstDayOfWeek: 1,
usesAmPm: false,
toOrdinal: function(number) {
return number + ".";
}
}

The locale of a DateFormatter can be set at any time, and affects all formatting done after that.

var df = new DateFormatter("d. MMMM yyyy");
var now = new Date(1972, 3-1, 28);
df.setLocale(localeDKDA);
var danishDate = df.format(now); // 28. marts 1972
df.setLocale(DateFormatter.DEFAULT_LOCALE); // English
var englishDate = df.format(now); // 28th March 1972

Lasse Reichstein Nielsen

Last modified: Thu Mar 10 00:22:58 Romance Standard Time 2005