Documentation


HistropediaJS is a JavaScript library that makes it easy to generate interactive timelines within a normal web page. This documentation page lists all of the main options and functions you can use to interact with the library, starting with the basics of getting started just below.

Don't hesitate to contact us if you need any help with anything, or just to want to say hi and discuss a few ideas!


Loading the HistropediaJS library

To start using HistropediaJS on a webpage, just include a <script> tag pointing to the location of your histropedia.js file.

The following two dependencies need to be loaded on the page before your histropedia.js file:

Here's an example HTML snippet for loading the library and its dependencies:

<script src="js/jquery-3.1.0.min.js"></script>
<script src="js/jquery.mousewheel-3.1.13.min.js"></script>
<script src="js/histropedia-1.0.6.min.js"></script>

HistropediaJS renders in HTML5 canvas and does not require any CSS. All styling is done via the Timeline options and Article Style options.

You can download HistropediaJS and all required dependencies here


Initialising a new Timeline

Create a new timeline and store to a variable using the syntax shown below. You can create any number of timelines on a single page using different variable names.

var myTimeline = new Histropedia.timeline (container, options)

container DOM element to place the timeline within
options Timeline options object to determine the initial settings for the timeline (see full options below)
Note: you can use { } to use the defaults for all settings

After initialisation, you can access all properties and methods of the main timeline object using your assigned variable. For example,

myTimeline.options  //options object used by myTimeline

myTimeline.articles //array of currently loaded articles

myTimeline.setOption("width", 1000) //set new timeline options

myTimeline.getArticleById(17) //get articles on the timeline

Adding Articles to the Timeline

Once a timeline has been initialised you can use the .load method to add "articles" to it (the items that are displayed on your timeline).

myTimeline.load(articles)
articles Array of articles to load on to the timeline. Each article is an object containing the data needed to render it on the timeline (see full options below)

Note: Throughout this documentation we will refer to the entire object as an "article" and what is visibly rendered on the timeline as an "Event Card".


Timeline Options

An object containing all settings for initialising a new timeline. The options shown below are the defaults, which will be used for any options that are not specified when initialising a new timeline.

Hover over the options for description
var DEFAULT_OPTIONS = {
	width: 1000,
	height: 500,
	verticalOffset: 40,
	enableUserControl: true, //new
	enableCursor: true, //new
	draggingVicinity: {up: 460, down: 40},
	initialDate: {
		year: 1990,
		month: 1,
		day: 1
	},
	zoom: {
		initial: 34,
		minimum: 0,
		maximum: 123, //changed default
		wheelStep: 0.1,
		wheelSpeed: 1,
		unitSize: { //new
			showMinorLabels: 48, //new
			minimum: 8 //new
		}
	},
	style: {
		mainLine: {
			visible: true, //new
			size: 7
		},
		draggingHighlight: {
			visible: true, //new
			area: { up: 0, down: 40 },
			color: "rgba(237, 247, 255, 0.5)"
		},
		marker: {
			minor: {
				height: 12,	
				color: "#6097f2",
				futureColor: "#ccc"
			},
			major: {
				height: 30,
				color: "#0c3a88",
				futureColor: "#ccc"
			}
		},
		dateLabel: {
			minor: { //new
				font: "normal 10px Calibri",	
				color: "#333",
				futureColor: "#ccc",
				textAlign: "start", //new
				offset: { //new
					x: 4,
					y: 0
				},
				bceText: "", //new
				thousandsSeparator: ",", //new
				yearPrefixes: { //new
					ka: { label: "ka", value: 1000, minDivision: 1000 },
					Ma: { label: "Ma", value: 1e6, minDivision: 1e5 },
					Ga: { label: "Ga", value: 1e9, minDivision: 1e8 }
				}
			},
			major: { //new
				font: "normal 16px Calibri",	
				color: "#000",
				futureColor: "#ccc",
				textAlign: "start", //new
				offset: { //new
					x: 4,
					y: 0
				},
				bceText: " ʙᴄᴇ", //new
				thousandsSeparator: ",", //new
				yearPrefixes: { //new
					ka: { label: "ka", value: 1000, minDivision: 1e5 },
					Ma: { label: "Ma", value: 1e6, minDivision: 1e6 },
					Ga: { label: "Ga", value: 1e9, minDivision: 1e9 }
			}
		}
	},
	article: {
		density: Histropedia.DENSITY_ALL,
		draggable: true, //new
		distanceToMainLine: 400,
		collectOngoing: false,
		autoStacking: {
			active: true,
			rowSpacing: 50,
			range: Histropedia.RANGE_ALL,
			fitToHeight: true,
			topGap: 10
		},
		periodLine: {
			spacing: 4,
			thickness: 10,
			stacking: {
				sorter: Histropedia.ARTICLE_FROM_SORTER,
				reverseOrder: false
			},
			defaultHide: false //new
		},
		animation: {
			move: {
				active: true,
				duration: 1500,	
				easing: "swing"	
			},
			fade: { 
				active: true,		
				duration: 1500,	
				easing: "swing"	
			}
		},
		defaultStyle: {style options},  
		defaultActiveStyle: {style options}
	}
}

Additional event handler options

The following 3 properties can also be added to your timeline options. These are used to attach custom functions to events fired by the timeline.

See our Events and handlers example for a live demo.

OPTION SYNTAX DESCRIPTION
onSave function(state) { code block } function executed on every state change for the timeline. ‘state’ is an object with all current timeline data (zoom level, start date, article ids loaded etc)
onArticleClick function(article) { code block } function executed when a user clicks on an article. ‘article’ is the object representing the article that was clicked
onArticleDoubleClick function(article) { code block } function executed when a user double clicks on an article. ‘article’ is the object representing the article that was double clicked

Article Options

The following object shows the syntax for creating new article(s) to add to a timeline. It consists of all data needed to render a single article on the timeline, as well as style options to customise the look of the Event Card in its normal and active states.

Note: Styles added in the article options will override the defaults defined in your timeline options.

Properties highlighted in red are required for each article.

Hover over the options for description
var newArticle = {
	id: 1,
	title: "Alfred Hitchcock",
	subtitle: "Film director (1899 – 1980)",
	from: {
		year: 1899,
		month: 8,
		day: 13,
		precision: Histropedia.PRECISION_DAY
	},
	to: {
		year: 1980,
		month: 4,
		day: 29,
		precision: Histropedia.PRECISION_DAY
	},
	isToPresent: false,  
	imageUrl: "https://example.com/image.jpg",
	rank: 100,
	starred: false,
	hiddenByFilter: false,
	hidePeriodLine: false,
	style: {style options},  
	activeStyle: {style options}
}

Article Style Options

The syntax of the object shown below is used for styling articles on your timeline. It can be used to define a style and activeStyle (style when an article is selected in the user interface). The activeStyle only needs to contain overrides to the normal style.

The article style options can be used to define styles before intialising a new timeline as follows:

After initialisation, you can use the setOption timeline method to change the defaults, or the setOption, setStyle and setActiveStyle article methods to change individual article styles.

The system default style and activeStyle options are shown below. These will be used for any options you do not define yourself.

See our Article Styling example for a live demo showing a gallery of styles you can use to get started.

Hover over the options for description
	//Default style
  	var style = {
		color: '#e9e9e9',
		width: 150,                         
		topRadius: 3,                             
		maxImageHeight: 400,                    
		header: {                                 
			height: 50,                            
			text: {                                   
				font: "normal 14px 'Segoe UI'",     
				color: "#333",                     
				margin: 10,                         
				lineHeight: 18,                      
				numberOfLines: 2                      
			}
		},
		subheader: {                              
			height: 30,                           
			color: '#555',
			text: {                                   
				font: "normal 11px 'Segoe UI'",     
				color: "#eee",                       
				margin: 10                          
			}
		},
		shadow: {                                
			x: 0,                                 
			y: 0,                                 
			amount: 0,                            
			color: '#000'                        
		},
		border: {
			color: '#ddd',
			width: 1,
		},
		connectorLine: {                         
			offsetX: 18,                   
			offsetY: -20,
			thickness: 1,
			arrow: {
				width: 16, 
				height: 45 
			}
		},
		star: { //new                        
			width: 16, //new                    
			margin: 3 //new
		}	
	}
	
	//Default activeStyle
	var activeStyle = { 
		color: "#337ab7", 
		header: { 
			text: {
				color: "#fff", 
			}
		},
		subheader: { 
			color: '#333',
		},
		shadow: {
			x: 3,
			y: 3,
			amount: 5,
			color: '#333'
		},
		border: {
			width: 2,
			color:"#2e6da4",
		},
		connectorLine: {
			thickness: 2,
		}
	}

Timeline Methods

Once you have initalised a new timeline, you can call any of the following methods from you're chosen timeline variable name.

Parameters

option (required) Either a timeline options object, or string to specify a path within the timeline options using dot notation.

A path string can be used with the value argument to set an option, or without the second parameter to get the current value.

value Value to set for the given option. Only applicable when string notation has been used to specify a property.

Return value: Current value

Value for the given option. Only returned when option is a path string, and no value parameter has been given.

Note: This is just provided for convenience when exploring options. It's much more efficient to use the .options property for this (e.g. myTimeline.options.style).

Examples

// set new width and height
timeline.setOption({width: 700, height:400})

// set mainLine size
timeline.setOption("style.mainLine.size", 10)  

// set default article subheader height and colour
timeline.setOption("article.defaultStyle.subheader", {height: 20, color: "#EEE"})

// get current animation settings
var animSettings = timeline.setOption("article.animation")

Parameters

id (required) Unique id of an article currently loaded on the timeline (as defined in your article data)

Return value: Article

The article object matching the given id, which can then be used to access its data and call article methods. Returns false if no matching article found.

Examples

// get the article with id=1
var article = timeline.getArticleById(1)

// check article data
console.log(article.data) 

// call article methods
article.setOption("hidePeriodLine", true)

Return value: Article

The object representing the currently active article, which can then be used to access its data and call article methods.

Examples

// get the currently active article
var article = timeline.getActiveArticle()

// check article data
console.log(article.data) 

// call article methods
article.setOption("hidePeriodLine", true)

Parameters

dmy (required) Destination date given as a Histropedia Dmy object using the syntax: new Histropedia.Dmy(year, month, day).
By default, the specified date will be on the left edge of the canvas when the animation is complete.
options
Settings object for the animation, with the following optional properties:

duration Duration of the animation in milliseconds (default: 2000)
offsetX Offset in pixels to adjust where the destination date will end up on the screen (default: 0)
complete Function to call when animation is complete

Examples

// create Dmy for 5th Jan 1970
var date = new Histropedia.Dmy(1970,1,5)

// pan to date, with date located on left edge of canvas
timeline.goToDateAnim(date)

// ... with date located in centre of the canvas
timeline.goToDateAnim(date, { offsetX: timeline.width/2 })

// ... with all options set
var options = {
	duration: 5000,
	offsetX: 50px,
	complete: function() { console.log("done!" }
}
timeline.goToDateAnim(date, options)

Parameters

date (required) Destination date can be given as a string using the syntax "yyyy-mm-dd", or as a Histropedia Dmy object using new Histropedia.Dmy(year, month, day).
By default, the specified date will be on the left edge of the canvas.

Note: Month and Day are optional, they will both default to 1 if not specified (e.g. "1935" for 1st Jan 1935, or "1935-3" for 1st March 1935).
offsetX
Offset in pixels to adjust where the destination date will end up on the screen (default: 0).

Examples

// create Dmy for 5th Jan 1970
var date = new Histropedia.Dmy(1970,1,5)

// jump to date, with date located on left edge of canvas
timeline.setStartDate(date)

// ... with date located in centre of the canvas
timeline.setStartDate(date, timeline.width/2)

// set date using string notation 
timeline.setStartDate("1970-6") //1st June 1970

// set BC date using string notation 
timeline.setStartDate("-500-3-25") //25th March 500BC

Parameters

zoom (required) Zoom is given as a decimal number between 0 (most zoomed in) and 123 (most zoomed out).

Note: Zoom will be restricted to the range defined by options.zoom.minimum and options.zoom.maximum in your Timeline options.
centrePixel
Position of the zoom centre, given as the number of pixels from the left edge of the canvas. The default value is half the width of your timeline (i.e. zooming from the centre of the canvas).

Note: The date where the zoom centre is will always remain in the same location on the screen after the zoom action is complete.

Examples

// set zoom level 13.5, zooming from the centre of the canvas
timeline.setZoom(13.5)

// ... zooming from the left edge of the canvas
timeline.setZoom(13.5, 0)

// ... zooming from the right edge of the canvas 
timeline.setZoom(13.5, timeline.width)
        

Details

This method can be used to render the results after making a series of dynamic changes to the timeline, so is often needed when creating you're own custom functions (along with the defaultRedraw method listed below).

Examples

// hide currently active article and set date labels to green 
timeline.getActiveArticle().hiddenByFilter = true
timeline.options.style.dateLabel.color = "green"

// redraw to see the results on the timeline
timeline.redraw()

Details

This method performs all the same steps as .redraw() but it also re-stacks the articles on the timeline by rank (only when options.article.autoStacking.active = true).

In short, use .defaultRedraw() when you want to re-stack the articles after your changes, and normal .redraw() if not.

Note: defaultRedraw() happens automatically whenever the end user zooms or scrolls on the timeline.

Examples

// hide currently active article and set date labels to green 
timeline.getActiveArticle().hiddenByFilter = true
timeline.options.style.dateLabel.color = "green"

// redraw to see the changes, with re-stacked Event Cards now that one is hidden 
timeline.defaultRedraw()

Article Methods

You can call the following methods from any article loaded on your timeline.

Note: You can get articles using the getArticleById and getActiveArticle Timeline methods, or by accessing the main array in the articles property of your timeline (e.g. myTimeline.articles).

Parameters

option (required) Either an article options object, or string to specify a path within the article options using dot notation.

A path string can be used with the value parameter to set an option, or without the second parameter to get the current value.

value Value to set for the given option. Only applicable when string notation has been used to specify a property.

Return value: Current value

Value for the given option. Only returned when option is a path string, and no value parameter has been given.

Note: This is just provided for convenience when exploring options. It's much more efficient to use the .data property for this (e.g. article.data.style).

Examples

// get an article to work with from "myTimeline"
var article = myTimeline.getActiveArticle()

// set new group of options
article.setOption({
	title: "New title",
	subtitle:"2005 - 2007",
	from: {year: 2005},
	to: {month:3, day: 16}
})

// set new start year with string input
article.setOption("from.year", 2005) 


// get current rank
var rank = article.setOption("rank")

Parameters

option (required) Either an article style object, or string to specify a path within the article style options using dot notation.

A path string can be used with the value parameter to set an option, or without the second parameter to get the current value.

value Value to set for the given option. Only applicable when string notation has been used to specify a property.

Return value: Current value

Value for the given style option. Only returned when option is a path string, and no value parameter has been given.

Note: This will return the individual style settings the article has set. To check the actual computed style after combination with the default style, use the .style property (e.g. article.style).

Examples

// get an article to work with from "myTimeline"
var article = myTimeline.getArticleById(1)

// set single style option
article.setStyle("border.width", 3)

// set multiple style options
article.setStyle({
	color: "#9b1000",
	header: {height: 60},
	shadow: {x: 5, y: 10, color:"blue"}
})

// get individual article style option 
var borderStyle = article.setStyle("border")

// get the actual computed style
var computedStyle = article.style
        

Parameters

option (required) Either an article style object, or string to specify a path within the article style options using dot notation.

A path string can be used with the value parameter to set an option, or without the second parameter to get the current value.

value Value to set for the given option. Only applicable when string notation has been used to specify a property.

Return value: Current value

Value for the given style option. Only returned when option is a path string, and no value parameter has been given.

Note: This will return the individual activeStyle settings that the article has set. To check the actual computed activeStyle after combination with the default style and activeStyle settings), use the .activeStyle property (e.g. article.activeStyle).

Examples

// get an article to work with from "myTimeline"
var article = myTimeline.getActiveArticle()

// set single style option
article.setActiveStyle("border.width", 3)

// set multiple active style options
article.setActiveStyle({
	color: "#9b1000",
	header: {height: 60},
	shadow: {x: 5, y: 10, color:"blue"}
})

// get article's own active style option
var borderStyle = article.setActiveStyle("border")

// get actual computed active style
var computedActiveStyle = article.activeStyle
        

Parameters

position (required) Object with left and top properties to specify the relative coordinates of the top left corner of the Event Card after the movement.

Note: Both properties default to the current value, so you only need to provide one of them if the other is staying the same.

Details

This method can be used to place an article's Event Card in any part of the timeline canvas, whilst keeping it connected to it's corresponding date on the timeline.

To see the Event Card in the new position you will need to use the redraw Timeline method. Any interaction with the timeline by the end user will also trigger a redraw.

Note: If you're timeline has autoStacking active in the Timeline options (the default setting), then the Event Card will return to its default position once the user zooms or scrolls the timeline. You can disable autoStacking if you want full control over event placement on the screen.

Examples

// get an article to work with from "myTimeline"
var article = myTimeline.getActiveArticle();

// move Event Card to top left corner of the timeline canvas
article.moveTo({left:0, top:0})
myTimeline.redraw()

// move horizontally only
article.moveTo({left:60})
myTimeline.redraw()

// move vertically only
article.moveTo({top:100})
myTimeline.redraw()     

Parameters

offset (required) Object with left and top properties to specify the Event Card's offset from the 'default' position.
The 'default' position is directly above the article's start date on the timeline (with a vertical connector line), and at a height defined by the article.distanceToMainLine setting in the Timeline options.

Note: Both properties default to the current value, so you only need to provide one of them if the other is staying the same.

Details

This method can be used to place an article's Event Card in any part of the timeline canvas, whilst keeping it connected to it's corresponding date on the timeline.

As the offset is relative to the 'default' position, using left = 0 will place the Event Card directly above it's start date (with vertical connector line). Using top=0 will place the event card at the default height (determined by the article.distanceToMainLine setting in your Timeline options)

To see the Event Card in the new position, use the redraw Timeline method. Any interaction with the timeline by the end user will also trigger a redraw.

Note: If you're timeline has autoStacking active in the Timeline options (the default setting), then the Event Card will return to its default position once the user zooms or scrolls the timeline. You can disable autoStacking if you want full control over event placement on the screen.

Examples

// get an article to work with from "myTimeline"
var article = myTimeline.getActiveArticle()

// move Event Card to 'default' position
article.moveToOffset({left:0, top:0})
myTimeline.redraw()

// if left is 0, Event Card stays above start date (vertical date connector)
article.moveToOffset({left:0, top: 60})
myTimeline.redraw()

// if left is not 0, date connector will be at an angle
article.moveToOffset({left: 100, top:-250})
myTimeline.redraw()

More Documentation and Examples Coming Soon...

HistropediaJS has a huge range of functionality, so there is a lot more to discover that is not listed on this page yet. We are updating the documentation regularly, so do come back and have a look from time to time, or sign up for our newsletter below to recieve updates.

In the meantime please don't hesitate to get in touch if you need anything. Whatever the scale of your project we are always exctided when people want to use HistropediaJS and will be happy to help however we can!

Contact Us