tDiary
プラグインの作り方

※プラグインの使い方については、HOWTO-use-plugin.htmlを参照してください。

　プラグインはtDiary 1.3.1以降で使えるようになった、システムに機能を追加する仕組みです。プラグインはtDiary.Netから入手することができます。また、tDiaryフルセットを利用している場合には、misc/pluginディレクトリに単独に配布されているのと同等のものが含まれています。これらの.rbファイルを、ファイルごとインストール先にあるpluginディレクトリに移動することで、利用できるようになります。

　プラグインにはさまざまなものがありますが、日記中に自動的に何かの文字列を埋め込んだり、特殊な処理をさせるのが主な目的です。また、特定のプラグインを作ることで、tDiaryのメッセージをカスタマイズすることもできます。

　以下では、プラグインについてその「作り方」を説明します。なお、.rbファイルのことを「プラグインファイル」、実際に日記中で呼び出して使う機能(主にRubyのメソッド)のことを「プラグイン」と呼びます。ひとつのプラグインファイルは、複数のプラグインを含みます。

プラグインの作り方

　プラグインは、Rubyのメソッドになっています。これらのメソッドはプラグインを実装するPluginクラスのメソッドとして読み込まれ、日記ファイル生成時の最後の段階で呼び出されます。プラグインメソッドは文字列を返し、それがそのまま日記に埋め込まれることになります。

　制作側から見たプラグインは、3種類あるように見えます。ひとつはカスタマイズ系プラグインです。これらは日記の特定の場所にすでに埋め込まれていて、日記生成時に強制的に呼び出されます。デフォルトプラグインにおいてすでに定義されていて、同名のプラグインを再定義することで動作を変更することができるものです。各種メッセージや、日付・段落アンカー、HTMLヘッダを生成するプラグインがこれにあたります。

　2種類目のプラグインは、完全にオリジナルのプラグインです。ヘッダやフッタ、日記本文に日記著者が意図的に記述することで呼び出されます。これらはデフォルトでは未定義で、既存のプラグインと名前がだぶらない限り好きな名称にできます。プラグイン集に収録されているプラグインは、たいていこれです。

　3種類目のプラグインはコールバック系プラグインです。これは呼び出される場所が決まっている点でカスタマイズ系プラグインに似ていますが、メソッドにはなっておらず、文字列を返すブロックを追加していく形で定義します。更新時だけに呼び出されるプラグインや、日記本文の前後に呼び出されるプラグイン、HTMLヘッダを追加するプラグインが定義できます。

　以降で、これらそれぞれのプラグインの作り方について説明します。

カスタマイズ系プラグイン

　日記本文に現れるメッセージや文字列の多くは、プラグインによって差し込まれています。それぞれのメッセージに対応するプラグインを再定義することで、メッセージをカスタマイズできるのです。プラグイン作成のうちもっとも簡単なこのカスタマイズをこれから見ていきます。

　カスタマイズ可能な文字列は、デフォルトプラグインとしてあらかじめ以下のように定義されています。

def comment_today; '本日のツッコミ'; end
def comment_total( total ); "(全#{total}件)"; end
def comment_new; 'ツッコミを入れる'; end
def comment_description; 'ツッコミ・コメントがあればどうぞ! E-mailアドレスは公開されません。'; end
def comment_description_short; 'ツッコミ!!'; end
def comment_name_label; 'お名前'; end
def comment_name_label_short; '名前'; end
def comment_mail_label; 'E-mail'; end
def comment_mail_label_short; 'Mail'; end
def comment_body_label; 'コメント'; end
def comment_body_label_short; '本文'; end
def comment_submit_label; '投稿'; end
def comment_submit_label_short; '投稿'; end
def comment_date( time ); time.strftime( "(#{@date_format} %H:%M)" ); end
def referer_today; '本日のリンク元'; end

　これらのメソッドを再定義することで、別の文字列を埋め込むことが可能です。

　まず、自分のカスタマイズ用プラグインファイルを用意します。pluginディレクトリに、例えば「custom.rb」という名前でファイルを作ります。自分の日記の雰囲気には「ツッコミ」という言葉がしっくり来ないという場合を想定して、これらを書き換えることにしましょう。ツッコミという言葉を使っている4つのメソッドをcustom.rbにコピーして、「コメント」という言葉に置き換えます。

def comment_today; '本日のコメント'; end
def comment_new; 'コメントを入れる'; end
def comment_description; 'コメントがあればどうぞ! E-mailアドレスは公開されません。'; end
def comment_description_short; 'コメント'; end

　これだけでOKです。日記を表示して、変化していることを確認しましょう(スーパーリロードしないと変化しないかも知れません)。

　他にも、カスタマイズ用プラグインとして「theme_url」が用意されています。

def theme_url; 'theme'; end

　このプラグインは、テーマファイルが置かれているURLを指定するものです。通常はインストール先のthemeディレクトリなのでこのままで大丈夫ですが、同一サーバで複数の日記を運用している場合など、テーマファイルを一か所に集めたい場合には、これを使わないとテーマが読み込まれません。

　カスタマイズするときは、「'theme'」の代わりにテーマファイルのあるディレクトリのURLを指定します。URLの最後を「/」で終わってはいけません。

　このほかにも、navi_userやnavi_adminを再定義することで、ナビゲーションボタンのラベルを変更することもできます。また00default.rbにはこれ以外にも、HTMLのヘッダの情報生成や、日付・段落アンカータグを生成する以下のようなプラグインが定義されています(詳しくはコードを読んでください)。

オリジナルプラグインの実装

　以下では、Rubyのコードが書ける人を対象に、オリジナルのプラグインを実装する方法を解説します。と言っても、文字列を返すメソッドを書くだけなので難しいことはありません。ここでは、プラグイン内で利用できるインスタンス変数の解説だけ行います。

　プラグインは専用のPluginクラスの内部で実行されるので、その中にある変数にしかアクセスできません。tDiaryの他の部分に影響が出ないようになっています。もっとも、evalを使って再定義してしまうことで、いくらでも自由になるのですが。

　Pluginクラスのインスタンス変数には以下のものがあります。

変数名説明
@mode現在動作中のモードを表現する文字列です。tdiary.rb中で使われているTDiaryクラスの策クラス名から、TDiaryを取って、downcaseしたものが含まれています。上手に利用するにはtDiaryの内部構造を知っている必要があるでしょう(いずれちゃんと説明書きます。すまぬ)
@diaries日記データを保持するDiaryインスタンスのHashです。現在表示対象になっている日付を含む月全体が含まれます(最新表示で月をまたいでいる場合は、2ヶ月分含まれることがあります)。Hashのキーは「yyyymmdd」形式の日付で、Hashの値がDiaryインスタンスです。
@cgiCGIクラスのインスタンスで、現在実行中のCGIに渡されてきたパラメタやCookieのデータが含まれています。スクリプトのパスや、パラメタの値を取得したい場合に利用できます。。
@years現存するすべての日記の年月データを保持するHashです。キーは年、値は月のArrayです。
@cache_pathキャッシュファイルのあるディレクトリ。プラグインでキャッシュを使いたい場合は、ここに独自のディレクトリを掘って利用します。
@index日記の本体を示すページのURLです。デフォルトは「./」。tdiary.confで指定した物と同じです。
@update日記の更新ページを示すURLです。デフォルトは「update.rb」。tdiary.confで指定した物と同じです。
@author_name日記著者(あなた)の名前です。tdiary.confで指定したものと同じです。
@author_mail日記著者(あなた)のE-mailアドレスです。tdiary.confで指定したものと同じです。
@index_pageトップページのURLです。tdiary.confで指定したものと同じです。
@html_title日記のタイトル。tdiary.confで指定したものと同じです。
@date現在表示中の日付。特定の日か、月を表現したものかどうかは、@modeを見なければ判断できません。
@date_format日付のフォーマットを示す文字列。tdiary.confで指定したものと同じです。
@referer_table「本日のリンク元」で特定のURLを指定した文字列に変換するためのテーブル。Hashです。
@debugプラグイン開発時のデバッグ用フラグです。この値をメソッド内でtrueにすると、プラグイン実行時に存在しないメソッドを呼んでもエラーになります(通常時には無視されています)。この変数を利用するのはプラグイン開発時のみにとどめ、プラグイン配布時には必ず削除してください。

コールバック系プラグイン

　上で説明した、単に文字列を返すメソッドを定義してそれを日記本文に埋め込んで使うだけのプラグインと違い、特定の状況でのみ呼び出されるようなコールバック系プラグインがあります。tDiaryの機能を拡張するために利用できます。以下にその作り方を解説します。

　コールバック系のプラグインは現在、以下の4種類定義されています。

　いずれも通常のプラグインと同様にメソッドとして実装されていますが、上書き定義してはいけません。上書きすると、この機能を使っている他のプラグインが呼び出されなくなってしまうためです。

　このため、これらのプラグインには機能を追加するためのメソッド、add_update_procとadd_header_proc、add_body_enter_proc、add_body_leave_procが用意されています。これらはブロックを受けとります。ここで登録されたブロックが順番に呼び出されることで、複数のプラグインが実行されます。これらのプラグインは以下のように定義して使います。

# 検索キーワードをheadに挿入する
add_header_proc do
   '<meta name="keyword" content="Linux,Kondara">'
end

　なお、コールバック系プラグインはそれぞれのブロックが返した文字列をすべて連結してHTMLに埋め込みますが、update_procは何も埋め込みません(意味がないので)。このため、update用に追加するブロックは何も返す必要はありません。

　デフォルトプラグインファイルである00default.rbには、標準のHTMLヘッダを生成するheader_proc用ブロックが定義されています。

Pluginクラスのメソッド

　プラグインは、TDiary::Pluginクラスのインスタンス内に定義された特異メソッドとして動作します(コールバックは除く)。そのため、すでにPluginインスタンス中で定義されているメソッドは、プラグインから自由に呼び出すことが可能です。例えばあるプラグインの機能を別のプラグインから通常のメソッド呼び出しの形式で利用できるわけです。

　この他に、Pluginクラスには以下のようなメソッドが用意されています。通常はPluginクラス外へ影響を及ぼせないプラグインですが、これらのメソッドを使うことでそれが一部可能になっています。

メソッド名説明
add_cookie( cookie )Webブラウザに返すCookieを追加します。プラグインから何らかの情報をWebブラウザ側に保持しておいて欲しい時に使います。引数cookieはCGI::Cookieインスタンスです。なお、逆にCookieを受けとる時は、@cgiインスタンス変数から取得してください。
add_XXX_proc( proc )コールバック系プラグインを追加するメソッド。「XXX」にはheader、update、body_enter、body_leaveが入る。引数procにはProcインスタンス、もしくはブロックを与える。コールバック系プラグインを参照。

プラグインへのオプションの渡し方

　プラグインはRubyのメソッドですから、呼び出し時に引数を指定することで、利用者がプラグインの挙動を変更することが可能です。しかし、tdiary.conf等で日記管理者が強制的にオプションを指定したい場合があります。そのようなプラグインを作成する時には、tdiary.confで指定できる@options変数を使うことができます。

　@option変数はHashとしてプラグインに見えますので、tdiary.confで任意の文字列をキーとして定義すれば、それをプラグイン内で利用することが可能です。@optionsのキーに指定する文字列はなんでもかまいませんが、名前の重複を避けるためにプラグイン名とオプション名を「.」で区切ったものを推奨します。

# sampleプラグインにhogeオプションを指定する(tdiary.conf内)
@options['sample.hoge'] = 'foobar'

# sampleプラグイン内でオプションを取得する(sample.rb内)
hoge = @options['sample.hoge']

　なお、この仕組みはプラグイン制作者側には便利ですが、ファイルを設置するだけで使えるようになるプラグインの簡便さを削いでしまう可能性もあります。できるだけ@optionsが設定されていなくても動作するように、適切なデフォルトを用意するようにして下さい。