jquery.timeline.psk

1.0.5 • Public • Published

Packagist

jQuery.Timeline

You are able to easily create two types of horizontal timeline with this jQuery plugin.

jQuery.Timeline Image

DEMO

For various examples, please see here:

Browser Support

jQuery.Timeline supports the following browsers:

  • Chrome : Recommended latest version as active support
  • Firefox : Recommended latest version as active support
  • Safari : Recommended latest version as active support
  • Opera : Recommended latest version as active support
  • Edge : Recommended latest version as active support
  • IE : Recommended latest version as active support

Dependencies

JQuery.Timeline works normal operation with jQuery version 1.9.0 or later. We recommend that you use the latest version 3.x.

Usage

Use resources in the dist directory in the repository package.

<link rel="stylesheet" href="./dist/timeline.min.css">
<script src="./dist/timeline.min.js"></script>

HTML:

<!-- Timeline Block -->
<div id="myTimeline">
  <ul class="timeline-events">
    <li data-timeline-node="{ start:'2017-05-26 10:00',end:'2017-05-26 13:00',content:'text text text text ...' }">Event Label</li>
    <li data-timeline-node="{ start:'2017-05-26 23:10',end:'2017-05-27 1:30',content:'<p>In this way, you can include <em>HTML tags</em> in the event body.<br>:<br>:</p>' }">Event Label</li>
  </ul>
</div>
 
<!-- Timeline Event Detail View Area (optional) -->
<div class="timeline-event-view"></div>

Note: The tag of the event list wrapped in the timeline block is not "ul" fixed. If the class name is a "timeline-events", it can be a "div" tag or the like.

jQuery:

$(function () {
  $("#myTimeline").timeline();
});

Options

You can pass options on plugin initialization. For example:

$("#myTimeline").timeline({
  startDatetime: '2017-05-25',
  rows: 6,
  datetimeFormat: { meta: 'g:i A, D F j, Y' },
  rangeAlign: 'center'
});
Option Type Default Description
type String bar View type of timeline event is either "bar" or "point"
scale String days Timetable's top level scale is either "years" or "months" or "days"
startDatetime String currently Default set datetime as viewing timetable; format is "^[-+]d{4}(/\|-)d{2}(/\|-)d{2}\sd{2}:d{2}:d{2}$" or "currently"
datetimePrefix String The prefix of the date and time notation displayed in the headline
showHeadline Boolean true Whether to display headline
datetimeFormat Object {full:"j M Y", year:"Y", month:"M", day:"D, j M", years:"Y", months:"F", days:"j", meta:"Y/m/d H:i", metato:""} Available formats are here: fn.date.js; Since version 1.0.3, it's able to define the date format displayed in the meta field of the event detail. In addition, it can be specified as a language JSON file for multilingual support.
minuteInterval Integer 30 Recommend more than 5 minutes; only if top scale is "days" (Deprecated)
zerofillYear Boolean false It's outputted at the "0099" if true, the "99" if false
range Integer 3 The default view range of the timetable starting from the "startDatetime"
rows Integer 5 Rows of timeline event area
rowHeight Integer 40 Height of one row
height Mixed auto Fixed height (pixel) of timeline event area; default "auto" is (rows * rowHeight)px
minGridPer Integer 2 Minimum grid per
minGridSize Integer 30 Minimum size (pixel) of timeline grid; It needs 5 pixels or more
rangeAlign String current Possible values are "left", "center", "right", "current", "latest" and specific event id
naviIcon Object {left:"jqtl-circle-left", right:"jqtl-circle-right"} Define class name
showPointer Boolean true Whether to display needle pointer on the current datetime
i18n Object (omission) Define translated text for internationalization of datetime format converted by datetime format. For details, refer to the section on Internationalization.
langsDir String ./langs/ Since ver.1.0.3, you can specify the path that stores the language files for multilingualization. Please specify by relative path or absolute URL from HTML where js script is loaded.
httpLanguage Boolean false Whether to obtain the language setting of the browsing environment from the server side header.

Methods

The initialized Timeline object can do various operations by using method. It is also possible to execute multiple methods by chaining each method.

$("#myTimeline").timeline({
  type  : "bar",
  range : 5
}).timeline("initialized", function( self, data ){ 
  console.log([ "user's callback", self, data ]);
});
Method Description Arguments Usage
initialized Called after plugin initialization, just before timeline block is rendered. Callback Function $.timeline('initialized', function( self, data ){ alert('initialization complete!'); });
destroy Destroy the timeline object created by the plugin. - $.timeline('destroy');
show Display hidden timeline objects. - $.timeline('show');
hide Hide the displayed timeline object. - $.timeline('hide');
render Re-render the timeline block. At this time, the event operated by the method is discarded and only the initial event is placed. -
dateback Put the timeline back to the past. It is the same as clicking on the left navigation icon. - $.timeline('dateback');
dateforth Go forth the timeline to the future. It is the same as clicking the right navigation icon. - $.timeline('dateforth');
alignment Adjust the center position of the timeline. - $.timeline('alignment', 'center');
getOptions Get all option values for timeline. - var tlOptions = $('#myTimeline').timeline('getOptions');
addEvent Add any events to the timeline. You can also specify a callback function after adding an event. Array, Callback Function (optional) $.timeline('addEvent', [ {start:'2017-6-1 00:00',end:'2017-6-1 02:00',row:2,label:'Add Event',content:'test'} ], function( self, data ){ alert('Added Event!'); });
removeEvent Removes the specified event from the timeline. To specify the event, use the event ID. Array, Callback Function (optional) $.timeline('removeEvent', [ 6, 7 ]);
updateEvent Updates the contents of the specified event. It is possible to update multiple events simultaneously. Array, Callback Function (optional) $.timeline('updateEvent', [ {eventId:3, start:'2017-5-29 13:00',end:'2017-5-29 15:30', row:1, label:'Updated Event', bgColor:'#aaaab0', color:'#d70035'} ]);
openEvent Called back when an event is clicked. (object) Unlike other methods, the processing specified by the event parameter callback (to be described later) is invoked.

Handling Events (since v1.0.5)

Since version 1.0.5, the custom events are triggered according to the state of timeline objects. This allows you to bind your own processing to a custom event.

$("#myTimeline").on("afterRender.timeline", function( e, options ) {
  // Do something
});
Event Description Arguments
afterRender.timeline Fired after rendering completely a timeline object. options (object)

Event Parameters

Events placed on the timeline have parameters for display. You can specify this event parameter either by directly marking up in HTML or by using a method.

Directly markup on HTML

<div class="timeline-events">
  <div>This event is ignored because it is an invalid event</div>
  <div data-timeline-node="{ start:'2017-01-01 00:00',end:'2017-01-01 13:00',content:'Fill in the text of the event.' }">This is a valid event</div>
  <div data-timeline-node="{ start:'2017-01-01 00:00',end:'2017-01-01 13:00',content:'Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...' }">Lorem Ipsum</div>
</div>

Note: Event lists that do not have a "data-timeline-node" attribute are ignored when initializing timeline objects and are not placed on the timeline.

Using methods

$('myTimeline').timeline()
.timeline( 'addEvent', [
  {start:'2017-1-1 08:00',end:'2017-1-1 10:00',label:'Event 1',content:'Event body'},
  {start:'2017-1-1 09:30',end:'2017-1-1 10:15',label:'Event 2',content:'Event body'}
],
function( self, data ){
  console.log('Events addition successfully!');
});

Event Parameter List

Parameter Type Timeline Type Description
eventId Integer bar/point It must be an integer value equal to or greater than 1 and it must be a unique value in the event list. It can be omitted as a parameter, and if omitted, it will be automatically issued at plugin initialization.
start String bar/point Event start datetime. Specify it like 2017-1-1 0:00 or 2017/01/02 01:23
end String bar Event end datetime. Ignored if the timeline type is point. The usable format is the same as start.
row Integer bar/point The display line (vertical position) on the timeline. An integer value of 1 or more. If not specified, this will be the first line (top row) event.
label String bar/point Event title. When marking up with HTML, the text part of the event list tag is used as a label.
content String bar/point Event body. If there is an event detail display area, it will be displayed there.
bgColor String bar/point The background color of the event node block displayed on the timeline.
color String bar/point The text color of the event node block displayed on the timeline.
bdColor String point Valid when the timeline type is point. The border color of the event node block displayed on the timeline.
image String point Valid only when the timeline type is point. It is a thumbnail image of the event node block displayed on the timeline.
margin Integer point Valid only when the timeline type is point. The margin of the event node block. The initial value is 2 pixels, and by increasing the value you can reduce the size of the event node block. It can be specified less than half the width of the optional rowHeight.
extend Object bar/point An arbitrary value can be set in the key and value format as the user extension parameter of the event node block. This parameter value can be referred to in a callback event.
callback JavaScript bar/point You can define additional processing when an event is clicked. The processing defined here is treated after the "openEvent" method.
relation Object point Valid only when the timeline type is point. If there is an event connected to itself before and after the event, its event and its own event are connected by a line by defining a concatenated event.

Event Relation Line

When the timeline type is point, each event can be concatenated with a line. To set the connection line, use the "relation" parameter at each event and specify the event ID before and after connecting to the event. The setting values that can be specified by the relation parameter are as follows.

Property Type Value Description
before Numeric eventId Specify the event ID to be concatenated before (left side) its own event. By specifying -1, you can draw a line from outside the timeline area (the left edge of the display area).
after Numeric eventId Specify the event ID to be concatenated after (right side) its own event. By specifying -1, you can draw a line outside the timeline area (the right end of the display area).
linesize Integer pixels Specify the thickness of the connection line.
linecolor String color code Specify the color of the connection line.
curve String Any of lt,rt,rb,lb Line can be curved when connecting to events of a line different from own event. Specify the curved direction at that time. For example, to concatenate to the upper left event specified by before, specify lb.

Example of lines

Basic

When linking from itself (event ID: 2) to past event (event ID: 1):

<ol class="timeline-events">
  <li data-timeline-node="{ eventId:1, start:'2017-5-25 12:00',row:2 }">Event 1</li>
  <li data-timeline-node="{ eventId:2, start:'2017-5-27 20:00',row:2,relation:{before:1} }">Event 2</li>
</ol>

Straight connection

Curve

When concatenating by curved line from itself (event ID: 2) to a past event (event ID: 1) of a different line:

<dl class="timeline-events">
  <dd data-timeline-node="{ eventId:1, start:'2017-5-25 12:00',row:2 }">Event 1</dd>
  <dd data-timeline-node="{ eventId:2, start:'2017-5-27 20:00',row:3,relation:{before:1,curve:'lb'} }">Event 2</dd>
</dl>

Curve connection

Internationalization

This plugin has a function to internationalize the date and time format text to be output and to define translated text according to the language to be used. When using this function, please add the following option when initializing the timeline object.

$("#myTimeline").timeline({
  i18n : {
    month: { 'Jan.': 'Januar', 'Feb.': 'Februar', 'März': 'März', 'Apr.': 'April', 'Mai': 'Mai', 'Juni': 'Juni', 'Juli': 'Juli', 'Aug.': 'August', 'Sept.': 'September', 'Okt.': 'Oktober', 'Nov.': 'November', 'Dez.': 'Dezember' },
    day: { 'So': 'Sonntag', 'Mo': 'Montag', 'Di': 'Dienstag', 'Mi': 'Mittwoch', 'Do': 'Donnerstag', 'Fr': 'Freitag', 'Sa': 'Samstag' },
    ma: [ 'vorm.', 'nachm.' ]
  }
});

Note: The above is an example of defining translation text in German.

Multilingualization

Since version 1.0.3, multilingual support enhanced. By placing any required language files (as the JSON format) on the "langs" folder, the translated text defined in the JSON file is applied according the language setting of the browser.

{
  "month": {
    "Jan": "January",
    "Feb": "February",
    "Mar": "March",
    "Apr": "April",
    "May": "May",
    "Jun": "June",
    "Jul": "July",
    "Aug": "August",
    "Sep": "September",
    "Oct": "October",
    "Nov": "November",
    "Dec": "December"
  },
  "day": {
    "Sun": "Sunday",
    "Mon": "Monday",
    "Tue": "Tuesday",
    "Wed": "Wednesday",
    "Thu": "Thurseday",
    "Fri": "Friday",
    "Sat": "Saturday"
  },
  "ma": [
    "am",
    "pm"
  ],
  "format": {
    "full": "j M Y",
    "year": "Y",
    "month": "M Y",
    "day": "D, j M",
    "years": "Y",
    "months": "F",
    "days": "j",
    "meta": "g:i A, D F j, Y",
    "metato": ""
  }
}

Note: The above is an "en-US.json" that defined translation text in English.

TIPS

Some practical TIPS are as follows:

1. Display event details in bootstrap's modal window

First, we set up an event detail area in the body block (.modal-body) of the modal window.

<div class="modal fade" id="myModal">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title"></h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        <div class="timeline-event-view"></div>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
      </div>
    </div>
  </div>
</div>

Set the callback of the event parameter to the call of the modal window.

<div id="myTimeline">
  <div class="timeline-events">
    <div data-timeline-node="{ start:'2017-05-26 12:45',end:'2017-05-26 13:45',callback:'$(\'#myModal\').modal()',content:'Show modal window via bootstrap' }">Event having callback</div>
  </div>
</div>

When an event on the timeline is clicked, event details will be displayed in the modal window.

2. Apply bootstrap tooltip to events on timeline

You will define options for tooltip control in the extended setting of event parameters.

<div id="myTimeline">
  <ul class="timeline-events">
    <li data-timeline-node="{ start:'2017-05-26 16:08',end:'2017-05-26 17:54',row:2,extend:{toggle:'popover',placement:'bottom',content:'Show popover via bootstrap'} }">Event with popover</li>
  </ul>
</div>

Make the tooltip bind to the event node block rendered in JavaScript.

$('.timeline-node').each(function(){
  if ( $(this).data('toggle') === 'popover' ) {
    $(this).attr( 'title', $(this).text() );
    $(this).popover({
      trigger: 'hover'
    });
  }
});

Now when you mouse over the event on the timeline you will see the tooltip.

Note: In Bootstrap version 4.x, errors may occur when tooltips are used. In that case, it may be solved by inclusion of the tether plugin.

3. Bind a custom function to an "openEvent" method

The custom function you want to call should be defined on the global scope.

<div id="myTimeline">
  <ul class="timeline-events">
    <li data-timeline-node="{ start:'2017-06-20 08:00',end:'2017-06-20 12:00', callback:'$.openMyEvent()', extend:{'prop':'value'} }">Example Event</li>
  </ul>
</div>
$.openMyEvent = function() {
  console.log('openEvent - event clicked...');
  // Retrieve extended data from an opened event 
  console.info( $('.timeline-node.active').data() );
};

Note

We posted a Japanese manual here:

https://ka2.org/

License

This plugin is available under the MIT license.

Dependencies (0)

    Dev Dependencies (9)

    Package Sidebar

    Install

    npm i jquery.timeline.psk

    Weekly Downloads

    1

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    773 kB

    Total Files

    55

    Last publish

    Collaborators

    • programmerpsk