Timeline highlighting and filtering

From SIMILE Widgets
Jump to: navigation, search

Contents

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.

<script src="../examples.js" type="text/javascript"></script> 

...

 <script> 
        var tl;
        function onLoad() {

...

setupFilterHighlightControls(document.getElementById("controls"), tl, [0,1], theme);
}
</script>
</head>
<body onload="onLoad();" onresize="onResize();"> 
<div class="controls" id="controls"></div>
</body>

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

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox