シンプルなイベントカレンダーを実装するjQueryプラグイン

05 Nov 2009
Releases

ある朝僕は、以下の用件を満たすカレンダープラグインを探していました。

シンプルなHTMLを吐いてデザインの変更が容易
コールバック関数である程度処理をイジれる
月移動のアニメーションが素人ウケしそう

小一時間色々なプラグインを見ましたが、中々しっくり来るモノが無く、「これは探すより作った方が早そうかなぁ」と思ったので作ってみました。

機能概要

記事の初めで大方出ていますが、主に以下の機能を備えています。

月移動時のスライドアニメーション
生成するHTMLを包含する要素のclass変更
イベント追加、月移動などに対応するコールバック関数
JSON形式でのイベント追加
イベント用JSONの先読み機能（月移動時の遅延対策）
表示中の月に属さない日付の表示、非表示

ダウンロード

jQuery.calendar

動作デモ

導入方法

jQueryプラグインではお馴染み、 jQueryを読み込んでからプラグインを読み込む 。

<script src="jquery.js"></script>
<script src="jquery.calendar.js"></script>

実際にカレンダーを呼び出すコードは以下のようになります。

jQuery(function($) {
  var $el = $('.example')

  // 初期状態でカレンダーを呼び出す
  $el.calendar();
  
  // オプションを付けて呼び出す
  $el.calendar({
    オプション
  });
});

オプション

以下のオプションが指定できます。

オプション名	オプション値	初期値
year	初期表示する年	現在の年
month	初期表示する月	現在の月
week	日曜日から始まる週の配列	[日, 月, 火, 水, 木, 金, 土]
caption	表示月のキャプション	%Y年%M月
navi	0=前月、1=次月の配列	[前の月へ, 次の月へ]
todayLink	「今日」へのリンク	今日 [%Y年%M月%D日]
moveTime	スライドアニメの速度	700
events	イベント(行事)を指定
hideOther	表示中の月以外の日付を非表示	false
cssClass	包含要素のclass	jqueryCalendar
addDay	日付追加コールバック
addEvent	イベント追加コールバック
beforeMove	月移動前のコールバック
afterMove	月移動後のコールバック
preloadEvent	イベントデータ先読み

イベントを追加

イベントを追加するには、オプションeventsに連想配列を渡します。

addEventコールバック関数をデフォルトの状態で使用する場合は、以下のような書式になります。

$el.calendar({
  events: {
    // 月と日はゼロパディングしてもしなくてもOK
    '2009-10-01': {
      title: 'titleを指定すると、指定した文字列がtitle属性に挿入される',
      url: 'urlを指定した場合リンクになる'
    },
    '2009-10-2': {
      title: 'titleを指定すると、指定した文字列がtitle属性に挿入される',
      url: 'urlを指定した場合リンクになる'
    }
  }
});

addEventコールバック関数を使って独自の処理にする場合は、連想配列の内容に制限はありません。

$el.calendar({
  events: {
    '2009-10-01': {
      hoge: 'addEventの第二引数で受け取れる (evt.hoge など)'
    }
  }
});

コールバック関数

addDay

表示月の日付セルを追加する際に呼ばれる関数。

実行するタイミング: 日付セル追加時第一引数: 日付セル(td)のjQueryオブジェクト

this.day で日（day）を取得できます。これは td.text() の戻り値と同じ値です。

$el.calendar({
  addDay: function(td) {
    // 日付の後ろに「日」を付ける (例: 10日)
    td.text(td.text() + '日');
  
    // 上記と下記の結果は同じ
    td.text(this.day + '日');
  }
});

addEvent

イベント(行事)を追加する際に呼ばれる関数。

実行するタイミング: イベント(行事)追加時
第一引数: 日付セル(td)のjQueryオブジェクト
第二引数: eventsオプションで指定したイベント

第二引数にはeventsで指定した日付の内容がそのまま渡される。イベントを追加の例では連想配列を渡しています。

$el.calendar({
  // 以下は初期値
  addEvent: function(td, evt) {
    var elem = typeof evt.url != 'undefined'
      ? $('<a>').attr('href', evt.url)
      : $('<span>');
    if (evt.id) {
      elem.attr('id', 'event-' + evt.id);
    }
    if (evt.title) {
      elem.attr('title', evt.title);
    }
    elem.text(td.text());
    td.text('').append(elem).addClass('event');
  }
});

beforeMove & afterMove

月移動前後に呼ばれる関数。

実行するタイミング: 月移動前後
第一引数: 全オプションの連想配列
第二引数: 移動する年
第三引数: 移動する月

$el.calendar({
  // 月移動前に次のイベントをセット
  beforeMove: function(option, year, month) {
    // /hoge/YYYYMM からJSONを取得
    $.getJson('/hoge/' + year + month, function(json) {
      option.events = json;
    });
  }
});

preloadEventがあるので使用用途が微妙。

イベントをプリロード

イベントデータを月ごとに読み込む場合、月移動時にAjaxなどでイベントデータを読み込むと遅延が発生するので、プリロード(先読み)機能を用意しました。

実行するタイミング: カレンダーを表示した直後
第一引数: 表示している年
第二引数: 表示している月

使用方法

オプションpreloadEventに関数を定義して、以下のようにイベントデータをreturnして下さい。

$el.calendar({
  preloadEvent: function(year, month) {
    // 表示月が2009年10月の場合
    :
    : AjaxでJSONを読み込むなど
    :
    return {
      '2009-09-1': {
        title: '前月のイベント'
      },
      '2009-11-1': {
        title: '次月のイベント'
      }
    }
  }
});

この場合、前月と次月のイベントを含むデータをreturnしなければなりません。

イベントデータが多い場合は、前月と次月を分けて記述することも出来ます。

$el.calendar({
  preloadEvent: function(year, month) {
    // 表示月が2009年10月の場合
    :
    : AjaxでJSONを読み込むなど
    :
    return {
      // 前月のデータはprevの中に
      prev: {
        '2009-09-1': {
          title: '前月のイベント'
        }
      },

      // 次月のデータはnextの中に
      next: {
        '2009-11-1': {
          title: '次月のイベント'
        }
      }
    }
  }
});

イベント追加の処理が少なくなるので、少しだけ速くなります。