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

A scrollable list of ordered items displayed against a proportional axis. Note: you must call draw() on a timetable before it is displayed.

Widgets must be called in a glow.ready() call.

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

The item will be passed into the template.

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

The track will be passed into the template.

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

The track will be passed into the template.

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

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();
  }
});

Further Info & Examples

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();
  }
});

Further Info & Examples

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

The item will be passed into the template.

  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

The track will be passed into the template.

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

The track will be passed into the template.

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");

Further Info & Examples

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

Description

The item will be passed into the template.

Further Info & Examples

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

Description

The track will be passed into the template.

Further Info & Examples

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

Description

The track will be passed into the template.

Further Info & Examples

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.

Documentation generated by JsDoc Toolkit 2.1.0 on Thu Jul 07 2011 12:47:30 GMT+0100 (BST)

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.