Version 1.5 glow.widgets.Timetable

Constructor

new glow.widgets.Timetable(container, start, end, viewStart, viewEnd, opts)

Parameters

container

Type

String | HTMLElement | glow.dom.NodeList

The Element into which the Timetable will be placed. If a String is given, it is used as a selector. If a Nodelist is given, the first item is used.

The contents of the element will be replaced by the Timetable. Ideally, this element should contain a static version of the timetable for users without JavaScript.

start

Type

Date | Number

The start point of the entire Timetable. The user will not be able to scroll before this point.

Also controls the unit of the Timetable. If a Number is given, the Timetable is regarded as number based, otherwise it's regarded as Date based

end

Type

Date | Number

The end point of the entire Timetable The user will not be able to scroll beyond this point.

viewStart

Type

Date | Number

The start point of the visible area. This sets the start point of the view, and in conjunction with viewEnd sets the zoom level of the timetable

viewEnd

Type

Date | Number

The end point of the visible portion. In conjunction with viewStart sets the zoom level of the timetable

opts

Type

Object

Optional

Yes

An optional options object

className

A class name for the Timetable's container element

Type

String

Optional

Yes

You must set this (or id) if you're going to customise the design of the timetable, to target it with CSS selectors.

collapseItemBorders

Should item borders collapse into each other?

Type

Boolean

Default

true

Optional

Yes

As in, take up the same space.

collapseTrackBorders

Should track borders collapse into each other?

Type

Boolean

Default

false

Optional

Yes

As in, take up the same space. This must be false if you want your tracks to be separated by a margin.

id

An id for the Timetable.

Type

String

Default

auto-generated

Optional

Yes

You must set this (or className) if you're going to customise the design of the timetable, to target it with CSS selectors.

itemTemplate

Template for each Item on a Track in the Timetable

Type

String | glow.dom.NodeList | Function

Optional

Yes

A default template is used if this is not provided, which displays just the item title

• If a String is provided, it is passed through glow.lang.interpolate, with the Item as the data parameter, and the output is used.
• If a NodeList is provided it is used directly.
• If a function is provided it should take the Item as its only argument, and return the HTML or a NodeList to use.

keepItemContentInView

Should the content of an item that is partially in view be moved into view?

Type

Boolean

Default

true

Optional

Yes

onChange

Event shortcut

Type

Function

Optional

Yes

onItemClick

Event shortcut

Type

Function

Optional

Yes

onMoveStart

Event shortcut

Type

Function

Optional

Yes

onMoveStop

Event shortcut

Type

Function

Optional

Yes

size

The width (if horizontal) or height (if vertical) of the scrollable area of the Timetable.

Type

String | Number

Default

container size

Optional

Yes

Note that headers and footers will add to the overall size.

theme

Visual theme for the Timetable.

Type

String

Default

"light"

Optional

Yes

Possible values are "light" and "dark". Both themes can be altered with CSS to fit the design of your site.

trackFooter

Template for the footer section the each Track in the Timetable

Type

String | glow.dom.NodeList | Function

Optional

Yes

Defaults to no footer. See itemTemplate above for a description of how the different values are treated.

trackHeader

Template for the header section the each Track in the Timetable

Type

String | glow.dom.NodeList | Function

Optional

Yes

Defaults to no header. See itemTemplate above for a description of how the different values are treated.

tracks

An array of Tracks to create the Timetable with.

Type

Array

Optional

Yes

Each element in the Array is an Array of parameters that are passed to the addTrack method.

This can be used to pass in timetable data as a single JSON object rather than using the addTrack and addItem methods.

vertical

Create a vertical Timetable?

Type

Boolean

Default

true

Optional

Yes

Examples

// using dates
var myTimetable = new glow.widgets.Timetable('#timetableContainer', "31 December 2008 23:30", "1 January 2009 14:30", "1 January 2009 00:30", "1 January 2009 05:30", { itemTemplate: "<strong>{title} # {id}</strong>", trackHeader: "<h2>{title}</h2>", }
) // using numbers
var myTimetable = new glow.widgets.Timetable('#timetableContainer', 0, 100, 5, 6, { itemTemplate: "<strong>{title} # {id}</strong>", trackHeader: "<h2>{title}</h2>", }
)

Properties

element

The root element of the Timetable widget

Type

glow.dom.NodeList

end

The end point of the whole Timetable

Type

Date | Number

Description

The user will not be able to scroll beyond this point.

id

The Timetable's id

Type

String

numerical

true if the Timetable is Number based, false if it is Date based

Type

Boolean

size

The width (if horizontal) or height (if vertical) of the Timetable's scrollable arae

Type

Number

start

The start point of the whole Timetable.

Type

Date | Number

Description

The user will not be able to scroll before this point.

tracks

Array of all the Tracks in the Timetable (including disabled ones).

Type

glow.widgets.Timetable.Track[]

Description

Ordered by the order they were added.

Methods

addScale

Adds a scale to one or both sides of the Timetable.

Synopsis

myTimetable.addScale(segmentation, position, size, opts);

Parameters

segmentation

Type

Number | String | function | Array

Defines the size of the scale's segments

• If a number is passed, scale segments are defined that size. If the Timetable is date based, this should be a number of milliseconds.
• If a String is passed, it should be one of "am/pm", "hour", "day", "week", "month" or "year", as shortcuts for common (not necessarily even) time intervals.
• If a function is passed, it should take a point on the Timetable as its only argument and return another point. It will be used to iteratively generate the scale segment end points starting from the first.
• If an Array is passed, its elements should be points on the Timetable, and these will be used directly as the scale segment end points. The start option below will have no effect.

position

Type

String

Optional

Yes

"top", "bottom", "left", "right" or "both" to determine where the scale should display.

• "top" and "left" are synonymous, and positions the scale above a horizontal timetable or to the left of a vertical one.
• "bottom" and "right" are synonymous, and positions the scale below a horizontal timetable or to the right of a vertical one.
• "both" positions two identical scales, one in each position.
• If more than one scale is added on the same side of the timetable, they will display in the order they were added on the top/left and in the reverse order on the bottom/right.

size

Type

String | Number

The height (if horizontal) or width (if vertical) of the scale

opts

Type

Object

Optional

Yes

Options object

className

A class name for the scale's container element

Type

String

Optional

Yes

id

An id for the scale's container element. Do not use this if adding a scale to both sides, or an error will be thrown (use className instead).

Type

String

Optional

Yes

start

The start point of the first scale segments.

Type

String | Date | Number

Default

auto

Optional

Yes

If set to auto, an appropriate choice is made for the start point.

• "am/pm" chooses 12am or 12pm
• "hour" gives the beginning of the hour
• "day" gives midnight
• "week" gives midnight on sunday
• "month" gives midnight on the first
• "year" gives midnight on January 1st

For any other segmentation definition, auto sets the start to the Timetable start point.

Has no effect if an Array is passed as the interval.

template

Specification for templating HTML of each section of the scale

Type

String | glow.dom.NodeList | Function

Optional

Yes

The template uses an object giving the segments "start" and "end" points.

• If a String is provided, it is passed through glow.lang.interpolate, with the above scale segment data object as the other parameter, and the output is used.
• If a NodeList is provided it is used directly.
• If a function is provided it should take the above scale segment data object as its argument, and return a String or a NodeList to use.
• If the final output of the template is a String, it need not contain any HTML (eg just a time of day, like "8am" is OK).
• If no template is supplied the scale segments will be empty.

Returns

this

Description

Several scales can be attached to either side of the Timetable - eg hours and "am/pm".

Scales will appear in the order in which they were added, working inwards. ie the last to be added will be closest to the Tracks.

Note that scales won't appear until the Timetable has been redrawn.

Example

myTimetable.addScale("hour", "left", 50, { template: function (segment) { return segment.start.getHours(); }
});

addScrollbar

Adds a scrollbar to one or both sides of the Timetable

Synopsis

myTimetable.addScrollbar(marks, position, size, opts);

Parameters

marks

Type

Number | String | function | Array

Defines the scrollbar's mark points

• If a number is passed, mark points are defined that far apart. If the Timetable is date based, this should be a number of milliseconds.
• If a String is passed, it should be one of "am/pm", "hour", "day", "week", "month" or "year", as shortcuts for common (not necessarily even) time intervals.
• If a function is passed, it should take a point on the Timetable as its only argument and return the next point. It will be used to iteratively generate the mark points starting from the first.
• If an Array is passed, its elements should be points on the Timetable, and these will be used directly as the mark points. The start option below will have no effect.

position

Type

String

Optional

Yes

"top", "bottom", "left", "right" or "both" to determine where the scale should display

• "top" and "left" are synonymous, and positions the scrollbar above a horizontal timetable or to the left of a vertical one.
• "bottom" and "right" are synonymous, and positions the scrollbar below a horizontal timetable or to the right of a vertical one.
• "both" positions two identical scrollbar, one in each position.

size

Type

String | Number

The height (if horizontal) or width (if vertical) of the scrollbar

opts

Type

Object

Optional

Yes

Options object

className

A class name for the scrollbar's container element

Type

String

Optional

Yes

id

An id for the scrollbar container element. Do not use this if adding a scrollbar to both sides, or an errro will be thrown.

Type

String

Optional

Yes

start

The first mark point.

Type

String | Date | Number

Default

auto

Optional

Yes

If set to auto, an appropriate choice is made for the start point.

• "am/pm" chooses 12am or 12pm
• "hour" gives the beginning of the hour
• "day" gives midnight
• "week" gives midnight on sunday
• "month" gives midnight on the first
• "year" gives midnight on January 1st

Has no effect if an Array is passed as the marks.

template

Specification for templating HTML of each mark point

Type

String | glow.dom.NodeList | Function

Optional

Yes

The template uses an object giving the mark's "start" and "end" points.

• If a String is provided, it is passed through glow.lang.interpolate, with the above data object as the other parameter, and the output is used.
• If a NodeList is provided it is used directly.
• If a function is provided it should take the above data object as its argument, and return a String or a NodeList to use.
• If the final output of the template is a String, it need not contain any HTML (eg just a time of day, like "8am" is OK).
• If no template is supplied the scale segments will be empty.

Returns

this

Description

Only one scrollbar can be attached to either side of the Timetable, if more than one are added, the last one is used.

Note that scrollbars won't appear until the Timetable has been redrawn.

Example

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

addTrack

Factory method for creating a standard Track and adding it to the Timetable.

Synopsis

myTimetable.addTrack(title, size, opts);

Parameters

title

Type

String

The title of the Track

size

Type

String | Number

The height (if horizontal) or width (if vertical) of the Track (not including borders and margins)

opts

Type

Object

Optional

Yes

Options object

className

A class name for the Track's container element

Type

String

Optional

Yes

data

An object of arbitrary data to be attached to the Track.

Type

Object

Optional

Yes

disabled

A disabled track is not rendered in the view

Type

Boolean

Default

false

Optional

Yes

id

An id for the Track

Type

String

Default

auto-generated

Optional

Yes

items

An array of Items to create the Track with

Type

Array

Optional

Yes

Each element in the Array is an Array of parameters that are passed to the addItem method of the Track

itemTemplate

Template for each Item on this Track.

Type

String | glow.dom.NodeList | Function

Optional

Yes

Overrides any template specified at Timetable level.

1. If a String is provided, it is passed through glow.lang.interpolate, with the Item as the other parameter, and the output is used.
2. If a NodeList is provided it is used directly.
3. If a function is provided it should take the Item as its only argument, and return the HTML or a NodeList to use.

trackFooter

Template for the footer section the this Track.

Type

String | glow.dom.NodeList | Function

Optional

Yes

Overrides any template specified at Timetable level.

See itemTemplate above for a description of how the different values are treated.

trackHeader

Template for the header section the this Track.

Type

String | glow.dom.NodeList | Function

Optional

Yes

Overrides any template specified at Timetable level.

See itemTemplate above for a description of how the different values are treated.

Returns

glow.widgets.Timetable.Track

The Track that was created

Description

Tracks can only created by using this method.

Example

// no items
var myTrack1 = myTimetable.addTrack("Track 1", 250); // add some items at the same time
var myTrack2 = myTimetable.addTrack("Track 2", 250, { items : [ ["Item 1", "2009/01/01 00:00", "2009/01/01 01:00"], ["Item 2", "2009/01/01 01:00", "2009/01/01 01:30"], ["Item 3", "2009/01/01 01:30", "2009/01/01 01:40"] ]
}); // add additional items
myTrack2.addItem("Item 4", "2009/01/01 01:40", "2009/01/01 02:00");

currentPosition

Gets or sets the start point of the Timetable's visible portion

Synopsis

myTimetable.currentPosition(value);

Parameters

value

Type

Date | Number

The new start point to use

Returns

this

draw

Update the view with any changes you've made.

Synopsis

myTimetable.draw(redraw);

Parameters

redraw

Type

Boolean

Default

false

Optional

Yes

Redraw all items? Usually, draw will just draw items & tracks that have been added since last calling draw. Use this option to force the timetable to completely redraw.

Returns

this

Description

You need to call this function after adding new tracks or items to make them visible on the timetable.

removeScales

Removes all the scales from one or both sides of the Timetable.

Synopsis

myTimetable.removeScales(position);

Parameters

position

Type

String

Optional

Yes

"top", "bottom", "left", "right" or "both" to determine which scales to remove.

• "top" and "left" are synonymous, and removes the scales above a horizontal timetable or to the left of a vertical one.
• "bottom" and "right" are synonymous, and removes the scales below a horizontal timetable or to the right of a vertical one.
• "both" all the scales.

Description

Note that scales won't disappear until the Timetable has been redrawn.

setBanding

Sets the background banding for the Timetable.

Synopsis

myTimetable.setBanding(banding, opts);

Parameters

banding

Type

Number | String | function | Array

Defines the banding intervals

• If a number is passed, banding intervals are defined that far apart. If the Timetable is date based, this should be a number of milliseconds.
• If a String is passed, it should be one of "am/pm", "hour", "day", "week", "month" or "year", as shortcuts for common (not necessarily even) time intervals.
• If a function is passed, it should take a point on the Timetable as its only argument and return the next point. It will be used to iteratively generate the banding interval points starting from the first.
• If an Array is passed, its elements should be points on the Timetable, and these will be used directly as the banding interval end points. The start option below will have no effect.

opts

Type

Object

Optional

Yes

Options object

start

The start point of the first banding interval.

Type

String | Date | Number

Default

auto

Optional

Yes

If set to auto, an appropriate choice is made for the banding.

• "am/pm" chooses 12am or 12pm.
• "hour" gives the beginning of the hour
• "day" gives midnight
• "week" gives midnight on sunday
• "month" gives midnight on the first
• "year" gives midnight on January 1st

For any other banding definition, auto sets the start to the Timetable start point.

Has no effect if an Array is passed as the banding.

Returns

this

Description

Note that banding won't appear until the Timetable has been redrawn.

Example

myTimetable.setBanding("hour");

setItemTemplate

Sets the Default Item template for the Timetable

Synopsis

myTimetable.setItemTemplate(template);

Parameters

template

Type

String | glow.dom.NodeList | function

The template to use

Returns

this

setTrackFooterTemplate

Sets the default Track footer template for the Timetable

Synopsis

myTimetable.setTrackFooterTemplate(template);

Parameters

template

Type

String | glow.dom.NodeList | Function

The template to use

Returns

this

setTrackHeaderTemplate

Sets the default Track header template for the Timetable

Synopsis

myTimetable.setTrackHeaderTemplate(template);

Parameters

template

Type

String | glow.dom.NodeList | Function

The template to use

Returns

this

viewRange

Get or set the visible data range.

Synopsis

myTimetable.viewRange(newRange);

Parameters

newRange

Type

Object

Optional

Yes

An object with 'start' and / or 'end' properties, in the same format as the viewStart and viewEnd constructor parameters. If either the 'start' or 'end' property is omitted, the current value is taken.

Returns

this (if setting) or Object with start & end properties representing the view range

Description

Changing this changes the scale of the timetable, you can use this to 'zoom' the view in or out.

Example

// function to zoom in a timetable
function zoomIn(timetable) { // get the current range var range = timetable.viewRange(); // get the difference between the start and end values var currentDiff = range.end - range.start; // half the difference, this is a 2x zoom var newDiff = currentDiff / 2; // set a new end value for the range timetable.viewRange({ end: range.start.valueOf() + newDiff })
}

Events

change

Fires each time the Timetable view start point changes.

Synopsis

glow.events.addListener(myTimetable, "change", function(event) { // ...
});

Arguments

event

Type

glow.events.Event

Event Object

Description

This will fire after dragging, rather than during dragging.

itemClick

Fires when the user clicks an item on the Timetable.

Synopsis

glow.events.addListener(myTimetable, "itemClick", function(event) { // ...
});

Arguments

event

Type

glow.events.Event

Event Object

Description

The Event object will have an 'item' property.

moveStart

Fires when the Timetable starts to move (by whatever UI method).

Synopsis

glow.events.addListener(myTimetable, "moveStart", function(event) { // ...
});

Arguments

event

Type

glow.events.Event

Event Object

moveStop

Fires when the Timetable stops moving (by whatever UI method).

Synopsis

glow.events.addListener(myTimetable, "moveStop", function(event) { // ...
});

Arguments

event

Type

glow.events.Event

Event Object

Classes

Item

An Item is an "event" on a Track.

Track

A Track is a grouping of Timetable items.