{{ and }}. Easy. It offers a few bits of logic, such as if/else clauses, for-each loops, etc. But, just as usefully, Handlebars allows you to add helper functions of your own.In this article I will show a nice little Handlebars helper to format datestamps and timestamps. Its raison d’etre is its support for multiple languages and timezones. The simplest use case (assuming
birthday is their birthday in some common format):<p>Your birthday is on {{timestamp birthday}}.</p>There are two ways to configure it: with global variables, or with per-tag options. For most applications, setting the globals once will be best. Here are the globals it expects to find:
tzOffset: the number of seconds your timezone is ahead of UTC. E.g. if in Japan, thentzOffset = 9*3600. If in the U.K. this is either0or3600depending on if it is summer time or not.lang: The user-interface language, e.g. “en” for English, “ja” for Japanese, etc.
The default timestamp format is the one built-in to sugar.js for your specified language. All these configuration options (the two above, and format) can be overridden when using the tag. E.g. if
start is the timestamp of when an online event starts, you could write:<p>The live streaming will start at
{{timestamp start tzOffset=0}} UTC,
which is {{timestamp start tzOffset=32400}}
in Tokyo and {{timestamp start tzOffset=-25200}}
in San Francisco.</p>Handlebars.registerHelper('timestamp', function(t, options){
var offset = options.hash.tzOffset;
if(!offset)offset = tzOffset;
if(!Object.isDate(t)){
if(!t)return "";
if(Object.isString(t))t = Date.create(t + "+0000").setUTC(true).addSeconds(offset);
else t = Date.create(t*1000).setUTC(true).addSeconds(offset);
}
else t = t.clone().addSeconds(offset);
if(!t.isValid())return "";
var code = options.hash.lang;
if(!code)code = lang; //Use global as default
var format = options.hash.format ? options.hash.format : '';
return t.format(format, lang);
});t into a Date object, coping whether it was already a Date object, or a string (in UTC, and in any common format the Date.create() can cope with), or a number (in which case it is seconds since Jan 1st 1970 UTC). However, be careful if giving a pre-made Date object: make sure it was the time in UTC and specifies that is in UTC.The rest of the function just chooses the language and format, and returns the formatted date string.
If you were paying attention you would have noticed
t stores a lie. E.g. for 5pm BST, t would be given as 4pm UTC. We then turn it into a date that claims to be 5pm UTC. Basically this is to stop format() being too clever, and adjusting for local browser time. (This trick is so you can show a date in a browser for something other than the user’s local timezone.)But it does mean that if you include any of the timezone specifiers in your format string, they will wrongly claim it is UTC.
{{timestamp theDeadline format="{HH}:{mm} {tz}" }} will output 17:00 +0000.To allow you to explicitly specify the true timezone, here is an enhanced version:
Handlebars.registerHelper('timestamp', function(t, options){
var offset = options.hash.tzOffset;
if(!offset)offset = tzOffset; //Use global as default
if(!Object.isDate(t)){
if(!t)return "";
if(Object.isString(t))t = Date.create(t + "+0000").setUTC(true).addSeconds(offset);
else t = Date.create(t*1000).setUTC(true).addSeconds(offset);
}
else t = t.clone().addSeconds(offset);
if(!t.isValid())return "";
var code = options.hash.lang;
if(!code)code = lang; //Use global as default
var format = options.hash.format ? options.hash.format : '';
var s = t.format(format, lang);
if(options.hash.appendTZ)s+=tzString;
if(options.hash.append)s+=options.hash.append;
return s;
});Now if you specify
appendTZ=true then it will append the global tzString. Alternatively you can append any text you want by specifying append. So, our earlier example becomes one of these:{{timestamp theDeadline format="{HH}:{mm}" appendTZ=true}}
{{timestamp theDeadline format="{HH}:{mm}" append="BST"}}
{{timestamp theDeadline format="{HH}:{mm}" append=theDeadlineTimezone}}VERSION INFO: The above code is for sugar.js v.1.5.0, which is the latest version at the time of writing, and likely to be so for a while. If you need it for sugar.js 1.4.x then please change all occurrences of
setUTC(true) to utc().
