Configuring Plugin Options
Configuring Plugin Options
You can pass options on plugin initialization. For example:
$("#myTimeline").timeline({
type: "bar",
startDatetime: "2019-03-04 00:00",
scale: "month",
rows: 6,
})
The option values that can be set are as follows. If the setting is omitted, each default value is specified.
| Option | Type | Default | Description |
|---|---|---|---|
| type | string | “bar” | View type of timeline event is either “bar” or “point” or “mixed“. The type of “mixed” has been available since version 2.0.0. |
| scale | string | “day” | Timetable’s minimum level scale. For more detail, refer to the scalable setting. |
| startDatetime | string | “currently” | Beginning DateTime of timetable on the timeline object. When the primitive value “currently” is used, the current DateTime is automatically set. |
| endDatetime | string | “auto” | Ending DateTime of timetable on the timeline object. When the primitive value “auto” is used, the date and time for the maximum limit prescribed for each specified scale are automatically set from the date and time specified by startDatetime. |
| headline | object | (detail) | Define the content display such as the heading of the top on the timeline object. For more detail, refer to the headline. |
| footer | object | (detail) | Define the content display such as the footer of the bottom on the timeline object. For more detail, refer to the footer. |
| range | number/string | 3 | Override the scale range of the timeline to be rendered when endDatetime is undefined or “auto” |
| sidebar | object | (detail) | Define the content display as the sidebar of the left on the timeline object. For more detail, refer to the sidebar. |
| rows | number/string | “auto” | Rows of timeline event area. |
| rowHeight | number | 48 | Height (pixel) of one row. |
| width | number/string | “auto” | Fixed width (pixel) of the timeline object. |
| height | number/string | “auto” | Fixed height (pixel) of the timeline object. Defaults to rows * rowHeight. |
| minGridSize | number | 30 | Override value of minimum size (pixel) of timeline grid. |
| marginHeight | number | 2 | Margin (pixel) of top and bottom of events on the timeline. |
| ruler | object | (detail) | Define the content display the ruler of the timetable on the timeline object. For more detail, refer to the ruler. |
| rangeAlign | number/string | “latest” | Adjust the position of the timetable in the first view of the timeline object. Possible setting values are “left” of “begin“, “center“, “right” or “end“, “current” or “currently“, “latest” and number of specific event id. |
| loader | string | “default” | Define the loader shown while loading timeline object, possible setting values are “default“, false and selector of your custom loader element. Also, the default preloading animation has changed since version 2.0.0. |
| loadingMessage | string | (none) | You can append to the specific content into the default preloading element. It will stop the default preloading animation if set this property. This property added since version 2.0.0. |
| hideScrollbar | boolean | false | Whether or not to display the scroll bar displayed when the width of the timeline overflows (even if it is set to non-display, it will not function depending on the browser). |
| eventMeta | object | (detail) | You can display meta on an event node block when the timeline type is “bar”. For more detail, refer to the event meta. |
| eventData | array<object> | (none) | There’s able to include any initial events into the default option. You should see the “Event Parameters” section about the definition of event objects in an array. This property added since version 2.0.0. |
| effects | object | (detail) | You can control some behaviors and view of the timeline by this property. For more details, refer to the effects. This property added since version 2.0.0. |
| colorScheme | object | (detail) | You can overwrite defaults UI color of the event nodes. Furthermore since version 2.1.0, you can set all color scheme of the timeline instance. |
| storage | string | “session” | Specification of Web storage to cache event data, defaults to sessionStorage. |
| reloadCacheKeep | boolean | true | Whether to load cached events during reloading, the cache is discarded if false. |
| zoom | boolean | false | Whether to use the ability to zoom the scale of the timeline by double clicking on any scale on the ruler. |
| wrapScale | boolean | true | Whether wrapping new scale in the timeline container when zoom. |
| firstDayOfWeek | number | 0 | There’s define a start day of one week for the week scale on the timeline. Defaults to 0 that equal Sunday. This property added since version 2.0.0. |
| engine | string | “canvas” | Choose dependent module to the core as a rendering engine. It’ll be “canvas” or “d3.js”; Maybe add in future version. |
| debug | boolean | false | Enable to debug mode if true then output logs for debugging to console. Defaults to false. |
Note: The following options which was effective in version 1.x has been departed. “datetimeFormat”, “datetimePrefix”, “duration”, “showPointer”, “httpLanguage”, “i18n”, “langDir”, “minGridper”, “minuteInterval”, “naviIcon”, “showHeadline”, “zerofillYear”.
Note: The type of “mixed” is shown the events of “bar” type that has an interval and the events of “point” type that enabled the starting DateTime only, together on one timeline container.
Scalable Settings
Since the plugin version 2.x, it has been supported scales of the timeline object as follows.
| Scale | Available Value(s) | Limit Scale Grids (when “auto”) |
|---|---|---|
| Millennium | “millennium” / “millenniums” / “millennia” | 100; In other words it’s 100000 years. |
| Century | “century“ | 500; In other words it’s 50000 years. |
| Decade | “decade” / “decennium” | 500; In other words it’s 5000 years. |
| Lustrum | “lustrum“ | 500; In other words it’s 2500 years |
| Year | “year” / “years” | 500; In other words it’s 500 years |
| Month | “month” / “months” | 540; In other words it’s 45 years |
| Week | “week” / “weeks” | 530; In other words it’s 10 years |
| Weekday | “weekday” | Undefined |
| Day | “day” / “days” | 366; In other words it’s about 1 year |
| Hour | “hour” / “hours” | 720; In other words it’s 30 days |
| Quarter-Hour | “quarter-hour” / “quarter-hours” | 720; In other words it’s 7.5 days |
| Half-Hour | “half-hour” / “half-hours” | 720; In other words it’s 15 days |
| Minute | “minute” / “minutes” | 720; In other words it’s 12 hours |
| Second | “second” / “seconds” | 900; In other words it’s 15 minutes |
| Millisecond | “millisecond” / “milliseconds” / “millisec” / “millisecs” | Undefined |
Headline
| Property Name | Type | Default | Description |
|---|---|---|---|
| display | boolean | true | This property is a toggle to whether or not to display the entire headline. If set to false headline is not shown. |
| title | string | (none) | Contents displayed as a heading. |
| range | boolean | true | Whether to display timetable range of timeline object as meta information in headline. |
| locale | string | “en-US” | This value is enabled if range is true, then it is instead of the locales argument to Date.prototype.toLocaleString([locales[, options]]). For more detail. |
| format | object | (detail) | This value is enabled if range is true, then it is instead of the options argument to Date.prototype.toLocaleString([locales[, options]]). For more detail. |
For example:
let options = {
headline: {
display: true,
title: "My Sample Timeline",
range: true,
local: "en-GB",
format: {
timeZone: "UTC", hour12: false,
}
},
}
Footer
| Property Name | Type | Default | Description |
|---|---|---|---|
| display | boolean | true | This property is a toggle to whether or not to display the entire footer. If set to false footer is not shown. |
| content | string | (none) | Contents displayed on the footer. |
| range | boolean | true | Whether to display timetable range of timeline object as meta information in footer. |
| locale | string | “en-US” | This value is enabled if range is true, then it is instead of the locales argument to Date.prototype.toLocaleString([locales[, options]]). For more detail. |
| format | object | (detail) | This value is enabled if range is true, then it is instead of the options argument to Date.prototype.toLocaleString([locales[, options]]). For more detail. |
For example:
let options = {
footer: {
display: true,
content: "<small>© MAGIC METHODS</small>",
range: true,
local: "ja-JP-u-ca-japanese",
format: {
timeZone: "Asia/Tokyo", era: "long",
}
},
}
Sidebar
| Property Name | Type | Default | Description |
|---|---|---|---|
| sticky | boolean | false | Whether does sticky the sidebar to left side by using “display: sticky” of CSS. |
| overlay | boolean | false | This property is enabled when sticky is true. When set to true, the portion hidden beneath the sidebar is transparently displayed when scrolling the timetable. |
| list | array<string> | (none) | Define the contents of the row of the sidebar. Appropriate escaping is necessary when using HTML. |
For example:
let options = {
sidebar: {
sticky: true,
overlay: true,
list: {
"<label>Row Item 1</label>",
"<label>Row Item 2</label>",
"<label>Row Item 3</label>",
}
},
}
Ruler
You can set the upper and lower ruler individually. You can define the ruler position to top or bottom and both.
| Property Name | Type | Default | Description |
|---|---|---|---|
| truncateLowers | boolean | false | There’s able to ignore outputting lower ruler scale than global scale if true. This property added since version 2.0.0b2. |
| top | object | (none) | The upper ruler configuration. The upper ruler is hidden if omitted. |
| bottom | object | (none) | The lower ruler configuration. The lower ruler is hidden if omitted. |
You can set options each the upper and lower ruler individually.
| Property Name | Type | Default | Description |
|---|---|---|---|
| lines | array<string> | (inherit scale) | Multiple tick marks can be set, and array elements are set in order from the top. Set same scale of Option.scale if omitted this. Refer to Scalable Settings for set possible scales. |
| height | number | 30 | The height of one row on the rulers. |
| fontSize | number | 14 | The size (pixel) of font on the rulers. |
| color | string | “#777777” | The color of text on the rulers. |
| background | string | “#FFFFFF” | The color of background on the rulers. |
| locale | string | “en-US” | This value is instead of the locales argument to Date.prototype.toLocaleString([locales[, options]]). For more detail. |
| format | object | (detail) | This value is instead of the options argument to Date.prototype.toLocaleString([locales[, options]]). For more detail. |
For example:
let options = {
ruler: {
truncateLowers: false,
top: {
lines: [ "year", "month", "weekday", "day" ],
height: 26,
fontSize: 12,
color: "#333",
background: "transparent",
locale: "de-DE",
format: {
timeZone: "UTC", weekday: "short", year: "numeric", month: "long", day: "numeric"
}
},
bottom: {
lines: [ "week", "year" ],
}
},
}
Event Meta
This event meta is enabled when timeline type is “bar” only. It will be added the meta information in the block of every event nodes on the timeline if enabled.
| Property Name | Type | Default | Description |
|---|---|---|---|
| display | boolean | false | Whether to show meta content into event nodes. |
| scale | string | “day” | Scale of meta datetime shown. |
| locale | string | “en-US” | This value is instead of the locales argument to Date.prototype.toLocaleString([locales[, options]]). For more detail. |
| format | object | (detail) | This value is instead of the options argument to # Date.prototype.toLocaleString([locales[, options]]). For more detail. |
| content | string | (none) | This is value for if you want to show custom content on the meta. |
For example:
let options = {
eventMeta: {
display: true,
scale: "day",
locale: "ja-JP",
format: [
timeZone: "Asia/Tokyo", hour12: false
],
content: ''
},
}
Effects
This property control some behaviors and view of the timeline. There’s added since version 2.0.0b1.
| Property Name | Type | Default | Description |
|---|---|---|---|
| presentTime | boolean | true | Whether show a line of present time if it includes present time into the timeline range shown. |
| hoverEvent | boolean | true | Whether fires a behavior when mouseover on one event. |
| stripedGridRow | boolean | true | Whether renders rows with striped color on the timeline container. |
| horizontalGridStyle | string | “dotted” | There’s able to change the horizontal grid line style on the timeline container. Allowed values are “solid”, “dotted” and “none”. |
| verticalGridStyle | string | “solid” | There’s able to change the vertical grid line style on the timeline container. Allowed values are “solid”, “dotted” and “none”. |
For example:
let options = {
effects: {
presentTime: true,
hoverEvent: true,
stripedGridRow: true,
horizontalGridStyle: "dotted",
verticalGridStyle: "solid",
},
}
Color Scheme
By using this property, you can overwrite defaults UI color of the timeline instance and the event nodes.
Check out the theme switching demo here.
| Property Name | Type | Default | Description |
|---|---|---|---|
| theme | object | (detail) | Color scheme to overwrite defaults UI color of the timeline instance. |
| event | object | (detail) | Color scheme to overwrite defaults UI color of the event node. |
| hookEventColors | function | undefined | You can declare a function to set colors with referring the data each event node. |
Theme Colors
| Property Name | Type | Default | Description |
|---|---|---|---|
| name | string | “default” | Theme’s name. |
| text | string | “#343A40” | Base text color. |
| subtext | string | “#707070” | Sub-text color. |
| offtext | string | “#BBBBBB” | Offtone text color. |
| modesttext | string | “#969696” | Modest text color more than offtone. |
| line | string | “#6C757D” | Base border color. |
| offline | string | “#DDDDDD” | Offtone border color. |
| activeline | string | “#DC3545” | Active line color. |
| background | string | “#FFFFFF” | Background color of the timeline instance. |
| invertbg | string | “#121212” | Inverted color of background. |
| striped1 | string | “#F7F7F7” | Used to striped color for ruler, sidebar, grids. |
| striped2 | string | “#F0F0F0” | Used to striped color for ruler, sidebar, grids. |
| active | string | “#F73333” | Activated event node color. |
| marker | string | “#2C7CFF” | Marker color for present time. |
| gridbase | string | “#333333” | Base color for grid lines in the timeline container. |
Event Colors
| Property Name | Type | Default | Description |
|---|---|---|---|
| text | string | “#343A4” | Text color on the event node. This uses as default color when the “color” of the event parameter undefined. |
| border | string | “#6C757D” | Border color on the event node. This uses as default color when the “bdColor” of the event parameter undefined. |
| background | string | “#E7E7E7” | Background color on the event node. This uses as default color when the “bgColor” of the event parameter undefined. |
About dateObj.toLocaleString
Please refer to the detail of about Date.prototype.toLocaleString().
The toLocaleString() method returns a string with a language sensitive representation of this date. The new locales and options arguments let applications specify the language whose formatting conventions should be used and customize the behavior of the function. In older implementations, which ignore the locales and options arguments, the locale used and the form of the string returned are entirely implementation dependent.
Please note that the implementation of toLocaleString() differs depending on each browser as described above, so you can not guarantee that the option value you set is always valid between all users who accessed the timeline.
In addition, this plugin has made some proprietary extensions for (format property in the plugin instead of) the options argument of toLocaleString().
| Extended Property | Added Value | Description |
|---|---|---|
| millennium / century / decade / lustrum / week / day | “ordinal” | It is expressed as ordinal according to scale. |
| year | “zerofill” | If the number is less than 4 digits, fill by zero within less than 4 digits. |
| hour / minute / second | “fulltime” | There are shown the “HH:MM” format if the property name is hour or minute, then the “HH:MM:SS” format if second. |
| custom | (Custom Format) | There’s able to show with any placeholder format string of the DateTime as like ruby. |
Custom Format
The dateObject.toLocaleString that is enhanced by this plugin has the “custom” property. By using this property, you can show the DateTime string more flexible. Allowed values of this property have placeholder patterns as like Ruby language.
| Placeholder | Shown DateTime | e.g. |
|---|---|---|
%Y |
A 4-digit number representing the year | 1970, 2019 |
%y |
Last 2 digits of the year | 00 – 99 |
%m |
A number representing the month | 01 – 12 |
%B |
Name of the month. That name will be dependent on the “locale” setting. | January |
%b |
An abbreviated name of the month. That name will be dependent on the “locale” setting. | Jan |
%d |
A number representing a day | 01 – 31 |
%w |
A number representing the day of the week. Sunday is 0. | 0 – 6 |
%W |
Yearly week number | 0 – 53 |
%A |
Name of the day of the week. That name will be dependent on the “locale” setting. | Sunday |
%a |
An abbreviated name of the day of the week. That name will be dependent on the “locale” setting. | Sun |
%I |
A number representing an hour in the 12-hour time | 01 – 12 |
%H |
A number representing an hour in the 24-hour time | 00 – 23 |
%M |
A number representing minutes | 00 – 59 |
%S |
A number representing seconds | 00 – 59 |
%j |
A day number of the year | 001 – 366 |
%Z |
4-digit year number with the zero-filled left side | 0645, 0083 |
For example:
let options = {
headline: {
locale: "ja-JP",
format: { custom: "%Y年%B%d日 %H%M分" }, // e.g. "2019年7月11日 20時15分"
},
}