2種類の横型タイムラインを簡単に作成できる「jQuery.Timeline」をリリース

 現在開発しているサービスで利用するべく、横型タイムラインを生成できるjQueryプラグインを自作したので、そこだけ単独でリリースしてみた。

 ソースコード等はGitHubの方にリリースしてあるので、興味のある方は、そちらを見てください。

 で、GitHubの方のマニュアルは英語版なので、日本語版のマニュアルはこちらのサイトに公開しておこうかと。以下がそのマニュアルになります。


jQuery.Timeline

 このjQueryプラグインを使うことで、二種類の横型タイムラインを簡単に作成できます。

プラグイン・イメージ

対応ブラウザ

 jQuery.Timeline の対応ブラウザ状況は下記の通りです。

  • Chrome : 最新版で動作確認
  • Firefox : 最新版で動作確認
  • Safari : 未確認
  • Opera : 最新版で動作確認
  • Edge : 最新版で動作確認
  • IE : 未確認

対応jQueryバージョン

 JQuery.Timeline は jQuery 1.9.0 以降での正常動作を確認済みです。なお、最新 3.x 系のバージョンでのご利用を推奨します。

使用方法

 下記、GitHubページから jQuery.Timeline の最新リソースをダウンロードしてください。

https://github.com/ka215/jquery.timeline/releases

 展開したファイルの dist ディレクトリ内のリソースを使用します。

 HTML内に上記のように jQuery.Timeline を読み込むことで準備完了です。

マークアップ:

 タイムラインブロックを表示する場所に、

 ──のようにマークアップします。

 注意: 上記の例ではタイムライン上のイベントリストを <ul> タグでマークアップしていますが、使用タグは <ul> 以外のタグも利用可能です。個々のイベントを定義したタグの親タグのクラス名が timeline-events であれば <div> タグ等でマークアップしても構いません。

 次に、タイムラインのイベントをクリックした際に、イベント詳細が表示される領域に下記のようにマークアップします。

 このイベント詳細領域が不要であれば、省略可能です。

 最後に、マークアップしたタイムラインブロックに jQuery.Timeline プラグインを適用します。 </body> の直前などに下記 JavaScript を追加してください。

 これで基本的なマークアップは完了です。

オプション

 プラグインが初期化される際に、タイムラインオブジェクトごとに個別のオプション設定を適用することができます。例えば、下記のように設定します。

 初期化オプションに設定可能なパラメータは下記の通りです。

オプション名 値タイプ 初期値 説明
type 文字列 bar タイムライン上のイベント表示を切り替えます。”bar” か “point” を指定可能で、”bar”の場合はイベント開始・終了を持つ期間表示型となり、”point”の場合はイベント開始のみを点描する表示形式となります。
scale 文字列 days タイムテーブルの最上位スケールを指定します。”years” か “months” か “days” が指定できます。
startDatetime 文字列 currently タイムテーブルの表示開始日時を指定します。”YYYY-MM-DD HH:MM” もしくは “YYYY/MM/DD HH:MM” の形式か、現在日時を起点とする “currently” が指定可能です。なお、実際にレンダリングされる開始日時はscaleオプションの指定によって変化します1
datetimePrefix 文字列 タイムラインブロックの見出しとして表示される日時表示に接頭辞を付与する場合にその文字列を指定できます。例えば “西暦” などです。
showHeadline 真偽値 true タイムラインブロックの見出しを表示するかどうかを指定します。
datetimeFormat オブジェクト {full:"j M Y", year:"Y", month:"M Y", day:"D, j M", years:"Y", months:"F", days:"j" } イベント詳細のメタ(”full“)や、タイムラインブロックの見出し(”year“,”month“,”day“)、タイムテーブルのスケール(”years“,”months“,”days“)に表示される日時表示の書式を定義できます。
利用可能な書式はPHPのdate関数に準拠しています。詳しくは fn.date.js を参照してください。
minuteInterval 数値 30 トップスケール(scale)が「日」の場合のみ有効な、分の区切り間隔を指定します。5分以上の指定を推奨します。(非推奨なパラメータのため、将来的に削除するかもしれません)
zerofillYear 真偽値 false 年表示が4桁に満たない場合に0埋めをするかどうかです。
range 数値 3 タイムテーブルの表示範囲を指定します。startDatetime からトップスケール換算で指定レンジ分、タイムテーブルがレンダリングされます。
rows 数値 5 タイムライン・イベントエリアに出力される行数を指定します。
rowHeight 数値 40 タイムライン・イベントエリアの縦方向の一行の高さを指定します。
height 複合値 auto タイムライン・イベントエリアの全体の高さを指定します。ピクセル値の固定値を指定することも可能です。初期値である “auto” の場合、rows * rowHeight で自動計算されます。
minGridPer 数値 2 中位スケールの1目盛を何分割するかです。
minGridSize 数値 30 最下位スケールの1目盛の横幅をピクセル値で指定します。5ピクセル以上が必要です。
rangeAlign 文字列 current タイムラインブロックが出力された時の最初の表示位置を指定できます。有効な値は、 “left“, “center“, “right“, “current“, “latest” と、 任意のイベントID になります。
naviIcon オブジェクト {left:"jqtl-circle-left", right:"jqtl-circle-right"} イベントエリアの左右に表示されるナビゲーション・アイコンのクラス名を指定できます。外部フォント利用時等に使います。
showPointer 真偽値 true タイムライン内に現在日時が含まれている場合に表示される現在時刻ポインターを表示するかどうかです。
i18n オブジェクト (省略) プラグイン全体で出力される日時書式を国際化するための、翻訳テキストを定義することができます。詳しくは国際化にて説明します。

メソッド

 初期化されたタイムラインオブジェクトに対して、メソッドを使うことで様々な操作を行うことができます。また、各メソッドはチェーンすることで、同時に複数のメソッドを利用することも可能です。

 メソッドを利用する時は、基本的にタイムラインオブジェクトに対して、第1引数にメソッド名、第2引数にメソッド用のパラメータを指定します。メソッドによっては、第2引数または第3引数にコールバック関数を指定できるものもあります。
 利用可能なメソッドは以下の通りです。

メソッド名 概要 引数 使用例
initialized プラグインの初期化後、タイムラインブロックのレンダリング直前に呼び出されます。コールバック関数を引数で渡すことができ、プラグイン初期化後に独自の処理を追加することができます。 Callback Function $.timeline('initialized', function( self, data ){ alert('initialization complete!'); });
destroy プラグインによって作成されたタイムラインオブジェクトをDOM上から破棄します。 $.timeline('destroy');
show 非表示のタイムラインオブジェクトを表示します。 $.timeline('show');
hide 表示されているタイムラインオブジェクトを非表示にします。 $.timeline('hide');
render タイムラインブロックを再レンダリングします。この際、初期化後にメソッドで操作されたイベントはすべて破棄され、初期マークアップ時のイベントのみが再配置されます。
dateback タイムラインを過去(左)方向へスクロールさせます。左ナビアイコンをクリックした際の動作と同じです。 $.timeline('dateback');
dateforth タイムラインを未来(右)方向へスクロールさせます。右ナビアイコンをクリックした際の動作と同じです。 $.timeline('dateforth');
alignment タイムラインの中央位置を任意の位置に移動します。rangeAlignオプションで有効な値を指定できます。 文字列 $.timeline('alignment', 'center');
getOptions タイムラインオブジェクトの現在のオプション値を取得して、JavaScriptオブジェクトとして返します。 var tlOptions = $('#myTimeline').timeline('getOptions');
addEvent タイムライン上にイベントを追加します。第3引数にコールバック関数を指定することで、イベント追加後に独自の処理を実行することも可能です。 配列, Callback Function (任意) $.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 タイムライン上の指定イベントを削除します。削除イベントの指定にはイベントIDを使い、複数のイベントを同時に削除できます。また、第3引数にコールバック関数を指定することで、イベント削除後に独自の処理を実行することも可能です。 配列, Callback Function (任意) $.timeline('removeEvent', [ 6, 7 ]);
updateEvent タイムライン上の特定のイベントの内容を更新します。同時に複数のイベントを更新することも可能です。第3引数にコールバック関数を指定することで、イベント更新後に独自の処理を実行することも可能です。 配列, Callback Function (任意) $.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 タイムライン上のイベントがクリックされた時にコールバックされます。 (オブジェクト) 他のメソッドと異なり、後述するイベント・パラメータのcallbackで指定された処理が呼び出されます。

イベント・パラメータ

 タイムライン上に配置されるイベントは表示用のパラメータを持っています。このイベント・パラメータの指定方法には、HTMLに直接マークアップする方法と、メソッドを利用して指定する方法の2種類あります。

HTML

 HTMLに直接マークアップする場合、イベントリストをラップするクラス名”timeline-events“を持つ親タグの下に、子タグの属性として”data-timeline-node”を指定し、ここにパラメータを記入します。

 注意: “data-timeline-node”属性を持たないイベントリストはタイムラインオブジェクト初期化時に無視され、タイムライン上に配置されません。

メソッド

 タイムラインオブジェクト初期化後にメソッドでイベントを指定する場合、イベントリストをJavaScriptの配列として渡します。配列の要素は、イベント・パラメータのJavaScriptオブジェクトになります。

イベント・パラメータ一覧

 イベント・パラメータとして利用可能な設定値は下記の通りです。

パラメータ名 値タイプ タイムラインタイプ 説明
eventId 数値 bar/point イベントID。1以上の整数値をとり、イベントリスト中において一意な値である必要があります。パラメータとしては省略可能で、省略した場合はプラグイン初期化時に自動で発番されます。
start 文字列 bar/point イベント開始日時。2017-1-1 0:002017/01/02 01:23 のように指定します。
end 文字列 bar イベント終了日時。タイムラインタイプがpointの場合は無視されます。指定書式は start と同じです。
row 数値 bar/point タイムライン上の表示行(縦位置)。1以上の整数値。指定しないと1行目(最上段)のイベントとなります。
label 文字列 bar/point イベント表題。HTMLでマークアップ時はイベントリストタグのテキスト部がラベルとして使用されます。
content 文字列 bar/point イベント本文。イベント詳細表示領域がある場合、そこに表示されます。
bgColor 文字列 bar/point タイムライン上に表示されるイベントノードブロックの背景色です。
color 文字列 bar/point タイムライン上に表示されるイベントノードブロックの文字色です。
bdColor 文字列 point タイムラインタイプがpointの場合のみ有効です。タイムライン上に表示されるイベントノードブロックの外枠(ボーダー)色です。
image 文字列 point タイムラインタイプがpointの場合のみ有効です。タイムライン上に表示されるイベントノードブロックのサムネイル画像になります。
margin 数値 point タイムラインタイプがpointの場合のみ有効です。イベントノードブロックの余白(マージン)です。初期値は2ピクセルで、値を大きくすることでイベントノードブロックのサイズを小さくできます。オプションの rowHeight の半分の幅未満で指定可能です。
extend オブジェクト bar/point イベントノードブロックのユーザー拡張パラメータとして任意の値をキー・バリュー形式で設定できます。このパラメータ値はコールバックイベントで参照できます。
callback JavaScript bar/point イベントがクリックされた時の追加処理を定義できます。ここで定義された処理は “openEvent” メソッドの後続処理として扱われます。
relation オブジェクト point タイムラインタイプがpointの場合のみ有効です。自身の前後に連結するイベントがある場合、連結イベントを定義することでそのイベントと自身のイベントが線で連結されます。

リレーション・ライン

タイムラインタイプが”point”の場合、各イベントを線で連結することができます。連結線を設定するためには各イベントにてrelationパラメータを使って、そのイベントに連結する前後のイベントIDを指定します。
relationパラメータで指定できる設定値は下記の通りです。

プロパティ名 タイプ 説明
before 数値 イベントID 自身のイベントの前(左側)に連結するイベントIDを指定します。-1 を指定することで、タイムライン領域外(表示領域の左端)から線を引くことができます。
after 数値 イベントID 自身のイベントの後(右側)に連結するイベントIDを指定します。-1 を指定することで、タイムライン領域外(表示領域の右側)へ線を引くことができます。
linesize 数値 ピクセル値 連結線の太さを指定します。
linecolor 文字列 カラーコード 連結線の色を指定します。
curve 文字列 lt,rt,rb,lb のいずれか 自身のイベントと異なる行のイベントに連結する時に、線形を曲線化できます。その際の曲線化する方向を指定します。例えば、beforeで指定した左上のイベントに連結する場合はrbを指定します。

リレーション・ラインの例

1. 基本(直線連結)

 自身(イベントID:2)から過去のイベント(イベントID:1)と連結する場合:

直線連結

2. 曲線連結

 自身(イベントID:2)から異なる行の過去のイベント(イベントID:1)に曲線で連結する場合:

曲線連結

※ 曲線連結はタイムラインでの表示に準じて、が”rb“、が”lb“、 が”lt“、 が”rt” となります。

国際化

 このプラグインでは出力される日時書式テキストを国際化して、利用する言語に応じて翻訳テキストを定義する機能を備えています。この機能を利用する場合、タイムラインオブジェクトの初期化時に下記のようなオプションを追加してください。

※ 上記は、日本語への翻訳をする場合になります。

デモ

 このプラグインのデモページはこちらです:

TIPS

 いくつか実践的なTIPSを紹介しておきます。

1. bootstrapのモーダルウィンドウにイベント詳細を表示する

 まず、モーダルウィンドウの本文ブロック(.modal-body)内に、イベント詳細エリアを設置しておきます。

 イベント・パラメータのコールバックにモーダルウィンドウの呼び出しを設定します。

 これで、タイムライン上のイベントがクリックされると、モーダルウィンドウにイベント詳細が表示されるようになります。

2. タイムライン上のイベントにbootstrapのツールチップを適用する

 イベント・パラメータの拡張設定にツールチップ制御用のオプションを定義しておきます。

 JavaScriptでレンダリングされたイベントノードブロックにツールチップをバインドさせます。

 これで、タイムライン上のイベントにマウスオーバーするとツールチップが表示されます2

ライセンス

the MIT license


  1. scaleに”years”を指定すると、月以下が切り捨てられ、年初が開始日時となります。また、scaleに”months”を指定すると、日以下が切り捨てられ、月初が開始日時となります。 
  2. Bootstrapのバージョン4.xでは、ツールチップの使用時にエラーが発生する場合があります。その際、tetherプラグインをインクルードすることで解決できるかもしれません。 

Leave a Reply

Your email address will not be published.