modules/timeline/README.txt

// $Id: README.txt,v 1.3 2006/10/24 20:48:02 arto Exp $

DESCRIPTION
-----------
Timeline is a DHTML-based AJAXy widget for visualizing temporal information.
It works in a similar way as Google Maps but for time-based events.

This Drupal module is based on a JavaScript widget developed by the MIT
SIMILE project. Several demo timelines demonstrating the full range of 
capabilities for this widget are available on the SIMILE project site at:
  http://simile.mit.edu/timeline/

The Views module is required to provide the list of nodes to render:
  http://drupal.org/project/views

This module provides two new view types for the Views module:
- Timeline Horizontal
- Timeline Vertical

In addition, two default views are provided to get you started quickly:
- timeline_nodes: plots any nodes by their creation dates.
- timeline_events: plots event nodes by their event start and end dates
  (requires the Event module).

OPERATION
---------
The module supports plotting nodes on a timeline view using any date/time
field. It uses the views fields configuration to determine which field to
use for plotting the node as an event on the timeline. If fields have been
specified for the view, they are used as follows:
- 1st: If present, used as the start time for the timeline event. If not
  present, the node's creation time is used instead.
- 2nd: If present, used as the end time for the timeline event. If not
  present, the event will have no duration and will show up on the timeline
  as a point instead of as a block.
- 3rd: If present, used as the title and clickable link for the timeline
  event. If not present, the node's default title is used instead.
- 4th: If present, used as the description for the timeline event. If not
  present, the node's teaser is used (if available). NOTE: at present CCK
  nodes don't have a teaser by default, so you'll want to define the
  description field explicitly for them.
- Any other view fields are ignored by this module.

Timeline events with only a start date are displayed as points on the
timeline view, whilst events with both a start and date are displayed as
continuous colored blocks (not dissimilar to Gantt chart entries).

REQUIREMENTS
------------
Please refer to the accompanying INSTALL.txt file.

INSTALLATION
------------
Please refer to the accompanying INSTALL.txt file.

USAGE
-----
After installing the module, do the following to create a new timeline view:

1. Make sure the `views' and `views_ui' modules are installed and enabled.
2. Go to administer >> views >> add.
3. Fill out the parameters for your custom view:
   Under Page >> View Type (for page views) and/or
   under Block >> View Type (for block views),
     select the option "Timeline Horizontal".
4. Under Fields, add 1-4 fields as described in the Operation section above.
5. Set any other views settings, such as the maximum number of nodes to
   show, filters to select only certain nodes or dates, etc. You'll likely
   want to disable the view's pager option in order to get all events to
   show up on the timeline.
6. Save your view and navigate to it to test out the timeline. In case you
   don't see the timeline at all, that most likely indicates the view
   selection criteria didn't result in any nodes to be displayed.

CONFIGURATION
-------------
By default, the timeline widget is referenced and loaded from:
  http://simile.mit.edu/timeline/api/timeline-api.js

You can override this location from the module's configuration. You will
probably want to download the widget's source code to the same host you are
running your Drupal instance on. Provided you have the Subversion command
line tools installed, the following is the easiest way to download the
widget:

  # svn export \
      http://simile.mit.edu/repository/timeline/trunk/src/webapp/api/ \
      modules/timeline/api

After downloading, set the Widget URL option in the module's configuration
to the value: modules/timeline/api/timeline-api.js

KNOWN ISSUES
------------
- The timeline widget insists on claiming that dates are GMT, regardless of
  the actual specified timezone. This is an upstream issue in the widget
  itself; we work around it the best we can by claiming dates are GMT while
  they're in fact explicitly adjusted to the current user's timezone.
- If the view's selection criteria results in no nodes, the timeline widget
  isn't shown at all. We should show an empty timeline instead.

FUTURE WORK
-----------
- There is currently no way to override timeline display settings (such as
  width or height) on a view-specific basis. This is an important feature
  that needs to be added. Currently it is planned to implement this using
  view arguments, and in addition possibly provide a more user-friendly
  screen (administer >> timelines) for managing timelines without having to
  fiddle with a multitude of low-level Views module settings.
- The timeline widget has rudimentary support for locales. Setting a locale
  other than 'en', and automatically tying locale selection into Drupal's
  localization features, should be investigated.
- While we already support JSON and XML data feeds, the timeline widget now
  also has a SPARQL data feed loader which could provide interesting
  additional mashup capabilities.

TROUBLESHOOTING
---------------
To post bug reports or feature requests please use the following issue
trackers for the Drupal module and the MIT SIMILE widget, respectively:
- http://drupal.org/project/issues/timeline
- http://simile.mit.edu/issues/browse/TIMELINE

CREDITS
-------
Refactored and extended Drupal module by Arto Bendiken <http://bendiken.net/>
Sponsored by MakaluMedia Group <http://www.makalumedia.com/>
Original Drupal module by David Donohue <http://drdonohue.com/>
Based on MIT's SIMILE Timeline widget <http://simile.mit.edu/timeline/>
1	// $Id: README.txt,v 1.3 2006/10/24 20:48:02 arto Exp $
2
3	DESCRIPTION
4	-----------
5	Timeline is a DHTML-based AJAXy widget for visualizing temporal information.
6	It works in a similar way as Google Maps but for time-based events.
7
8	This Drupal module is based on a JavaScript widget developed by the MIT
9	SIMILE project. Several demo timelines demonstrating the full range of
10	capabilities for this widget are available on the SIMILE project site at:
11	http://simile.mit.edu/timeline/
12
13	The Views module is required to provide the list of nodes to render:
14	http://drupal.org/project/views
15
16	This module provides two new view types for the Views module:
17	- Timeline Horizontal
18	- Timeline Vertical
19
20	In addition, two default views are provided to get you started quickly:
21	- timeline_nodes: plots any nodes by their creation dates.
22	- timeline_events: plots event nodes by their event start and end dates
23	(requires the Event module).
24
25	OPERATION
26	---------
27	The module supports plotting nodes on a timeline view using any date/time
28	field. It uses the views fields configuration to determine which field to
29	use for plotting the node as an event on the timeline. If fields have been
30	specified for the view, they are used as follows:
31	- 1st: If present, used as the start time for the timeline event. If not
32	present, the node's creation time is used instead.
33	- 2nd: If present, used as the end time for the timeline event. If not
34	present, the event will have no duration and will show up on the timeline
35	as a point instead of as a block.
36	- 3rd: If present, used as the title and clickable link for the timeline
37	event. If not present, the node's default title is used instead.
38	- 4th: If present, used as the description for the timeline event. If not
39	present, the node's teaser is used (if available). NOTE: at present CCK
40	nodes don't have a teaser by default, so you'll want to define the
41	description field explicitly for them.
42	- Any other view fields are ignored by this module.
43
44	Timeline events with only a start date are displayed as points on the
45	timeline view, whilst events with both a start and date are displayed as
46	continuous colored blocks (not dissimilar to Gantt chart entries).
47
48	REQUIREMENTS
49	------------
50	Please refer to the accompanying INSTALL.txt file.
51
52	INSTALLATION
53	------------
54	Please refer to the accompanying INSTALL.txt file.
55
56	USAGE
57	-----
58	After installing the module, do the following to create a new timeline view:
59
60	1. Make sure the `views' and `views_ui' modules are installed and enabled.
61	2. Go to administer >> views >> add.
62	3. Fill out the parameters for your custom view:
63	Under Page >> View Type (for page views) and/or
64	under Block >> View Type (for block views),
65	select the option "Timeline Horizontal".
66	4. Under Fields, add 1-4 fields as described in the Operation section above.
67	5. Set any other views settings, such as the maximum number of nodes to
68	show, filters to select only certain nodes or dates, etc. You'll likely
69	want to disable the view's pager option in order to get all events to
70	show up on the timeline.
71	6. Save your view and navigate to it to test out the timeline. In case you
72	don't see the timeline at all, that most likely indicates the view
73	selection criteria didn't result in any nodes to be displayed.
74
75	CONFIGURATION
76	-------------
77	By default, the timeline widget is referenced and loaded from:
78	http://simile.mit.edu/timeline/api/timeline-api.js
79
80	You can override this location from the module's configuration. You will
81	probably want to download the widget's source code to the same host you are
82	running your Drupal instance on. Provided you have the Subversion command
83	line tools installed, the following is the easiest way to download the
84	widget:
85
86	# svn export \
87	http://simile.mit.edu/repository/timeline/trunk/src/webapp/api/ \
88	modules/timeline/api
89
90	After downloading, set the Widget URL option in the module's configuration
91	to the value: modules/timeline/api/timeline-api.js
92
93	KNOWN ISSUES
94	------------
95	- The timeline widget insists on claiming that dates are GMT, regardless of
96	the actual specified timezone. This is an upstream issue in the widget
97	itself; we work around it the best we can by claiming dates are GMT while
98	they're in fact explicitly adjusted to the current user's timezone.
99	- If the view's selection criteria results in no nodes, the timeline widget
100	isn't shown at all. We should show an empty timeline instead.
101
102	FUTURE WORK
103	-----------
104	- There is currently no way to override timeline display settings (such as
105	width or height) on a view-specific basis. This is an important feature
106	that needs to be added. Currently it is planned to implement this using
107	view arguments, and in addition possibly provide a more user-friendly
108	screen (administer >> timelines) for managing timelines without having to
109	fiddle with a multitude of low-level Views module settings.
110	- The timeline widget has rudimentary support for locales. Setting a locale
111	other than 'en', and automatically tying locale selection into Drupal's
112	localization features, should be investigated.
113	- While we already support JSON and XML data feeds, the timeline widget now
114	also has a SPARQL data feed loader which could provide interesting
115	additional mashup capabilities.
116
117	TROUBLESHOOTING
118	---------------
119	To post bug reports or feature requests please use the following issue
120	trackers for the Drupal module and the MIT SIMILE widget, respectively:
121	- http://drupal.org/project/issues/timeline
122	- http://simile.mit.edu/issues/browse/TIMELINE
123
124	CREDITS
125	-------
126	Refactored and extended Drupal module by Arto Bendiken <http://bendiken.net/>
127	Sponsored by MakaluMedia Group <http://www.makalumedia.com/>
128	Original Drupal module by David Donohue <http://drdonohue.com/>
129	Based on MIT's SIMILE Timeline widget <http://simile.mit.edu/timeline/>