literyzjs-timeline/wiki/USAGE.md

Usage: v0.2.0.121 alpha

This is the usage guide for LiteRyzJS/Timeline, version 0.2.0.121 alpha.

Usage

LiteRyzJS.Timeline(el)

Creates a timeline.

Parameters

Parameter	Type	Description
el	string	Identifier of canvas element

Examples

<canvas id="myCanvas"></canvas>

var timeline1 = new LiteRyzJS.Timeline("myCanvas");

Clear()

Clear timeline and blank canvas.

Examples

timeline1.Clear();

Invalidate(redrawAxis, redrawMarkers)

Invalidates and redraws the canvas.

Parameters

Parameter	Type	Description
redrawAxis	bool	Redraw the whole canvas (with the axis and labels only)
redrawMarkers	bool	Clear the the contents of the graph and redrawn the markers

Examples

timeline1.Invalidate(true, true);

Load(date)

Set the start date of the timeline and load the start date.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The start date of the timeline

Examples

timeline1.Load("2023-10-08");

Show(date)

Load the timeline starting with the date.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date of the timeline

Examples

timeline1.Show("2023-10-08");

DateToString(date, pattern)

Convert a JavaScript date to string using the .NET standard format for date-time.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The start date of the timeline

Result

Returned a string of the date-time.

Examples

timeline1.DateToString(new Date(), "yyyy-MM-dd");

ConvertToDate(date)

Convert a date string "yyyy-MM-dd" into a JavaScript date object.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date

Result

Returned a JavaScript date object.

Examples

timeline1.ConvertToDate("2023-10-08");

CalcEndDate()

Calculates the end date displayed on the current view of the timeline.

Result

Returns a string of the laste date on-screen in "yyyy-MM-dd" format.

Examples

timeline1.DateToString(new Date(), "yyyy-MM-dd");

AddEvent(date, label, options)

Add an event marker to the timeline. A marker can contain multiple events.

Options

{
  Title: "",
  Description: "",
  Link: "",
  Tag: null
}

Parameters

Parameter	Type	Description
date	Date ("yyyy-MM-dd")	The date of the marker
label	string	The label of the marker, null to leave unchanged otherwise update existing label
Title	string	Title of the event
Description	string	Description of the event
Link	string	Link to the event
Tag	string	Extra data object for this event

Examples

  const markerName = "Random Marker #" + GetRandy(10000, 99999);

  timeline1.AddEvent(markerDate, markerName, { Title: markerName, Description: "This is a randomly generated marker" });

DeleteMarker(date)

Delete marker and all events on a date.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date

Examples

timeline1.DeleteMarker("2023-10-08");

UpdateLabel(date, label)

Update the label on a marker.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date
label	string	Label text

Examples

timeline1.UpdateLabel("2023-10-08", "New Label");

UpdateMarker(date, borderColour, backColour)

Update the style of a marker.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date
borderColour	Hex colour	Colour of the marker's border
backColour	Hex colour	Fill colour of the marker

Examples

timeline1.UpdateMarker("2023-10-08", "#E68422", "#FAE7D3");

FindDatePosition(date)

Find the position of the date on the timeline chart. Date must be within the display range of the chart.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date

Result

Null, if date not found or is not currently visible.

{
  Date: "yyyy-MM-dd",
  X: 0
}

Property	Type	Description
Date	Date (yyyy-MM-dd)	The date
X	integer	The horizontal locaton of the marker

Examples

const coords = timeline1.FindDatePosition("2023-10-08");

FindVisibleEvents()

Find all markers/events that are within the current visible date range.

Result

Null, if no markers found.

[{
  Date: date,
  Label: "",
  Position: { X: 0, Y: 0 },
  Events: [],
  HitBox: null,
  BorderColour: "#3A5D9C",
  BackColour: "#D4DEEF"
}]

Property	Type	Description
Date	Date (yyyy-MM-dd)	The date
Label	string	Text label of the marker
Position	Point { X: float, Y: float }	The location of the marker
Events	Array of Events	An array of events, see FindEvent.
HitBox	Rectangle { X: float, Y: float, W: float, H: float }	The hitbox or rectangle that repersents the marker and label
BorderColour	Hex colour	Colour of the marker border
BackColour	Hex colour	Fill colour of the marker

Examples

const visibleEvents = timeline1.FindVisibleEvents();

FindEvent(date)

Find a list of events by date (yyyy-MM-dd).

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date

Result

Null, if no events found.

[{
  Title: "",
  Description: "",
  Link: "",
  Tag: null
}]

Property	Type	Description
Title	string	Title of the event
Description	string	Description of the event
Link	string	Link to the event
Tag	string	Extra data object for this event

Examples

const events = timeline1.FindEvent("2023-10-08");

FindEventsByCoords(x, y)

Find a list of events by a point (x, y) on the chart.

Parameters

Parameter	Type	Description
date	Date (yyyy-MM-dd)	The date

Result

Null, if no events found. For results, see FindEvent.

Examples

const events = timeline1.FindEventsByCoords(400, 280);