Getting Started

Getting Started

This getting started guide is a brief introduction to iLib.

Getting iLib

You can get iLib in one of three ways:

1. Download the already-assembled code from the Files link in the tabs above, unzip or untar, et voila
2. Download the source code from the Code link. The trunk always has the latest, and features are done in the separate branches.
3. Use npm to get the latest build: "npm install ilib"

Including iLib

Let's say that you are creating a web application. To include iLib, you would take the file ilib-full-compiled.js from the iLib distribution and copy it to your web server where it is accessible to your pages.

Then, you simply include it inside the head tag like any other Javascript file:

<script type="text/javascript" src="ilib-full-compiled.js"></script> 

Now any iLib class is available to use.

Now let's say you are creating a nodejs application. We assume that you have already installed the iLib npm package. At the beginning of your program, all you need to do is:

var ilib = require("ilib").ilib;

Now any iLib class is available to use.

iLib Classes

In iLib currently, there are three general types of classes:

1. Object modelers which also parse things. These model a specific type of data and the constructor usually parses a string and interprets it in some way.
2. Formatters. These take model instances and format them back into strings in a locale-sensitive manner.
3. Info objects. These are object wrappers around basic info that the object models and formatters use.

This guide will briefly go through one example of each type.

An Object Model

The ilib.Number class represents a number. It can parse numbers written as strings in many different locales.

var num = new ilib.Number("54.321,05", {
    locale: 'de-DE'
});

console.log("The number is " + num.valueOf());
// output is "The number is 54321.05"

The valueOf() method gives you the value of the number instance as an actual Javascript number.

A Formatter

Formatting a date is simply a matter of creating a date formatter instance and a date instance, and then formatting that date with the formatter. Those familiar with ICU or the Java libraries will be familiar with this pattern.

var date = ilib.Date.newInstance({
    year: 2012,
    month: 5,
    day: 18
});
var formatter = new ilib.DateFmt({type: date});
console.log("The date is " + formatter.format(date));
// output is "The date is Fri 5/18/2012"

Et voila, you have a formatted date. The strength of iLib is that the formatter classes are very configurable. The format is controlled via options to the ilib.DateFmt() constructor. In the example above, only one argument was passed to the ilib.DateFmt constructor to tell it to format dates only, so it will use the current locale and default format and length of format for that locale. See the API reference documentation for more details on the parameters to the constructor of the ilib.DateFmt class.

An Info Object

Let's say you want to get some information about a time zone. Specifically, you would like to know how many hours different a user's time zone is from the server's time zone so that your code can give them info appropriate to the time in their time zone.

First, you would create a time zone instance with the id of the user's time zone, and another instance with the id of the server's time zone. Then, for a particular time and date, you find out what the offset is to UTC for each time zone, then subtract.

var tzUser = new ilib.TimeZone({
    id: 'Europe/Berlin'
});

// default to the current time zone
var tzServer = new ilib.timeZone();

// date we are interested in
var date = ilib.Date.newInstance({
    year: 2012,
    month: 6,
    day: 1
});

// need the date because the offset changes due to daylight savings time
var userOffset = tzUser.getOffset(date); 
var serverOffset = tzServer.getOffset(date);
var differenceInHours = (userOffset.h + userOffset.m/60) - (serverOffset.h + serverOffset.m/60);

More Reading

The above is just a flavour of what you can get from iLib. There is also a more complete tutorial that goes into detail about all the things iLib can do and a number of tutorial pages listed on the home page of this wiki. You can also browse the latest API reference documentation when you are ready to start coding.