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 histropediaJS file.

The following two dependencies need to be loaded on the page before histropediaJS:

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

<script src="js/jquery-3.5.1.min.js"></script>
<script src="js/jquery.mousewheel-3.1.13.min.js"></script>
<script src="js/histropedia-1.2.0.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.

Download HistropediaJS and all required dependencies here.

Alternatively, you can access HistropediaJS via our CDN:

https://cdn.histropedia.com/histropedia-1.2.0.min.js



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,
	enableCursor: true,
	draggingVicinity: true, // new values // changed default
	shiftBceDates: false, // new
	initialDate: {
		year: 1990,
		month: 1,
		day: 1
	},
	zoom: {
		initial: 34,
		minimum: 0,
		maximum: 123,
		wheelStep: 0.1,
		wheelSpeed: 3, // changed default
		unitSize: {
			showMinorLabels: 48,
			minimum: 8
		}
	},
	style: {
		mainLine: {
			visible: true,
			size: 8 // changed default
		},
		draggingHighlight: {
			visible: true,
			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: {
				font: "normal 10px Calibri",	
				color: "#333",
				futureColor: "#ccc",
				textAlign: "start",
				offset: {
					x: 4,
					y: 0
				},
				bceText: "",
				thousandsSeparator: ",",
				yearPrefixes: {
					ka: { label: "ka", value: 1000, minDivision: 1000 },
					Ma: { label: "Ma", value: 1e6, minDivision: 1e5 },
					Ga: { label: "Ga", value: 1e9, minDivision: 1e8 }
				}
			},
			major: {
				font: "normal 16px Calibri",	
				color: "#000",
				futureColor: "#ccc",
				textAlign: "start",
				offset: {
					x: 4,
					y: 0
				},
				bceText: " ʙᴄᴇ",
				thousandsSeparator: ",",
				yearPrefixes: {
					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,
		distanceToMainLine: 400,
		collectOngoing: false,
		autoStacking: {
			active: true,
			rowSpacing: 50,
			range: Histropedia.RANGE_ALL,
			fitToHeight: true,
			topGap: 10 // new values
		},
		periodLine: {
			spacing: 4,
			thickness: 10,
			stacking: {
				sorter: Histropedia.ARTICLE_FROM_SORTER,
				reverseOrder: false
			},
			defaultHide: false
		},
		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) { ... } 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) { ... } Function executed when a user clicks on an article.
article is the object representing the article that was clicked
onArticleDoubleClick function(article) { ... } Function executed when a user double clicks on an article.
article is the object representing the article that was double clicked
onRedraw new function(event) { ... } Function executed when each timeline redraw is complete.
The event object has the following properties:
  • canvasContext: Use for drawing to the timeline canvas
  • drawCycleContext: Object with cached pixel coordinates for each timeline marker date
  • top: The top coordinate of the base of the timeline


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},
	hoverStyle: {style options} // new
	activeStyle: {style options}


Article Style Options

The syntax of the object shown below is used for styling articles on your timeline. All of the same options can be used to define the style, hoverStyle and activeStyle.
The hoverStyle and activeStyle only need to include overrides to the normal style. The order in which styles are overriden is summarised below:

style hoverStyle activeStyle

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 for the whole timeline, or the .setOption, .setStyle, .setActiveStyle and .setHoverStyle article methods to change individual article styles.

The system default style, hoverStyle 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",
			align: "left", // new
			baseline: "middle", // new
			margin: 10,                         
			lineHeight: 18,                      
			numberOfLines: 2                      
		}
	},
	subheader: {
		height: 30,
		color: '#555',
		text: {
			font: "normal 11px 'Segoe UI'",
			color: "#eee",
			align: "left", // new
			baseline: "middle", // new
			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: {                        
		width: 16,                    
		margin: 3
	}	
}

// Default hoverStyle // new
var hoverStyle = {
	color: "#a6c6e2"
}

// 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 initialised a new timeline, you can call any of the following methods from your 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)
easing Animation easing using either "swing" or "linear" (default: "swing")
Note: Any custom JQuery easing functions you have installed can also be used here
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: 400,
	offsetX: 50,
	complete: function() { console.log("done!" }
}
timeline.goToDateAnim(date, options)

Parameters

pixel (required) The number of pixels to move the timeline by. Use positive numbers to go forward in time, or negative numbers to go backward.
options
Settings object for the animation, with the following optional properties:

duration Duration of the animation in milliseconds (default: 2000)
easing Animation easing using either "swing" or "linear" (default: "swing")
Note: Any custom JQuery easing functions you have installed can also be used here
complete Function to call when animation is complete

Examples

// 50 pixels backward in time (the viewport "moving" to the left)
timeline.goToPixelAnim(-50)

// 1 million pixels forward in time (the viewport "moving" to the right)
timeline.goToPixelAnim(1e6)

// whole canvas width, useful for creating next/previous timeline navigation arrows!
timeline.goToPixelAnim(timeline.width)

// ... with all available options set
var options = {
	duration: 400,
	easing: "linear",
	complete: function() { console.log("done!" }
}
timeline.goToPixelAnim(timeline.width, 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)
        

Parameters

redrawFunction Optionally provide a specific redraw function to use. This can be one of the built in functions listed below (.redraw, .repositionRedraw, .defaultRedraw) or any custom made redraw function of your own.
If no function is specified .repositionRedraw is used.

Details

This method can be used to render the results after making dynamic changes to the timeline. It gives a significant performance advantage over directly calling any of the redraw functions. This is most noticeable when the timeline is animating, as .requestRedraw will incorporate the redraw request into any ongoing animation.

Examples

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

// redraw the timeline using the default `repositionRedraw` function
timeline.requestRedraw()

// as the timeline start date and zoom level have not changed, we can specify
// the most basic timeline redraw for a performance boost
timeline.requestRedraw(timeline.redraw)

// Alternatively, for a full redraw including re-stacking of event cards on the timeline
timeline.requestRedraw(timeline.defaultRedraw)

        

Details

This is the fastest but most basic timeline redraw function.
For best performance, use the .requestRedraw method rather than calling redraw functions directly, e.g. timeline.requestRedraw(timeline.redraw)

If the start date and/or zoom level have changed, use .repostionRedraw or .defaultRedraw instead.

Examples

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

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

// However, for best performance call via the .requestRedraw method instead
timeline.requestRedraw(timeline.redraw)
        

Details

This method performs all the same steps as the basic .redraw but it also re-calculates the origin location for all articles on the timeline. This is needed when the timeline start date and/or zoom level changes.

For best performance, use the .requestRedraw method rather than calling redraw functions directly, e.g. timeline.requestRedraw()
Note: This is equivalent to timeline.requestRedraw(timeline.respositionRedraw) as .repositionRedraw is the default.

Examples

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

// redraw to see the changes
timeline.repositionRedraw()

// However, for best performance call via the .requestRedraw method instead
timeline.requestRedraw() 

// Note: No need to pass timeline.repositionRedraw as an argument as it is the
// default for the requestRedraw method

Details

This is the slowest but most complete redraw function. It performs all the same steps as .repositionRedraw but it also re-stacks the articles on the timeline by rank (only relevant when options.article.autoStacking.active = true).

For best performance, use the .requestRedraw method rather than calling redraw functions directly, e.g. timeline.requestRedraw(timeline.defaultRedraw)

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.major.color = "green"

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

// However, for best performance call via the .requestRedraw method instead
timeline.requestRedraw(timeline.defaultRedraw)



Article Methods

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

Note: To get articles, use the .getArticleById and .getActiveArticle Timeline methods, or access the main array directly in the articles property of your timeline (e.g. myTimeline.articles[0]).

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 for this article. To see the actual computed style after combination with the default styles, 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 borderColor = article.setStyle("border.color")

// 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 hoverStyle settings for this article. To see the actual computed hoverStyle after combination with the default styles, use the hoverStyle property (e.g. article.hoverStyle).

Examples

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

// set single hover style option
article.setHoverStyle("star.width", 25)

// set multiple hover style options
article.setHoverStyle({
	color: "#9b1000",
	subheader: {height: 60},
	shadow: {x: 5, y: 10, color:"green"}
})

// get value for a given hover style option
var hoverBorderColor = article.setHoverStyle("border.color")

// get actual computed hover style, after combination with timeline defaults
var computedHoverStyle = article.hoverStyle
        

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 for this article. To see the actual computed activeStyle after combination with the default styles, use the activeStyle property (e.g. article.activeStyle).

Examples

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

// set single active 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 value for a given active style option
var activeBorderColor = article.setActiveStyle("border.color")

// get actual computed active style after combination with timeline defaults
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 your 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 'origin' position.
The 'origin' 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 'origin' 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 your 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 'origin' 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 receive 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 excited when people want to use HistropediaJS and will be happy to help however we can!

Contact Us