tDiary
プラグインの作り方

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

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

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

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

プラグインの種類

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

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

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

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

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

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

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

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

def no_diary; "#{@date.strftime( @conf.date_format )}の日記はありません。"; end
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

def navi_index; 'トップ'; end
def navi_latest; '最新'; end
def navi_update; "更新"; end
def navi_preference; "設定"; end
def navi_prev_diary(date); "前の日記(#{date})"; end
def navi_next_diary(date); "次の日記(#{date})"; end

これらのメソッドを再定義することで、別の文字列を埋め込むことが可能です。モバイルモード向けにも用意されています。詳しくは00default.rbを参照してください。

まず、自分のカスタマイズ用プラグインファイルを用意します。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のヘッダの情報生成や、日付・段落アンカータグを生成する以下のようなプラグインが定義されています(詳しくはコードを読んでください)。

• author_name: 著者名を示すmetaタグを生成
• author_mail: 著者のメールアドレスを示すmetaタグを生成
• index_page: INDEXを示すmetaタグを生成
• css_tag: スタイルシートの利用を指示するタグを生成
• title_tag: titleタグを生成
• anchor: アンカータグを生成する

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

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

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

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

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

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

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

• update_proc: 日記更新時およびツッコミ追加時に呼び出される
• header_proc: HTMLヘッダ情報の生成時に呼び出される
• body_enter_proc: 日記本文開始の直前で呼び出される。パラメタに処理中の日記の日付(Timeインスタンス)が与えられる
• body_leave_proc: 日記本文終了の直後に呼び出される。パラメタに処理中の日記の日付(Timeインスタンス)が与えられる
• footer_proc: footer生成時に呼び出される
• edit_proc: 更新フォームの内部で呼び出される。更新フォーム内に新たなアイテムを追加する時に使う。パラメタに処理中の日記の日付(Timeインスタンス)が与えられる。追加したアイテムのname属性は、必ず「plugin_プラグイン名_アイテム名」になっていなくてはならない
• form_proc: 更新フォームの次に呼び出される。更新フォームとは別のフォームなどを追加するときに使う。パラメタに処理中の日記の日付(Timeインスタンス)が与えられる。フォームを追加した場合、submitボタンには必ず「plugin」というname属性を付ける必要がある
• conf_proc: 設定画面で呼び出される。プラグインのオプション設定をWebから行うためのプラグイン
• title_proc: 日ごとのタイトルを表示する局面で呼び出される。日付をリンクにするなど、タイトルを装飾するためのプラグイン
• subtitle_proc: セクションのサブタイトルを表示する局面で呼び出される。セクションアンカーを付与するなど、サブタイトルを装飾するためのプラグイン
• section_enter_proc: セクションの開始(サブタイトルの直前)で呼び出される。パラメタに処理中の日記の日付(Timeインスタンス)とセクションの番号(1〜)が与えられる
• section_leave_proc: セクションの終了直後に呼び出される。パラメタに処理中の日記の日付(Timeインスタンス)とセクションの番号(1〜)が与えられる

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

このため、これらのプラグインには機能を追加するためのメソッド、add_update_procとadd_header_proc、add_body_enter_proc、add_body_leave_proc、add_footer_proc、add_edit_proc、add_form_proc、add_title_proc、add_subtitle_proc、section_enter_procおよびsection_leave_procが用意されています。これらはブロックを受けとります。ここで登録されたブロックが順番に呼び出されることで、複数のプラグインが実行されます。また、conf_procに対応するadd_conf_procは後述するようにキーワードとラベル文字列を引数に取り、必要な時だけ呼び出されます。

これらのプラグインは、一般的に以下のように定義して使います。ブロックの返り値が、プラグインの値になります。

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

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

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

body_enter_procとbody_leave_proc、edit_proc、form_procは、現在対象にしている日記の日付がブロックパラメタとして受け取れるようになっているので、以下のように指定する必要があります。

# 最終更新日を表示する
add_body_enter_proc do |date|
   diary = @diaries[date.strftime( '%Y%m%d' )]
   "#{diary.last_modified( "%Y-%m%-d" )}"
end

section_enter_proc<\code>とsection_leave_procはbody_enter_procによく似ていますが、ブロックパラメタにセクションの通し番号(1〜)が加わっています。

# Permalinkを表示する
add_section_enter_proc do |date, index|
   "#{@index}#{anchor( date.strftime( '%Y%m%d' ) + '#p' + sprintf( '%02d', index )}"
end

# タイトルの末尾にリンクを付加する
add_title_proc do |date, title|
   return title + '<a href="hoge">link</a>'
end

# サブタイトルの末尾にリンクを付加する
add_subtitle_proc do |date, index, subtitle|
   return subtitle + '<a href="hoge">link</a>'
end

# name属性には「plugin_プラグイン名_アイテム名」を付けなければならない
add_edit_proc do |date|
   'Hoge: <input name="plugin_hoge_item1">'
end

# 更新時に値を受け取れる
add_update_proc do
   if /^(append|replace)$/ =~ @mode then
      hoge = @cgi.params['plugin_hoge_item1'][0]
   end
end

add_conf_proc( 'hoge', 'hogeの設定', 'etc' ) do
   # 設定の保存
   if @mode == 'saveconf' then
      @conf['hoge.fuga'] = @cgi.params['hoge.fuga'][0]
   end

   # 設定画面の出力
   <<-HTML
   <h3>fugaの指定</h3>
   <p><input name="hoge.fuga"></p>
   HTML
end

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

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