{{
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>
It builds on top of sugar.js’s Date enhancements; I was going to do this article without using them, to keep it focused, but that would have made it unreasonably complex.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 either0
or3600
depending 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>
Here is the basic version: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);
});
The first two-thirds of the function turn 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;
});
(the only change is to add a couple of lines near the end)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}}
The first one assumes a global tzString is set. The second one hard-codes the timezone, which is unlikely to be the case; the third one is the same idea but getting timezone from another variable. 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()
.
No comments:
Post a Comment