※プラグインの作り方については、HOWTO-make-plugin.htmlを参照してください。
プラグインはtDiary 1.3.1以降で使えるようになった、システムに機能を追加する仕組みです。プラグインはtDiary.Netから入手することができます。また、tDiaryフルセットを利用している場合には、misc/pluginディレクトリに単独に配布されているのと同等のものが含まれています。これらの.rbファイルを、ファイルごとインストール先にあるpluginディレクトリに移動することで、利用できるようになります。
プラグインにはさまざまなものがありますが、日記中に自動的に何かの文字列を埋め込んだり、特殊な処理をさせるのが主な目的です。また、特定のプラグインを作ることで、tDiaryのメッセージをカスタマイズすることもできます。
以下では、プラグインについてその「使い方」「プラグイン集について」を説明します。なお、.rbファイルのことを「プラグインファイル」、実際に日記中で呼び出して使う機能(主にRubyのメソッド)のことを「プラグイン」と呼びます。ひとつのプラグインファイルは、複数のプラグインを含みます。
プラグインを使うには、そのプラグインを含んだプラグインファイルが、tDiaryインストール先にあるpluginディレクトリになければなりません。あらかじめ使いたいプラグインファイルをpluginディレクトリにコピーしておく必要があります。プラグインの中には高機能で処理に時間のかかるものも含まれているので、必要でないプラグインまでコピーすると、日記の表示が遅くなったりします。必要なプラグインだけを使うように、きちんと選択してください。
プラグインは、eRubyと呼ばれる文法を使って、日記のタイトルや本文、ヘッダやフッタに埋め込むことで利用できます。「calendar」や「navi」というデフォルトプラグインは、すでにヘッダの中で使っているので見たことがあるでしょう。プラグインの機能を日記に埋め込むときのもっとも簡単な書式は以下のとおりです。
<%=プラグイン名%>
たとえば、カレンダーを埋め込むプラグイン「calendar」は、以下のようにして記述します。
<%=calendar%>
プラグインの種類によっては、以下のようにパラメタを指定して動作を変えることもできます。
<%=プラグイン名 パラメタ1, パラメタ2, ...%>
各プラグインがどのようなパラメタを利用できるかは、プラグインファイルの先頭の方に書かれていることがあります。
プラグインを使えるのは、日記のタイトルと本文、およびヘッダとフッタです。日付フォーマットで使えるものもあります。すべてのページに表示したい場合にはヘッダかフッタを、その日の日記にだけ使いたい場合にはタイトルや本文に使います。また、ツッコミには使えません。
「デフォルトプラグイン」というプラグインファイル「00default.rb」がすでにpluginディレクトリに置いてあります。まず、これらのプラグインについて説明します。
日記ページの先頭にある、「トップ」「最新」「更新」などのナビゲーションボタンを表示するためのプラグインです。パラメタはありません。ヘッダやフッタに埋め込むことで、ページによって最適なボタンを表示します。このプラグインをどこかに埋め込んでおかないと、日記の更新ができなくなってしまいます。
※もしnaviプラグインを埋め込み忘れてしまい、日記の更新ができなくなってしまったら、日記のURLの後ろに「update.rb」(環境によっては「update.cgi」など)を付けて呼び出してみましょう。更新ページが表示されます。
※naviプラグインは、更新や設定のページに内部的に埋め込まれています。もとの挙動を大きく変えるような改造をすると、操作性を大きく損ねるおそれがあるので注意してください。
naviプラグインから内部的に呼び出されているプラグインですが、単独で使うこともできます。このプラグインは、ナビゲーションボタンのうち、日記閲覧者にのみ必要なボタン(「トップ」「最新」「<前日」「翌日>」)を表示します。これを使うことで、「更新」のような日記オーナーにだけ必要なボタンを表示させないなどのカスタマイズを行えます。
パラメタはありませんが、naviプラグインを使う場合に比べて、前後のPタグが省略されるので、以下のようにして埋め込むと良いでしょう。
<p class="adminmenu"><%=navi_user%></p>
navi_userプラグインと反対に、管理用に必要なボタン「更新」「設定」を表示します。使い方はnavi_userと同じです。
カレンダーを表示します。日記が書かれている月のみをリストします。ヘッダやフッタに埋め込んで使います。パラメタはありません。このプラグインをどこかに入れておかないと、日記閲覧者は過去の日記を読むことができなくなってしまいます。
外部ファイルを日記に読み込みます。主な用途は、ヘッダやフッタに、すでにある定型ファイルを挿入したいような場合です。そのままの形で埋め込むので、挿入するファイルはHTMLでなければなりません。パラメタとしてひとつのファイル名をとるので、以下のように使います。
<%=insert 'menu.html'%>
このプラグインは、ファイルにアクセスするため、tdiary.confで@secureがfalseに設定されていないと利用できません。
日記本文中で、自分の日記内へのリンクを簡単に作成します。<a href="〜">...</a>とやってもよいのですが、こちらの方がサーバの引っ越しやmod_rewriteを利用してURLを変更した場合などに強くできます。
最初のパラメタにリンク先の日付とアンカーを「YYYYMMDD#pXX」(YYYY年MM月DD日のXX番目のセクション)や「YYYYMMDD#cXX」(YYYY年MM月DD日のXX番目のツッコミ)のような形式で指定します。2番目のパラメタには、リンクにする文字列を指定します。
<%=my '20020301#c01', 'そのツッコミ' %>はひどい(笑)。
続いて、プラグイン集について説明します。プラグイン集は、tDiaryユーザが作った数々のプラグインを集めたものです。tDiaryフルパッケージをインストールした場合にはmisc/pluginディレクトリにありますし、そうでない場合にもtDiary.Netから入手することができます。これらのプラグインファイルは、は自分でpluginディレクトリにコピーして利用します。
ここでは、プラグイン集に収録されているプラグインのうち、いくつか代表的なものについて簡単に解説します。これら以外にも、たくさんのプラグインが収録されています。使い方の説明は、個々のプラグインファイルの先頭を参照してください。
title_list.rbファイルに含まれています。現在表示中の月のタイトル一覧を表示します。ヘッダやフッタに埋め込んで使います。単に一覧を表示するだけなので、きちんとレイアウトするにはtableタグを使ったり、CSS(テーマファイル)を書き換える等の工夫が必要になります。
src.rbファイルに含まれています。日記本文に外部にあるファイルを埋め込むために使います。デフォルトプラグインのinsertとの違いは、insertがファイルの中身をそのまま埋め込むのに対し、srcは「<」「>」「&」などのHTML的に意味のある文字がそのまま表示されるように「<」「>」「&」等で置換してくれる点です。このため、srcプラグインは普通のテキストファイルやプログラムのリストを埋め込むのに適しています。
なお、insertと同様、このプラグインも@secureがfalseでないと使えません。
src.rbファイルに含まれています。srcプラグインと違い、パラメタに直接文字列を指定するタイプです。何がうれしいかと言うと、srcと同様、HTML的に意味のある文字をエスケープしてくれる点です。1行だけの文字列であれば以下のように使えますが、
<%=src_inline 'HTMLのタグは「<」で始まり「>」で終わります'%>
複数行に渡るような場合には以下のようにすると楽でしょう(Rubyのヒアドキュメント機能を活用)。
<%=src_inline <<TEXT HTMLのタグは「<」で始まり「>」で終わります。 このため、文章中に「<」を書くときは「<」、 「>」を書くときは「>」と書かねばなりませ んが、src・src_inlineプラグインではそのよう なことを考えなくても大丈夫です。 TEXT %>
また、挿入する文章に空改行が含まれている場合は注意が必要です。tDiaryの文法では、空改行はセクションの終了を意味するので、このままだとそこでセクションが切られてしまいます。空改行がある場合には、空白をひとつ入れる等の工夫をして下さい。
dropdown_calendar.rbには、デフォルトのcalendarを置き換えるプラグインが含まれています。このように、同名のプラグインを作ると、元のプラグインを置き換えることが可能です。
dropdown_calendar.rbのcalendarプラグインは、一覧形式でカレンダーを表示するデフォルトのcalendarと違い、ドロップダウンリストとしてカレンダーを表示します。長年日記を続けて、デフォルトのカレンダーが大きくなりすぎたら、このプラグインを使ってみるといいかも知れません。使い方はデフォルトのcalendarと全く同じです。
日毎表示の時に、ナビゲーションボタンの「更新」を「編集」に置き換えるプラグインです。標準の「更新」ボタンは今日の日記を追加するモードになりますが、editプラグインを入れて「編集」にすることで、現在表示されている日記を直接編集できるようになります。
一般的なカレンダーと同じ表形式を使って、過去の日記にアクセスできるようにするプラグインです。ヘッダやフッタに入れて使います。詳しくはcalendar2.rbを見てください。
最近書いた日記のタイトル、サブタイトルを表示します。title_listプラグインとの違いは、常に最新の日記を対象にする点です。ヘッダやフッタに入れて使いますが、テーブルを使うか、テーマを書き換えてレイアウトを工夫しないと使えないでしょう。詳しくはrecent_list.rbを見てください。
最近あったツッコミを新しい順にリストアップします。ヘッダやフッタに入れて使います。詳しくはrecent_comment.rbを見てください。
ツッコミの数でランキングを作ります。ヘッダやフッタに入れて使います。詳しくはcomment_rank.rbを見てください。