Parameters

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

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

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

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

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

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

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)

Parameters

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

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

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

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

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

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()