# Usage: v0.2.0.121 alpha

This is the usage guide for [LiteRyzJS/Timeline](/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

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

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

### Clear()

Clear timeline and blank canvas.

#### Examples

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
{
  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

```javascript
  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

```javascript
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

```javascript
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

```javascript
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.

```javascript
{
  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

```javascript
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.

```javascript
[{
  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

```javascript
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.

```javascript
[{
  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

```javascript
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

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