Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 253 lines (167 sloc) 12.235 kb
9f688f3 @longlho markdowned README
longlho authored
1 # TimezoneJS.Date
2
d5fa6e6 @longlho add build status to README
longlho authored
3 [![Build Status](https://secure.travis-ci.org/mde/timezone-js.png)](https://secure.travis-ci.org/mde/timezone-js)
4
9f688f3 @longlho markdowned README
longlho authored
5 A timezone-enabled, drop-in replacement for the stock JavaScript Date. The `timezoneJS.Date` object is API-compatible with JS Date, with the same getter and setter methods -- it should work fine in any code that works with normal JavaScript Dates.
6
7 [Mailing list](http://groups.google.com/group/timezone-js)
8
9 ## Overview
10
11 The `timezoneJS.Date` object gives you full-blown timezone support, independent from the timezone set on the end-user's machine running the browser. It uses the Olson zoneinfo files for its timezone data.
12
13 The constructor function and setter methods use proxy JavaScript Date objects behind the scenes, so you can use strings like '10/22/2006' with the constructor. You also get the same sensible wraparound behavior with numeric parameters (like setting a value of 14 for the month wraps around to the next March).
14
15 The other significant difference from the built-in JavaScript Date is that `timezoneJS.Date` also has named properties that store the values of year, month, date, etc., so it can be directly serialized to JSON and used for data transfer.
16
17 ## Setup
18
19 First you'll need to include the code on your page. Both `timezoneJS.Date`, and the supporting code it needs in `timezoneJS.timezone` are bundled in the `date.js` file in `src` directory. Include the code on your page with a normal JavaScript script include, like so:
20
21 <script type="text/javascript" src="/js/timezone-js/src/date.js">
22
23 Next you'll need the Olson time zone files -- `timezoneJS.Date` uses the raw Olson data to calculate timezone offsets. The Olson region files are simple, structured text data, which download quickly and parse easily. (They also compress to a very small size.)
24
37405ea @jgable Removing extra v in tar command, adding removal of downloaded archives
jgable authored
25 Here is an example of how to get the Olson time zone files:
cad3017 @jgable Updating README with directions for getting Olson files
jgable authored
26
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
27 ``` bash
28 ##!/bin/bash
29
30 # NOTE: Run from your webroot
31
32 # Create the /tz directory
33 mkdir tz
34
35 # Download the latest Olson files
36 curl ftp://ftp.iana.org/tz/tzdata-latest.tar.gz -o tz/tzdata-latest.tar.gz
37
38 # Expand the files
39 tar -xvzf tz/tzdata-latest.tar.gz -C tz
40
41 # Optionally, you can remove the downloaded archives.
42 rm tz/tzdata-latest.tar.gz
43 ```
cad3017 @jgable Updating README with directions for getting Olson files
jgable authored
44
9f688f3 @longlho markdowned README
longlho authored
45 Then you'll need to make the files available to the `timezoneJS.timezone` code, and initialize the code to parse your default region. (This will be North America if you don't change it). No sense in downloading and parsing timezone data for the entire world if you're not going to be using it.
46
47 Put your directory of Olson files somewhere under your Web server root, and point `timezoneJS.timezone.zoneFileBasePath` to it. Then call the init function. Your code will look something like this:
48
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
49 ``` js
50 timezoneJS.timezone.zoneFileBasePath = '/tz';
51 timezoneJS.timezone.init({ callback: cb });
52 ```
9f688f3 @longlho markdowned README
longlho authored
53
c57552f @longlho update README for dependencies
longlho authored
54 If you use `timezoneJS.Date` with `Fleegix.js`, `jQuery` or `jQuery`-compatible libraries (like `Zepto.js`), there's nothing else you need to do -- timezones for North America will be loaded and parsed on initial page load, and others will be downloaded and parsed on-the-fly, as needed. If you want to use this code with some other JavaScript toolkit, you'll need to overwrite your own transport method by setting `timezoneJS.timezone.transport = someFunction` method. Take a look at `test-utils.js` in `spec` for an example.
9f688f3 @longlho markdowned README
longlho authored
55
1e15a27 @longlho clarify init function in README
longlho authored
56 **NOTE**: By default `init()` is async so you'll need to specify a callback function such as `init({ callback: cb })`. Otherwise set `init({ async: false })` to turn off async.
57
9f688f3 @longlho markdowned README
longlho authored
58 ## Usage
59
9f8f5ae @lumbric fix bug with date strings without timezone
lumbric authored
60 The `timezoneJS.Date` constructor is compatible to the normal JavaScript Date constructor, but additional allows to pass an optional `tz` (timezone). In the following cases the passed date/time is unambiguous:
61
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
62 ``` js
63 timezoneJS.Date(millis, [tz])
64 timezoneJS.Date(Date, [tz])
65 timezoneJS.Date(dt_str_tz, [tz])
66 ```
9f8f5ae @lumbric fix bug with date strings without timezone
lumbric authored
67
c57552f @longlho update README for dependencies
longlho authored
68 `dt_str_tz` is a date string containing timezone information, i.e. containing `Z`, `T` or a timezone offset matching the regular expression `/[+-][0-9]{4}/` (e.g. `+0200`). The [one-stop shop for cross-browser JavaScript Date parsing behavior](http://dygraphs.com/date-formats.html) provides detailed information about JavaScript date formats.
9f8f5ae @lumbric fix bug with date strings without timezone
lumbric authored
69
70 In the following cases the date is assumed to be a date in timezone `tz` or a locale date if `tz` is not provided:
71
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
72 ``` js
73 timezoneJS.Date(year, mon, day, [hour], [min], [second], [tz])
74 timezoneJS.Date(dt_str, [tz])
75 ```
9f8f5ae @lumbric fix bug with date strings without timezone
lumbric authored
76
5916a8c @chotiwat Update README.md
chotiwat authored
77 `dt_str` is a date string containing no timezone information.
9f8f5ae @lumbric fix bug with date strings without timezone
lumbric authored
78
79 ### Examples
80
9f688f3 @longlho markdowned README
longlho authored
81 Create a `timezoneJS.Date` the same way as a normal JavaScript Date, but append a timezone parameter on the end:
82
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
83 ``` js
84 var dt = new timezoneJS.Date('10/31/2008', 'America/New_York');
85 var dt = new timezoneJS.Date(2008, 9, 31, 11, 45, 'America/Los_Angeles');
86 ```
9f688f3 @longlho markdowned README
longlho authored
87
88 Naturally enough, the `getTimezoneOffset` method returns the timezone offset in minutes based on the timezone you set for the date.
89
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
90 ``` js
91 // Pre-DST-leap
92 var dt = new timezoneJS.Date(2006, 9, 29, 1, 59, 'America/Los_Angeles');
93 dt.getTimezoneOffset(); => 420
94 // Post-DST-leap
95 var dt = new timezoneJS.Date(2006, 9, 29, 2, 0, 'America/Los_Angeles');
96 dt.getTimezoneOffset(); => 480
97 ```
9f688f3 @longlho markdowned README
longlho authored
98
8ff1a36 @EugenyLoy Small formatting tweaks
EugenyLoy authored
99 Just as you'd expect, the `getTime` method gives you the UTC timestamp for the given date:
9f688f3 @longlho markdowned README
longlho authored
100
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
101 ``` js
102 var dtA = new timezoneJS.Date(2007, 9, 31, 10, 30, 'America/Los_Angeles');
103 var dtB = new timezoneJS.Date(2007, 9, 31, 12, 30, 'America/Chicago');
104 // Same timestamp
105 dtA.getTime(); => 1193855400000
106 dtB.getTime(); => 1193855400000
107 ```
9f688f3 @longlho markdowned README
longlho authored
108
109 You can set (or reset) the timezone using the `setTimezone` method:
110
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
111 ``` js
112 var dt = new timezoneJS.Date('10/31/2006', 'America/Juneau');
113 dt.getTimezoneOffset(); => 540
114 dt.setTimezone('America/Chicago');
115 dt.getTimezoneOffset(); => 300
116 dt.setTimezone('Pacific/Honolulu');
117 dt.getTimezoneOffset(); => 600
118 ```
9f688f3 @longlho markdowned README
longlho authored
119
8ff1a36 @EugenyLoy Small formatting tweaks
EugenyLoy authored
120 The `getTimezone` method tells you what timezone a `timezoneJS.Date` is set to:
9f688f3 @longlho markdowned README
longlho authored
121
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
122 ``` js
123 var dt = new timezoneJS.Date('12/27/2010', 'Asia/Tokyo');
124 dt.getTimezone(); => 'Asia/Tokyo'
125 ```
9f688f3 @longlho markdowned README
longlho authored
126
a14273a @EugenyLoy Update README.md - added example showing how to get timezone abbreviatio...
EugenyLoy authored
127 You can use `getTimezoneAbbreviation` method to get timezone abbreviation:
128
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
129 ``` js
130 var dt = new timezoneJS.Date('10/31/2008', 'America/New_York');
131 dt.getTimezoneAbbreviation(); => 'EDT'
132 ```
a14273a @EugenyLoy Update README.md - added example showing how to get timezone abbreviatio...
EugenyLoy authored
133
9f688f3 @longlho markdowned README
longlho authored
134 ## Customizing
135
136 If you don't change it, the timezone region that loads on
137 initialization is North America (the Olson 'northamerica' file). To change that to another reqion, set `timezoneJS.timezone.defaultZoneFile` to your desired region, like so:
138
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
139 ``` js
140 timezoneJS.timezone.zoneFileBasePath = '/tz';
141 timezoneJS.timezone.defaultZoneFile = 'asia';
142 timezoneJS.timezone.init();
143 ```
9f688f3 @longlho markdowned README
longlho authored
144
145 If you want to preload multiple regions, set it to an array, like this:
146
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
147 ``` js
148 timezoneJS.timezone.zoneFileBasePath = '/tz';
149 timezoneJS.timezone.defaultZoneFile = ['asia', 'backward', 'northamerica', 'southamerica'];
150 timezoneJS.timezone.init();
151 ```
9f688f3 @longlho markdowned README
longlho authored
152
153 By default the `timezoneJS.Date` timezone code lazy-loads the timezone data files, pulling them down and parsing them only as needed.
154
155 For example, if you go with the out-of-the-box setup, you'll have all the North American timezones pre-loaded -- but if you were to add a date with a timezone of 'Asia/Seoul,' it would grab the 'asia' Olson file and parse it before calculating the timezone offset for that date.
156
157 You can change this behavior by changing the value of `timezoneJS.timezone.loadingScheme`. The three possible values are:
158
159 1. `timezoneJS.timezone.loadingSchemes.PRELOAD_ALL` -- this will preload all the timezone data files for all reqions up front. This setting would only make sense if you know your users will be using timezones from all around the world, and you prefer taking the up-front load time to the small on-the-fly lag from lazy loading.
160 2. `timezoneJS.timezone.loadingSchemes.LAZY_LOAD` -- the default. Loads some amount of data up front, then lazy-loads any other needed timezone data as needed.
161 3. `timezoneJS.timezone.loadingSchemes.MANUAL_LOAD` -- Preloads no data, and does no lazy loading. Use this setting if you're loading pre-parsed JSON timezone data.
162
163 ## Pre-Parsed JSON Data
164
165 If you know beforehand what specific cities your users are going to be using, you can reduce load times specifically by creating a pre-parsed JSON data file containing only the timezone info for those specific cities.
166
0ce8355 @longlho update README
longlho authored
167 The src directory contains 2 command-line JavaScript scripts that can generate this kind of JSON data:
168
169 - `node-preparse.js`: Uses Node to preparse and populate data.
170 - `preparse.js`: This script requires the Rhino (Java) JavaScript engine to run, since the stock SpiderMonkey (C) engine doesn't come with file I/O capabilities.
9f688f3 @longlho markdowned README
longlho authored
171
172 Use the script like this:
173
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
174 ``` bash
175 rhino preparse.js zoneFileDirectory [exemplarCities] > outputfile.json
176 ```
9f688f3 @longlho markdowned README
longlho authored
177
0ce8355 @longlho update README
longlho authored
178 Or:
179
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
180 ``` bash
181 node node-preparse.js zoneFileDirectory [exemplarCities] > outputfile.json
182 ```
0ce8355 @longlho update README
longlho authored
183
9f688f3 @longlho markdowned README
longlho authored
184 The first parameter is the directory where the script can find the Olson zoneinfo files. The second (optional) param should be a comma-delimited list of timzeone cities to create the JSON data for. If that parameter isn't passed, the script will generate the JSON data for all the files.
185
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
186 ``` bash
187 rhino preparse.js olson_files \
188 "Asia/Tokyo, America/New_York, Europe/London" \
189 > major_cities.json
190
191 rhino preparse.js olson_files > all_cities.json
192 ```
9f688f3 @longlho markdowned README
longlho authored
193
0ce8355 @longlho update README
longlho authored
194 Or:
195
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
196 ``` bash
197 node node-preparse.js olson_files \
198 "Asia/Tokyo, America/New_York, Europe/London" \
199 > major_cities.json
9f688f3 @longlho markdowned README
longlho authored
200
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
201 node node-preparse.js olson_files > all_cities.json
202 ```
0ce8355 @longlho update README
longlho authored
203
9f688f3 @longlho markdowned README
longlho authored
204 Once you have your file of JSON data, set your loading scheme to `timezoneJS.timezone.loadingSchemes.MANUAL_LOAD`, and load the JSON data with `loadZoneJSONData`, like this:
205
a049a0c @ockcyp Syntax highlighting for bash and js code blocks
ockcyp authored
206 ``` js
207 var _tz = timezoneJS.timezone;
208 _tz.loadingScheme = _tz.loadingSchemes.MANUAL_LOAD;
209 _tz.loadZoneJSONData('/major_cities.json', true);
210 ```
9f688f3 @longlho markdowned README
longlho authored
211
0ce8355 @longlho update README
longlho authored
212 Since the limited set of data will be much smaller than any of the zoneinfo files, and the JSON data is deserialized with `eval` or `JSON.parse`, this method is significantly faster than the default setup. However, it only works if you know beforehand exactly what timezones you want to use.
9f688f3 @longlho markdowned README
longlho authored
213
214 ## Compressing
215
216 The Olson timezone data files are simple, space- and linefeed-delimited data. The abundance of whitespace means they compress very, very well.
217
218 If you plan to use `timezoneJS.Date` in a production Web app, it's highly recommended that you first strip the copious comments found in every Olson file, and serve compressed versions of the files to all browsers that can handle it. **(Note that IE6 reports itself as able to work with gzipped data, but has numerous problems with it.)**
219
220 Just to give you an idea of the difference -- merely stripping out the comments from the 'northamerica' file reduces its size by two-thirds -- from 103K to 32K. Gzipping the stripped file reduces it down to 6.5K -- probably smaller than most of the graphics in your app.
221
222 The `src` directory has a sample Ruby script that you can use to strip comments from Olson data files.
223
67c844b @longlho switch test framework to Jasmine since jsUnit is no longer supported. Mo...
longlho authored
224 ## Development
3131489 @longlho update documentation
longlho authored
225 This project use [Jake](https://github.com/mde/jake) to build. In order to see available tasks, do `jake -T`. The build sequence is:
9f688f3 @longlho markdowned README
longlho authored
226
3131489 @longlho update documentation
longlho authored
227 - `jake test:init`: Download and extract tz files to `lib/tz`.
228 - `jake test`: Run `jasmine-node`.
d09d43e @longlho add contributors section to package.json, update README for further test...
longlho authored
229
3131489 @longlho update documentation
longlho authored
230 Feel free to fork and modify at your own will.
13cfb3c @longlho updated README w/ copyright, resolve #47
longlho authored
231 The source code is annotated and doc can be generated with `jake doc`.
232
1532324 @longlho minor README tweak
longlho authored
233 ## License
13cfb3c @longlho updated README w/ copyright, resolve #47
longlho authored
234
235
236 Copyright 2010 Matthew Eernisse (mde@fleegix.org) and Open Source Applications Foundation.
237
238 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
239
240 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
241
242 Credits: Ideas included from incomplete JS implementation of Olson parser, "XMLDAte" by Philippe Goetz (philippe.goetz@wanadoo.fr)
243
244 Contributions:
245
246 - Jan Niehusmann
247 - Ricky Romero
248 - Preston Hunt (prestonhunt@gmail.com)
249 - Dov. B Katz (dov.katz@morganstanley.com)
250 - Peter Bergström (pbergstr@mac.com)
251 - Long Ho (@longlho)
fa7c48b @EugenyLoy Updated contributor's list
EugenyLoy authored
252 - Eugeny Loy (eugeny.loy@gmail.com)
Something went wrong with that request. Please try again.