Dipity Timelines JavaScript API Documentation

Resource Index

Getting Started

After obtaining developer keys, simply include the required javascript file, initialize your timeline object and make calls to the API. Please review the requirements that apply to all JS API calls, which are described below.

Authentication

Including Dipity JS API files and initializing our widget both require a valid developer key and sig. The key parameter is the API key listed on the developer keys page.

The sig parameter is a signature used to verify the authenticity of the request for the provided key. A signature is computed according to the following steps:

  1. Start with the secret, obtained from the developer keys page
  2. Append to the secret the domain that we have authorized for you to make API calls. (e.g. dipity.com or myapp.dipity.com
  3. Compute the MD5 checksum of the resulting string

The checksum computed in the final step is the value to provide for the sig parameter.

Include the javascript

Once you've figured out your signature, you'll need to include a single javascript file to get started. The file is located at:

http://www.dipity.com/js/api.js?key=[key]&sig=[sig]

Where [key] and [sig] are replaced with the keys and signatures described above.

Resource Documentation

The "Hello, World" of the Dipity JS API

The easiest way to see how the Dipity JS API works is to see a simple example.

<!DOCTYPE html>
<html>
<head>
<style type="text/css">
  html { height: 100% }
  body { height: 100%; margin: 0px; padding: 0px }
  #timeline { width:75%; height:500px; margin:50px auto; }
</style>
<script type="text/javascript"
    src="http://www.dipity.com/js/api.js?key=[key]&sig=[sig]">
</script>
<script type="text/javascript">
  function initialize() {
  
    // simple timeline initialization options
    var options = {
      'key':'[key]',
      'sig':'[sig]'
    };
    
    // add some events to initialization options
    options.data = {
      'events': [
        { 'eid':1, 'x': 861080400, 'title':'Hello, World' },
        { 'eid':2, 'x':1273942900, 'title':'Goodbye, World' }
      ]
    };
    
    // initialize the timeline
    var canvas = document.getElementById('timeline');
    var timeline = new dipity.widget(canvas,options);
    
    // programmatically add another event for fun
    timeline.addEvent({ 'eid':3, 
                        'title':'Got my first real 6-string', 
                        'x':-12873600, 
                        'date':'Summer of Sixty Nine' });
  }  
</script>
</head>
<body onload="initialize()">
  <div id="timeline"></div>
</body>
</html>

Even in this simple example, there are a few things to note:

  1. We declare the application as HTML5 using the <!DOCTYPE html> declaration.
  2. We include the Timeline API JavaScript using a script tag.
  3. We write a JavaScript function to initialize the widget.
    • We create a JavaScript object literal to hold a number of timeline properties as defined by the WidgetOptions specification.
    • We create a new Timeline Widget object from our WidgetOptions.
    • We programmatically add a new event to our timeline object.
  4. We create a div element named "timeline" to hold the Timeline.
  5. We initialize the timeline object from the body tag's onload event.

Examples in action

  1. The simple example above
  2. A more complex example with custom theming and more event details
  3. Another complex example with custom theming on individual events

Widget Class

A dipity widget object that can be used to display timelines built with event data specified by the developer. It can be instantiated using the method below.

dipity.widget(container,options)

container
An element in the DOM to place the widget into.
options
A set of initialization options as defined by the WidgetOptions specification

Add Event

Adds a new event to the dipity.widget object

addEvent(options)

options
A set of properties as defined by the EventData specifications

Remove Event

Removes an event from the dipity.widget object.

removeEvent(eid)

eid
The unique id of the event to remove

Scroll To

Scrolls to a specific timestamp on the dipity.widget object.

scrollTo(x)

x
A unix timestamp representing the time to scroll to.

WidgetOptions object specification

The options used when initializing a new timeline object.

Required Properties

key
Developer API Key
sig
Developer API Signature.

Optional Properties

defaultDate
A date defining the center of the timeline. If not provided, we will try to pick a center based on recent events.
defaultEventImage
An image that will be used as the default image for the default popups and flipbook/list visualizations. If not present, we will use a default image from dipity.com
defaultZoom
A default zoom level upon loading the timeline. If not provided, we will try to pick a fitting zoom level based on recent events. Options are: '30min', '1hr', '6hr', '12hr', '1day', '3day', '7day', '1mon', '3mon', '6mon', '1yr', '2yr', '5yr', '10yr', '25yr', '50yr', '100yr', '250yr', '500yr', '1000yr', '5000yr'
data
A WidgetData object to define the contents of the widget.
gmtOffset
The difference from Greenwich time (GMT) in hours. This should correlate to the timezone in which your events take place. Valid values range from -12 to 14. Defaults to 0, GMT.
intl
A key to translate the default text on the timeline to the language of your choice. We currently support en (English), fr (French), and es (Spanish). Defaults to en.
theme
Define an object to customize the look of the widget following the WidgetTheme specification.
themes
An object containing key value pairs to define multiple themes within a single timeline. This is useful for color coding certain events or groups of events. Each key takes a WidgetTheme object value. To set the default theme, use the key main.

WidgetData object specification

A collection of data to define the contents of the widget.

Optional Properties

events
An array of initial events following the EventData specification.

EventData object specification

The options used when initializing a new event object.

Required Properties

eid
A unique identifier for the event object. This can be numeric or a string.
x
A unix timestamp representing the time of the event. This is used to place the event object on the timeline.
title
A short title describing the event.

Optional Properties

author
A name to represent the author of a given event.
authorURL
If both an author and authorURL are provided, the author's name will be linked.
date
A display date to represent the timestamp of your event. If not present, we will generate this from the event's unix timestamp (x property).
description
A longer description to associate with the event. HTML is allowed.
img
The URL of an image to go along with a particular event.
ll
A comma separated latitude and longitude to display your event on a map.
specificity
If a display date is not given, you can define a specificity for the date we calculate from your unix timestamp (x property). Options are: n (minute), h (hour), d (day), m (month), y (year). Defaults to n (minute).
theme
If multiple themes have been defined in the WidgetOptions object, you can specify the key of the theme you'd like your event to reflect here.
v
A numeric score for an event. Events with higher scores will (vertically) take priority over those without scores. Defaults to 0 unless an event image is defined, then the default is 1.

WidgetTheme object specification

The options used for customizing the colors and elements within a widget.

Optional Properties

backgroundColor
A CSS-property to define the timeline's background color.
backgroundImage
The URL of an image to use as a timeline background.
bubbleDateColor
bubbleDateHoverColor
bubbleTitleColor
bubbleTitleHoverColor
chromeSelectedTabTextColor
chromeTextColor
flipbookSlideBackgroundColor
flipbookSlideHeaderBackgroundColor
flipbookSlideHeaderTextColor
popupBackgroundColor
popupLinkColor
popupSelectedTabBackgroundColor
popupSelectedTabTextColor
popupTabBackgroundColor
popupTabBorderColor
popupTabHeaderBackgroundColor
popupTabTextColor
popupTextColor
popupTitleBackgroundColor
popupTitleTextColor
spriteAtlas
The URL of an image that can be defined for customizing the colors and elements within the timeline widget. Transparent PNGs are optimal. A Photoshop template and examples are available in the JavaScript SDK.
spriteAtlasHR
The URL of an image that can be defined for customizing the color and style of the horizontal rules across widget. A Photoshop template and examples are available in the JavaScript SDK.
timescaleTextColor