現在開発しているサービスで利用するべく、横型タイムラインを生成できる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 の最新リソースをダウンロードしてください。
展開したファイルの dist ディレクトリ内のリソースを使用します。
<link rel="stylesheet" href="./dist/timeline.min.css">
<script src="./dist/timeline.min.js"></script>
HTML内に上記のように jQuery.Timeline を読み込むことで準備完了です。
マークアップ:
タイムラインブロックを表示する場所に、
<div id="myTimeline">
<ul class="timeline-events">
<li data-timeline-node="{ start:'2017-05-26 10:00',end:'2017-05-26 13:00',content:'Lorem ipsum dolor sit amet, consectetur adipiscing elit.' }">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 Title</li>
</ul>
</div>
──のようにマークアップします。
注意: 上記の例ではタイムライン上のイベントリストを <ul> タグでマークアップしていますが、使用タグは <ul> 以外のタグも利用可能です。個々のイベントを定義したタグの親タグのクラス名が timeline-events であれば <div> タグ等でマークアップしても構いません。
次に、タイムラインのイベントをクリックした際に、イベント詳細が表示される領域に下記のようにマークアップします。
<div class="timeline-event-view"></div>
このイベント詳細領域が不要であれば、省略可能です。
最後に、マークアップしたタイムラインブロックに jQuery.Timeline プラグインを適用します。 </body> の直前などに下記 JavaScript を追加してください。
<script>
$(function () {
$("#myTimeline").timeline();
});
</script>
これで基本的なマークアップは完了です。
オプション
プラグインが初期化される際に、タイムラインオブジェクトごとに個別のオプション設定を適用することができます。例えば、下記のように設定します。
$("#myTimeline").timeline({
startDatetime: '2017-05-25',
rows: 6,
rangeAlign: 'center'
});
初期化オプションに設定可能なパラメータは下記の通りです。
| オプション名 | 値タイプ | 初期値 | 説明 |
|---|---|---|---|
| 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 | オブジェクト | (省略) | プラグイン全体で出力される日時書式を国際化するための、翻訳テキストを定義することができます。詳しくは国際化にて説明します。 |
メソッド
初期化されたタイムラインオブジェクトに対して、メソッドを使うことで様々な操作を行うことができます。また、各メソッドはチェーンすることで、同時に複数のメソッドを利用することも可能です。
$("#myTimeline").timeline({
type : "bar",
range : 5
}).timeline("initialized", function( self, data ){
console.log([ "user's callback", self, data ]);
});
メソッドを利用する時は、基本的にタイムラインオブジェクトに対して、第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”を指定し、ここにパラメータを記入します。
<div class="timeline-events">
<div>このイベントリストは無視されます</div>
<div data-timeline-node="{ start:'2017-01-01 00:00',end:'2017-01-01 13:00',content:'イベント本文が入ります。' }">有効なイベント</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>
注意: “data-timeline-node”属性を持たないイベントリストはタイムラインオブジェクト初期化時に無視され、タイムライン上に配置されません。
メソッド
タイムラインオブジェクト初期化後にメソッドでイベントを指定する場合、イベントリストをJavaScriptの配列として渡します。配列の要素は、イベント・パラメータのJavaScriptオブジェクトになります。
$('myTimeline').timeline()
.timeline( 'addEvent', [
{start:'2017-1-1 08:00',end:'2017-1-1 10:00',label:'イベント 1',content:'内容'},
{start:'2017-1-1 09:30',end:'2017-1-1 10:15',label:'イベント 2',content:'内容'}
],
function( self, data ){
console.log('Events addition successfully!');
});
イベント・パラメータ一覧
イベント・パラメータとして利用可能な設定値は下記の通りです。
| パラメータ名 | 値タイプ | タイムラインタイプ | 説明 |
|---|---|---|---|
| eventId | 数値 | bar/point | イベントID。1以上の整数値をとり、イベントリスト中において一意な値である必要があります。パラメータとしては省略可能で、省略した場合はプラグイン初期化時に自動で発番されます。 |
| start | 文字列 | bar/point | イベント開始日時。2017-1-1 0:00 や 2017/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）と連結する場合:
<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>
2. 曲線連結
自身（イベントID:2）から異なる行の過去のイベント（イベントID:1）に曲線で連結する場合:
<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>
※ 曲線連結はタイムラインでの表示に準じて、└が”rb“、┘が”lb“、┌ が”lt“、┐ が”rt” となります。
国際化
このプラグインでは出力される日時書式テキストを国際化して、利用する言語に応じて翻訳テキストを定義する機能を備えています。この機能を利用する場合、タイムラインオブジェクトの初期化時に下記のようなオプションを追加してください。
$("#myTimeline").timeline({
i18n : {
month: { '一月': '睦月', '二月': '如月', '三月': '弥生', '四月': '卯月', '五月': '皐月', '六月': '水無月', '七月': '文月', '八月': '葉月', '九月': '長月', '十月': '神無月', '十一月': '霜月', '十二月': '師走' },
day: { '日': '日曜', '月': '月曜', '火': '火曜', '水': '水曜', '木': '木曜', '金': '金曜', '土': '土曜' },
ma: [ '午前', '午後' ]
}
});
※ 上記は、日本語への翻訳をする場合になります。
デモ
このプラグインのデモページはこちらです：
TIPS
いくつか実践的なTIPSを紹介しておきます。
1. bootstrapのモーダルウィンドウにイベント詳細を表示する
まず、モーダルウィンドウの本文ブロック（.modal-body）内に、イベント詳細エリアを設置しておきます。
<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">×</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>
イベント・パラメータのコールバックにモーダルウィンドウの呼び出しを設定します。
<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>
これで、タイムライン上のイベントがクリックされると、モーダルウィンドウにイベント詳細が表示されるようになります。
2. タイムライン上のイベントにbootstrapのツールチップを適用する
イベント・パラメータの拡張設定にツールチップ制御用のオプションを定義しておきます。
<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>
JavaScriptでレンダリングされたイベントノードブロックにツールチップをバインドさせます。
$('.timeline-node').each(function(){
if ( $(this).data('toggle') === 'popover' ) {
$(this).attr( 'title', $(this).text() );
$(this).popover({
trigger: 'hover'
});
}
});
これで、タイムライン上のイベントにマウスオーバーするとツールチップが表示されます2。
ライセンス
- scaleに”years”を指定すると、月以下が切り捨てられ、年初が開始日時となります。また、scaleに”months”を指定すると、日以下が切り捨てられ、月初が開始日時となります。 ↩
- Bootstrapのバージョン4.xでは、ツールチップの使用時にエラーが発生する場合があります。その際、tetherプラグインをインクルードすることで解決できるかもしれません。 ↩
