Timeline EventSources

= Event Attributes and Data Formats=

Timeline Event data can use any of the following popular formats:
 * XML
 * JSON
 * SPARQL more info

An Event Source controls the loading of data sources into a timeline. Also see loading events dynamically.

There is only one underlying meaning of Timeline event attributes. But the event attributes are arranged slightly differently in the different data transport formats. Each format's adapter reads the incoming data and stores it in the Timeline. For example, in the XML format, the events are a series of elements under the root element. In JSON, the root hash has an events array, whose order is not important. In the sections below, the data attributes are described. The placement of the attributes is described in the XML and JSON Data Formats sections.

= Event attributes = Defaults are used if an event does not specify an attribute value. start attribute is required. See Event Display options for examples of the different ways to display an event on a Timeline

Basic Event Attributes

 * start - in full date format (e.g. "May 20 1961 00:00:00 GMT-0600"). See next section for alternative formats.
 * latestStart - for imprecise beginnings - same date format as start. Only used by duration events (see more).
 * earliestEnd - for imprecise ends - same date format as start. Only used by duration events (see more).
 * end - same date format as start.
 * durationEvent - XML and SPARQL: "true" or "false". JSON: true or false. Only applies to events with start/end times.
 * true -- the event occurs over a time duration. No icon. The event will be drawn as a dark blue tape. The tape color is set with the color attribute. Default color is #58A0DC
 * false -- the event is focused on a specific "instant" (shown with the icon). The event will be drawn as a blue dot icon (default) with a pale blue tape. The tape is the default color (or color attribute color), with opacity set to 20. To change the opacity, change the theme's instant: {impreciseOpacity:  20} value. Maximum 100.
 * title</tt> - text title that goes next to the tape in the Timeline. Also shown in the bubble. The title attribute is optional. Leave it out if you want just an icon or icon and tape. The description will be shown in the bubble when the icon or tape is clicked.

Date Time Formats
The default date time parser uses the Javascript Date parser built into the browser.

Recommended formats
 * The format of May 10 1961 00:00:00 GMT-0600</tt> is unambiguous and is the default.
 * The RFC 2822 format of Thu, 21 Dec 2000 16:01:07 +0200</tt> also works fine by default.
 * The JSON data format used by Timeline supports explicit date objects. Eg new Date(Date.UTC(2008,0,17,20,00,00,0))</tt>. See Using JS Date objects. This format also loads in the least time since no parsing is needed.
 * A subset of the ISO 8601 format. This is also the xsd:dateTime format from XML. Examples: 1995-02-04 10:20:01Z</tt>, or 1995-02-04T10:20:01Z</tt>, or 1995-02-04T10:20:01+5:00</tt>. To use this date format, your data file must specify the date-time-format. See the Timeline attributes section, below. The ISO 8601 parser used by Timeline is from Dojo Toolkit. Documentation.

Formats that are not recommended
 * The format 5/10/1961 00:00:00 GMT-0600</tt> is ambiguous. (May 10 or October 5). It may work differently depending on the locale settings of the computer the browser is running on and the sophistication of the browser.
 * The format 5 10 1961 00:00:00 GMT-0600</tt> is also ambiguous. In addition, while Firefox, Safari and Chrome seem to understand it, IE does not.

Programming tips for proper date time formats
 * Php -- use date("r", $event_date)</tt>

Additional Event Attributes
Nota Bene: the XML standard requires that an element's text content must be escaped/formatted HTML. (eg.  &amp;lt;div&amp;gt; </tt> for   </tt>)
 * icon</tt> - url. This image will appear next to the title text in the timeline if (no end date) or (durationEvent = false</tt>). If a start and end date are supplied, and durationEvent</tt> is true, the icon is not shown. If icon attribute is not set, a default icon from the theme is used.
 * image</tt> - url to an image that will be displayed in the bubble
 * <tt>link</tt> - url. The bubble's title text will be a hyper-link to this address.
 * <tt>color</tt> - color of the text and tape (duration events) to display in the timeline. If the event has <tt>durationEvent = false</tt>, then the bar's opacity will be applied (default 20%). See <tt>durationEvent</tt>, above.
 * <tt>textColor</tt> - color of the label text on the timeline. If not set, then the <tt>color</tt> attribute will be used.
 * <tt>tapeImage</tt> and <tt>tapeRepeat</tt> Sets the background image and repeat style for the event's tape (or 'bar') on the Timeline. Overrides the color setting for the tape. Repeat style should be one of {repeat | repeat-x | repeat-y}, repeat is the default. See the Cubism example for a demonstration. Only applies to duration events.
 * <tt>caption</tt> - additional event information shown when mouse is hovered over the Timeline tape or label. Uses the html <tt>title</tt> property. Looks like a tooltip. Plain text only. See the cubism example.
 * <tt>classname</tt> - added to the HTML classnames for the event's label and tape divs. Eg classname attribute 'hot_event' will result in div classes of 'timeline-event-label hot_event' and 'timeline-event-tape hot_event' for the event's Timeline label and tape, respectively.
 * <tt>description</tt> - will be displayed inside the bubble with the event's title and image.
 * XML Format: the description is stored as the text content of the event element (see below).
 * JSON Format: the description key of the event hash

Notes:
 * url's can be absolute or relative. The base address for relative urls is the directory of event file.

Event Attributes for Developers

 * <tt>trackNum</tt> - used to override the automatic layout of events on the Timeline.
 * <tt>eventID</tt> - a cookie attribute that is stored, not used by the Timeline library. If you write a custom labeller or event bubble filler, the attribute can be obtained using the <tt>getEventID</tt> method on the event object.
 * If that's not enough for you, the event object has a generic <tt>getProperty</tt> method that will retrieve any property you care to assign to the event.

Organizing event types
You have two options for translating your event types to the user. For example, suppose most of your events are of type 'regular,' and some are of type 'special.' You want the special events to be visually distinct on the Timeline. Two options:
 * Special events would have attribute <tt>classname = 'special'</tt>. Regular events would not set classname or set it to 'regular'. Then use CSS rules to change the color, font, background image, etc of the special event's labels and tapes on the Timeline. The additional CSS rules can be specified in your HTML file or a CSS file.
 * Special events would explicitly use the event attributes <tt>color</tt>, <tt>textColor</tt>, <tt>tapeImage</tt> and <tt>tapeRepeat</tt> to change the look of the special events. The <tt>icon</tt> attribute could also be used to change the icon image.

Deprecated Event attributes
The following event attributes are still supported, but you should not use them for new event sources. Support may be removed at the next major release.
 * <tt>hoverText</tt> - superseded by the caption attribute
 * <tt>isDuration</tt> - "true" or "false". Only applies to events with start/end times. This attribute is correctly interpreted by the XML and SPARQL format handlers. It's negated (a bug) by the JSON format handler. See issue 33. This attribute is replaced by attribute <tt>durationEvent</tt> (editor's note: issue 33 not there anymore, so this business requires some further clarification on versions, backward compatibility etc.)

= Timeline attributes = These attributes are specified once per Timeline. They are then used for all events in the Timeline. They are optional. Note: in JSON event source this property is <tt>dateTimeFormat</tt>. (editor's note: are the other once-per-Timeline attributes similarly camel-cased for JSON?)
 * <tt>wiki-url</tt> - Base url used to gin up url's for each event; by appending the wiki-section and the event's title; often a MediaWiki wiki URL
 * <tt>wiki-section</tt> - MediaWiki wiki section
 * <tt>date-time-format</tt> - Which parser should be used for dates/times. Values: "iso8601" or "Gregorian". Default is "Gregorian".

If you don't want the default wiki "Discuss" links at the foot of every event bubble, completely omit the <tt>wiki-url</tt> and <tt>wiki-section</tt> attributes listed above from the data element of your Event Source. Note that simply using the wiki attributes with empty string (e.g. "") values will still result in wiki links being shown in the event bubbles; only complete omission of the attributes suppresses the wiki links.

= Which Data Format? = If another department will be creating the data file for you, your choices may be limited. For example, XML may be the preferred data exchange format for your organization. If you have more control over the data source, you may wish to try the JSON format with calls to the <tt>Date</tt> object. This format will give you the fastest load times. You can also write a Javascript adapter (similar to the existing XML, JSON and SPARQL adapters) to directly interpret a different data format.

XML Data Format
The XML format used for Timeline includes the above attributes in the following format:

Everything is contained within a '''<tt>

JSON Data Format
See http://json.org for general information about JSON.

The JSON format used for Timeline includes the above attributes in the following format:

Everything is contained in a single base object <tt>{}</tt> The base object can include the Timeline attributes:
 * <tt>wiki-url</tt>
 * <tt>wiki-section</tt>
 * <tt>date-time-format</tt> (editor's note: <tt>dateTimeFormat</tt>? see above question about camelCase)

Unless you want wiki "Discuss" links at the foot of every event bubble, completely omit the <tt>wiki-url</tt> and <tt>wiki-section</tt> attributes listed above from the data element. Note: just using the attributes with empty string ("") values will still result in wiki-links being show in the event bubbles.

The base object also contains the <tt>events</tt> attribute. Its value is an array of <tt>event</tt> objects. The events can be in any order, they do not have to be ordered by date.

Each event object can include the event attributes listed above as key : value pairs. For example:
 * <tt>start</tt>, <tt>latestStart</tt>, <tt>earliestEnd</tt>, etc
 * <tt>description</tt> is also stored as member of the event object.

As noted in the Event attributes section above, the Timeline JSON data format will accept references to the Javascript Date object as an alternative to date strings. Note that your data set will no longer strictly qualify as JSON if you include Date objects in it. (But it will load faster!)

Caveats
JSON <tt>true</tt>, <tt>false</tt> values must not include quotes. See <tt>durationEvent</tt>, below.

JSON arrays and objects should not have trailing commas before closing brackets or braces. If present, they will cause problems with some JS engines. Eg, the one in Internet Explorer.

JSON Examples
{   'wiki-url':"http://simile.mit.edu/shelf/", 'wiki-section':"Simile JFK Timeline", 'dateTimeFormat': 'Gregorian', 'events': [ {       'start':"Sat May 20 1961 00:00:00 GMT-0600", 'title':"'Bay of Pigs' Invasion", 'durationEvent':false // Notes: not "false". And no trailing comma. }, {       'start':"Wed May 01 1963 00:00:00 GMT-0600" , 'end':"Sat Jun 01 1963 00:00:00 GMT-0600" , 'durationEvent':true, 'title':"Oswald moves to New Orleans", 'description':"Oswald moves to New Orleans, and finds employment at the William B. Riley Coffee Company. ref. Treachery in Dallas, p 320" }, {      ...     } ]    // Note: Do NOT include a trailing comma! (Breaks on IE) }

SPARQL data format
Morten?

'''Please do not leave comments here, they are not read. Use the mailing list. Thanks.'''