Timeline .NET

Rob Chartier — Wed, 26 Mar 2008 02:43:00 GMT

My latest project over on CodePlex.com is Timeline .NET.

The Project Description…

Timeline .NET is the most complete ASP.NET WebControl which wraps the MIT Simile Timeline API.

Control such things as the data feed which can come directly from an RSS feed or add Timeline Events directly with a fully managed API. You can also control the Height and Width of the Timeline itself; the Bubble Height and Width; full control over type different bands in use (HotZone, Original, Standard) and adding any number of Zones to each band, etc...

View the samples online here.

I wanted to put together a quick article on the usage of the control and some of its options.

Usage

First off we will download the current release off of the Codeplex website, found at: http://www.codeplex.com/timelinenet/Release/ProjectReleases.aspx Right now I have made available a direct download to the DLL alone, named “TimelineNet.dll”.

Next create a new Web Application using Visual Studio. By the way, I’m using Visual Studio 2008 (and ASP.NET 2.0), so the dialogs might be slightly different if you are using 2005.

In this Web Application you will need to set a reference to the TimelineNet.dll which you previously downloaded. Right click the project in the solution explorer, and choose “Add Reference”. Browse until you find the DLL and then hit OK.

The next step that you might want to do is add it to the Toolbox in VS.NET. To do this right click the Toolbox and first add a new tab called “Timeline”. In that tab right click and choose “Choose Items”. Again browse for the TimelineNet.dll. You should now see the Timeline control in the Toolbox.

Drag the Timeline control onto the page and lets add in a few basic properties:

<cc1:Timeline DataSourceType="rss" DataUrl="http://weblogs.asp.net/rchartier/rss.aspx" Height="300" Width="100%" ID="Timeline1" runat="server" />

Notice that we are instructing the control to grab the RSS feed from my weblog. This will instruct the Ajax Handler (which we will get to in 2 seconds) to yank the RSS feed content and use it as the datasource for the events which will be rendered in the Timeline.

Now in order to actually load data into the timeline, the DLL contains a http module which we need to register in the web.config file. In your web.config file, find the <system.web> section and add:

</httpHandlers>

Once you have completed that, all you need now is to hit F5 and give the control a test. (If you get a dialog about modifying the web.config to enable debugging, just hit ok).

You should see something similar to:

A very basic timeline rendering events from the RSS feed you supplied.

Additional Usage

Once you managed to get the basic timeline rendering you will want to start to tweak the control. Here is the current complete list of properties available:

Property	Description
JSName	The name of the variable in javascript to represent our timeline. This should be set to a unique value per instance
LabelWidth	The width of the label
BubbleWidth	The typical width of the bubble
BubbleHeight	The typical height of the bubble
ParentElementID	The client side element to render the timeline into
LocalTimelineJSFolder	If you set the ScriptSourceLocation variable to local, you can set the root path to the timeline folder. Typically this will be the relative path from the root of the current applicaiton which contains the timeline-api.js file
ScriptSourceLocation	Allows you to choose remote vs local script source/ Remote location defaults to: http://simile.mit.edu/timeline/api/timeline-api.js
TimelineData	The root of our data source to add events to. This is your starting point for adding data.
Theme	The theme which will be used to render the timeline. Default is the ClassicTheme
EnableSearchAndFilter	Allows you to control the Search and Filter controls. Note: If this is enabled it will force the script source location to remote
DataSourceType	The type of data source.
Bands	A list of the bands to render. This is your starting point for adding bands of different types and time ranges. A zone is added to the specific band itself.
DataUrl	If you are using a remote or local data source (other than named) you must provide the URL to the resource to load
SearchAndFilterTag	The client side DOM element which to render the Search and Filter elements

The two key properties to notice are “TimelineData” and “Bands”.

Custom Timeline – HotZone

If you need to manipulate the basic bands in use, here is an example:

protected void Page_Load(object sender, EventArgs e) { if(!Page.IsPostBack) { TimelineNet.Library.Zone dayZone = new TimelineNet.Library.Zone(DateTime.Now.AddDays(-2), DateTime.Now, 10, TimelineNet.Library.Enums.TimelineDateTime.HOUR); HotZoneBand YEAR = new HotZoneBand(10, Enums.TimelineDateTime.YEAR, 100); HotZoneBand MONTH = new HotZoneBand(10, Enums.TimelineDateTime.MONTH, 100); HotZoneBand DAY = new HotZoneBand(80, Enums.TimelineDateTime.DAY, 100); YEAR.Overview = true; MONTH.Overview = true; YEAR.TrackGap = new decimal(0.5); MONTH.TrackGap = new decimal(0.5); MONTH.SynchWith = 0; YEAR.SynchWith = 0; this.Timeline1.Bands.Add(DAY); this.Timeline1.Bands.Add(MONTH); this.Timeline1.Bands.Add(YEAR); DAY.Zones.Add(dayZone); }

Here we are adding a year, month and day band. In the Day band we are adding a HotZone broken down by hour, this will have the effect of:

Notice that the top band breaks down to hour increments on the right side, a HotZone.

Custom Timeline – Named Events

Update the aspx file to simply be:

<cc1:Timeline Height="300" Width="100%" ID="Timeline1" runat="server" />

And then in the code behind we can do something like:

protected void Page_Load(object sender, EventArgs e) { if(!Page.IsPostBack) { Timeline1.DataSourceType = TimelineNet.DataSourceTypes.named; Timeline1.TimelineData = new TimelineData(); Timeline1.TimelineData.Add(new Event(DateTime.Now.AddDays(-5), DateTime.Now.AddDays(-1), false, "Hello World", null, "This is a sample event", null)); Timeline1.TimelineData.Add(new Event(DateTime.Now.AddDays(-1), DateTime.Now.AddDays(3), false, "Goodbye World", null, "This is another sample event", null)); } }

We change the DataSourceType to be a named data source, which means that we are going to rely on the fact that the Event Data will come directly and not automatically derived from an XML document or RSS feed. The next few lines above initialize the TimelineData object and then create two simple events. This will render as:

Whats left? A few of the bits that are still remaining to discuss include:1. I added a non-standard “GroupedEvent”. Which has the additional property of “GroupName”. This allows for a visual grouping by text color of the events in the timeline.2. Search and Filter controls can be turned on and off via the “EnableSearchAndFilter” property. Be sure to also set the “SearchAndFilterTag” property, which should be the name of a HTML DOM element on the page, which the Search and Filter controls will be rendered out to.

Rob Chartier ~ Contemplation... : Timeline

Timeline .NET