Please turn on JavaScript. To find out how to do this visit the WebWise JavaScript guide.

Overview

The glow.widgets.Timetable widget allows you to create highly interactive "tables" of data that are proportionally laid out along a time axis, which need not be wholly in view. If neccessary, the visible portion of the Timetable can be altered by the user by dragging.

The data on a Timetable is represented by Items with a start and end point, which are organised in to one or more Tracks. Timetables can also have scales and scrollbars, as well as Track headers and footers.

Using the Timetable Widget

Getting Started

The bare minimum you need for a Timetable is a container element and some Items to display. You also need so decide when the overall start and end points are, and what view window you want.

var myTimetable = new glow.widgets.Timetable("#myTimeTable",
    "1 January 2010 00:00", "1 January 2011 00:00",
    "1 January 2010 08:00", "1 January 2010 18:00"
);

You then add one or more Tracks using the addTrack method. This factory method returns a glow.widgets.Timetable.Track and is the only way this class can be instantiated.

var myTrack = myTimetable.addTrack("myTrack", 100);

Finally, you add Items to your track using the addItem factory method of glow.widgets.Timetable.Track.

var item1 = myTrack.addItem("item1", "1 January 2010 07:30", "1 January 2010 09:45");
var item2 = myTrack.addItem("item2", "1 January 2010 10:30", "1 January 2010 10:45");

You can shortcut some of these steps using the options object. For instance you can create an Track with the Items already on it, by specifying items in the options. This is an array each of whose elements is an array of data matching the parameters of addItem. So the above example would become;

var myTrack = myTimetable.addTrack("myTrack", 100, {
    items : [
        ["item1", "1 January 2010 07:30", "1 January 2010 09:45"],
        ["item2", "1 January 2010 10:30", "1 January 2010 10:45"]
    ]
});

You can of course shortcut Track creation in to the Timetable, again by providing a tracks option that is an Array of addTrack parameter Arrays...

var myTimetable = new glow.widgets.Timetable("#myTimeTable",
    "1 January 2010 00:00", "1 January 2011 00:00",
    "1 January 2010 08:00", "1 January 2010 18:00",
    {
        tracks : [
            ["myTrack", 100]
        ]
    }
);

...or combine the two.

var myTimetable = new glow.widgets.Timetable("#myTimeTable",
    "1 January 2010 00:00", "1 January 2011 00:00",
    "1 January 2010 08:00", "1 January 2010 18:00",
    {
        tracks : [
            ["Track 1", 100, {
                items : [
                    ["item1", "1 January 2010 07:30", "1 January 2010 09:45"],
                    ["item2", "1 January 2010 10:30", "1 January 2010 10:45"]
                ]
            }],
            ["Track 2", 100, {
                items : [
                    ["item3", "1 January 2010 08:00", "1 January 2010 08:45"],
                    ["item4", "1 January 2010 09:00", "1 January 2010 11:30"]
                ]
            }]
        ]
    }
);

Drawing and redrawing

For the Timetable to appear on your page, you must explicitly call its draw method.

myTimetable.draw();

You can also use this to redraw a Timetable that has been updated (eg by altering the Tracks to show).

The result of all this code is a simple vertical timeline with no extra interface elements, and just the Item title. This looks a little sparse at the moment, but we will look at how to alter the appearance with extra features in the following sections.

Custom Item template

The first change you will probably want to make is to alter the way an Item is displayed. You can do this by setting am Item template.

This can be set for the whole timetable, for all the Items on a particular Track, or for an individual Item either by setting an itemTemplate option, or by using the setItemTemplate method, which is available on Timetable, Track and Item.

var myTimetable = new glow.widgets.Timetable("#myTimeTable",
    "1 January 2010 00:00", "1 January 2011 00:00",
    "1 January 2010 08:00", "1 January 2010 18:00",
    {
        itemTemplate : "{title} ({start})"
    }
);

See Templating within a Timetable for more information about the different ways you can specify a template.

Add banding

You can add a visual banding to appear in the background of the timetable. This is in the form of horozontal bands of colour.

To decide how the bands display, you need to decide how large the bands are, and optionally where the first one starts. To keep things simple for you, there are several shortcut options that allow common time intervals for banding and sensible start points to go with them. For instance the below code will set up bands an hour long, anchored on the hour.

myTimetable.setBanding("hour");

You can also specify banding with a time interval, as an array of "banding points", or as a function that can be used to generate such an array. See the API docs for the full specification.

Add scales

Scales fulfil a similar user interface function to bands (they give the user some sense of position), but scales offer the ability to add text labels (via a template), you can choose where they go, and you can have several of them.

myTimetable.addScale("hour", "left", 50, {template: function(data){return data.start.getHours()}})
.addScale(15 * 60 * 1000, "right", 50, {template: function(data){return data.start.getMinutes()}});

Add scrollbars

Scrollbars add another way for the user to interact with the Timetable. You can have one on each side. They work just like you would expect, but there are text labels to indicate the period in display.

myTimetable.addScrollbar("hour", "right", 50, {template: function(data){return data.start.getHours()}});

Headers and Footers

Finally, Tracks on a Timetable can have Headers and Footers. These are applied by setting a template to use, similarly to Items.

myTimetable.setTrackHeaderTemplate("<h2>{title}</h2>");

Arbitrary data on Items and Tracks

In addition to the standard information (title, start point etc) about an Item, you can also add arbitrary data to it by providing as an object in the data option. This can hold any information you want such as ratings or link URLs. This dat ais exposed on the Item as its data property, which youcan them access in your template.

myTimetable.setItemTemplate("{title} ({data.rating})");

myTrack.addItem("The News", "1 June 2009 22:00", "1 June 2009 22:30", {data: {rating: "cert. 18"}});

// Item content would be "The News (cert. 18)"

Numerical Scales

While many Timetables are based around dates or times, there are occasions when this is insufficient. You might want items arranged against distance or arbitrary milestones, or the dates in question might be outside the Javascript range. Timetables can handle these scenarios by allowing you to use numbers instead of dates.

var myNumericTimetable = new glow.widgets.Timetable("#numericExample", 0, 10, 1, 7, {
    vertical: false,
    size: 760,
    trackHeader: "<h2>{title}</h2>",
    collapseTrackBorders: false,
    trackFooter: "footer",
    itemTemplate: "{title} - {start}",
    tracks: [
        ["Track 1", 50, {items: [["Item 1", 0, 1], ["Item 2", 1, 2], ["Item 3", 2, 3]]}],
        ["Track 2", 50, {items: [["Item 4", 3, 4], ["Item 5", 4, 5], ["Item 6", 5, 6]]}]
    ]})
    .draw();

Themes

There are two standard themes. All the examples to now have used the default "light" theme, but you can also specify the dark theme in the constuctor options. It will look like this;

BBC navigation

BBC © 2014 The BBC is not responsible for the content of external sites. Read more.

This page is best viewed in an up-to-date web browser with style sheets (CSS) enabled. While you will be able to view the content of this page in your current browser, you will not be able to get the full visual experience. Please consider upgrading your browser software or enabling style sheets (CSS) if you are able to do so.