Dates to remember
by Adam Peller

Dealing with dates in software can be trickier than it seems.  The web and Javascript add to the challenge.  Because your code is on the web, users are likely to execute it in a variety of platforms in different locales and time zones, and Javascript isn’t always helpful abstracting these issues in development.  Javascript has got a bunch of quirks of its own related to dates, perhaps worthy of their own cookies, but it’s got a reasonably straightforward API.  When you’re in Javascript, you use the Date object.  You can create one like this:

>>> new Date(2008, 5, 28)
Sat Jun 28 2008 00:00:00 GMT-0400 (EDT)

Note that month is zero-indexed, so 5 is June, not May.  Note also that the string representation is implementation dependent and will vary by browser.  It’s neither a dependable machine format, nor does it follow localized conventions — it’s always in English!   (More on localization later)  But aside from that, you’ve got a nice encapsulation for a point in time and some pretty complex calendaring rules.  It knows how to compute the day of the week and even has a pretty good idea how to deal with daylight savings.

So, you can create these Date objects, pass them between your Javascript functions, and use the methods on Date or some of the utility methods in to manipulate them.  Now, what happens when you need to use your Dates outside the Javascript world?  You’ll likely need to marshall them over the network to server storage or pass them to the DOM for some user interaction.  I like to think of it as two separate problems: talking to machines, and talking to humans.

Dates for machines

You can’t ship a Javascript Date object directly over a network connection like an XHR or a form post.  Everything must be serialized into bytes.  Letting Javascript coerce Dates to Strings, as it typically would do by default, or explicitly using Date.toString is a bad idea.  The exact syntax and format of the contents are implementation-dependent, so servers cannot reliably parse them.  The ECMAscript spec ( states only that it must be “convenient and human-readable”.  Furthermore, they’re not efficient on the wire.  Why transmit the day of the week and abbreviated month names?

A common, but troublesome practice is using mm/dd/yyyy as a wire format.  This is more efficient, but because it assumes month-day-year ordering, it is potentially confusing to other cultures which might have different conventions.  A British programmer would either have to know that this data was generated using US customs, or a terrible miscalculation might occur.  What folks in the US called 5/6/2007 (May 6th, 2007) would be interpreted as June 5th, 2007 in the UK!  It’s bad enough having your presentation assume a local custom, but creating data that is not universally understood is very troublesome indeed.  The best practice is to use some locale-neutral format that everyone can agree upon and understand.

Another common technique for storing dates, and the primitive representation in Javascript, is the Unix “epoch” timestamp, or milliseconds since January 1, 1970 UTC.  It’s impossible for humans to parse, and it has other limitations, like depending on word size.  But here’s another problem.  Suppose you want to put the date for June 28, 2008 into a database.

>>> new Date(2008, 5, 28).valueOf()

I’m in Boston.  Suppose someone in San Francisco runs their application and retrieves this data.  What will they see?

>>> var myDate = new Date(1214625600000)
>>> myDate
Fri Jun 27 2008 21:00:00 GMT-0700 (PDT)
>>> myDate.getDate()

Servers, perhaps even remote web services, might also retrieve the data, so calculations will be dependent on the host system.  This problem is not unique to Javascript.  “Unix Epoch” based representation is a point in time and not based on a timezone.  Javascript gives you the option of doing all of your date math in universal time (aka UTC, or the prime meridian) but that’s even more confusing.  Not to mention that constructor and setter calls to mutate Dates are very expensive, as each one generates costly calendar calculations.

Enter ISO-8601 dates.  They are an unambiguous, easily readable and quickly parsed way to represent dates and times, and are increasingly common in computing environments today; the next Ecmascript specifications 3.1 and 4.0 will include support for them, as does the JSON library today.  Dojo implements a simple and fast subset of the specification in


You can easily ask for just the date, so you can express that date without worrying about time zones:

>>>, {selector:'date'})

It’s concise, fixed length, and even sortable!  These little strings are easy to pass around, and can sometimes save you the cost of instantiating Date objects, which is not cheap.  Dojo uses the ISO representation exclusively in its markup and wire formats because of its elegance and because it encourages good programming practices.  dijit.form.DateTextBox and TimeTextBox encapsulate this by secretly composing ISO date strings and sending them back to the server for you in hidden fields, in place of the nicely localized and formatted information the user sees.

Dates for humans

Again, Javascript dates fall short when it comes to representing Date objects in the UI.  Date has a poorly-defined, inflexible output which is limited to either UTC or your machine’s time zone.  Firefox does have some proprietary methods for customized representation, but even that makes assumptions — even the localized Date methods assume the installed locale of the user’s browser or operating system, a setting which is not customizable by the user or by web applications.  Do not confuse this with the preferences language dialog, which only controls the HTTP accept-language header.  Developers very quickly get in the business of providing translation tables for month and day names baked into their Javascript.  For global support, multiply that by the different ordering, translation, and punctuation used by different languages and in different countries and you have hundreds, if not thousands of combinations.  That’s a lot to get right, and a lot of data and logic to send to the browser. does all the heavy lifting for you, efficiently.  It leverages a database from called the Common Locale Data Repository (CLDR), maintained by industry giants, which knows how to format dates in 135 languages (and counting).  In Dojo, only the data for the user’s language, as configured for that page, is actually transmitted to the browser.  In its simplest form, it’s as easy as

>>>, {selector: "date"})

or you can ask for a more verbose format

>>>, {selector: "date", formatLength: "long"})
"June 28, 2008"

That’s what I get on my machine in US-English.  Dojo defaults to the browser’s installation language.  But you can easily set the locale to anything you like when you load Dojo:

<script type="text/javascript" src="dojo/dojo.js" locale="zh-cn"></script>

reload, and that same code will produce different results:

>>>, {selector: "date", formatLength: "long"})
"2008年6月28日" even lets you provide custom date formats of your own, but once you do, you defeat the localization mechanism.  Want to consume dates from user input? is the inverse function.  Given a language and a “format length”, it will try and give you a Javascript Date object.


This entry was posted on Thursday, July 3rd, 2008 at 3:18 pm and is filed under Dojo Cookies. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

Leave a Reply

You must be logged in to post a comment.