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.0b2.
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.0b2.
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.0b2.
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.0b2.
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.0b1.
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.0b2.
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",
    },
}

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 0099
%m A number representing the month 0112
%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 0131
%w A number representing the day of the week. Sunday is 0. 06
%W Yearly week number 053
%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 0112
%H A number representing an hour in the 24-hour time 0023
%M A number representing minutes 0059
%S A number representing seconds 0059
%j A day number of the year 001366
%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分"
    },
}