Timeline highlighting and filtering

= Introduction = The code for the various painters in the Timeline library includes highlighting and filtering methods as below, but the code to actually perform filtering is not part of the main API.

Code to actually generate a UI for filtering and highlighting is to be found in examples.js in the timeline/src/webapp/site/examples/ directory (see the jfk example). A revised version of setupFilterHighlightControls is to be found at Multiple filter boxes


 * [Editorial Note: Recommend that setupFilterHighlightControls be integrated into the API in an appropriate place in timeline/src/webapp/api/scripts. There have been many questions to the list arising from confusion over where this code lives. Jjon 19:34, 14 September 2009 (UTC)]

Highlighting
An event can have highlighting added on a per-band basis.
 * Use the band's getHighlightMatcher and setHighlightMatcher to add your highlighting function.
 * Your function will have argument evnt -- an event object
 * Your function returns the highlighting_index (integer) for the event:
 * less than 0 - no highlighting
 * 0-3 - highlighting indexes. -- Uses the highlighting css in theme.event.highlightColors

Example
See the JFK Timeline for an example of adding highlighting to a Timeline

Please double-check that this code is all that is needed.



...

var tl; function onLoad {

...

setupFilterHighlightControls(document.getElementById("controls"), tl, [0,1], theme); } 

Filtering
Bands include a filtering option. Each event in a band with a filter either will pass the filter and be shown in the band, or will be stopped by the filter and not shown.
 * Use the band's getFilterMatcher and setFilterMatcher to add your filter function.
 * Your function will have argument evnt -- an event object
 * Your function returns true if the event passes the filter, or false.

Filters are binary: either an event passes the filter procedure and will thus be shown on the timeline or it doesn't, and the event will be omitted.

If you want additional logic for the user interface then you can make your filter procedure as elaborate as you'd like: eg multiple boxes that "or" the boxes' content against the event name/description; check boxes for different pre-defined event types, ANDing and ORing of expressions; filtering using drop down menus of different event 'categories' etc.

Note that the filter can also look into additional event attributes that are not part of the formal Timeline event attributes. This is done through the method event.getProperty

See also: Multiple filter boxes

Example
See the JFK Timeline for an example of adding filtering to a Timeline