all about blosxom: AboutPlugin - blosxomのプラグインについてのページです。

blosxomのプラグインについてのページです。

blosxomはデフォルトで提供されている機能は少なく、プラグインによってその機能を拡張します。つまり、ちょっと何かをしようとするとプラグインが必要になるということでもあるので、日本語で良くまとまっているページが無いこともあり、この点では敷居が高いというか取っ掛かりが無い感じではあります。

かなり数多くのプラグインが公式サイトにある上、既にblosxomを利用している日本人達が公開していることも多いので、検索エンジンで探してみると欲しい機能を実装したプラグインが見つかるかもしれません。もしかしたらPluginListでも欲しいプラグインが見つかるかもしれません。

プラグインの利用方法

ほとんどのプラグインは設定で指定したプラグインのディレクトリ($plugin_dir)に置くだけで動作します。

設定が必要な場合やフレーバーに変数を記述する必要がある場合、独自にフレーバーを作成する必要がある場合もありますが、それらはプラグインによって違い、一概には説明できないので、プラグイン自体に添付されているドキュメントや配布元のページを参照してください。

プラグイン自体に添付されているドキュメントは、多くの場合PODというフォーマットで書かれている事が多いので、Perlが導入済みのマシンなら、

perldoc plugin

などと、perldocユーティリティで閲覧することが可能です。

もしかしたら設定や変数についてのページがこのWikiにあるかもしれません。

プラグインの作成

プラグインの作成については、いくつかのプラグインを参考にして書き換えながら覚えていくのが一番手っ取り早いと思います。もちろん公式サイトのプラグイン・アーキテクチャの解説(やその日本語訳)も大いに役に立ちます。

プラグイン・アーキテクチャ

blosxomのプラグイン・アーキテクチャは、blosxomのフロー処理をいくつかのブロックに分け、それぞれをプラグインによりそのブロックで行われる処理を上書き(または入れ替え)するという形のものです。フロー処理のブロックは、

start
template
entries
filter
skip
interpolate
head
sort
date
story
foot
last
end

の13種類があります。プラグインでこれらのブロックで行われる処理を上書きするためには、

sub story {
  my($pkg, $path, $fn, $story_ref, $title_ref, $body_ref) = @_;

  $$title_ref = "#" . $num++ . ". " . $$title_ref;

  return 1;
}

といったようにそれぞれのブロックの名前でサブルーチンを作ってやります。

blosxomの変数

blosxomの設定(See Also: SetupBlosxom)の他にもプラグインから扱うことができる変数がいくつかあります。

@plugins: インストール済みで有効なプラグインのリストがセットされる
$path_info: 環境変数PATH_INFO(またはpathパラメータ)を元にしたパラメータがセットされる
$flavour: 訪問者が指定したflavour名(無指定の場合は$default_flavour)
$static_or_dynamic: 動的生成を指定した場合にはdynamic、静的生成を指定した場合にはstaticという文字列がセットされる
$output: 生成された出力がセットされる
$version: blosxomのバージョン番号がセットされる

それぞれの変数はblosxomというnamespaceでアクセスすることができるので、$blosxom::blog_titleや@blosxom::pluginsなどという形で参照します。

プラグイン・サブルーチン

以下はそれぞれのサブルーチンの使い方の簡単な説明です。

start

startサブルーチンはプラグインの有効・無効を切り替えることがメインの目的で定義されているものです。このサブルーチンは必ず必要なので、全てのプラグインでその利用例は見つけることができるでしょう。

また、0を返してやれば、そのプラグインは無効になるので、例えば静的生成の場合にはプラグインを動作させないようにするためには、

sub start {
  return 0 if $blosxom::static_or_dynamic eq 'static';

  return 1;
}

という様にしてやればプラグインのロードによるオーバーヘッドを極力抑えることが出来ます。

template

templateサブルーチンはデフォルトのフレーバー読み込みサブルーチンを上書きするために定義されているものです。themeでの利用がリファレンス的な実装になります。

このサブルーチンをプラグインで利用する場合、プラグイン側では無名サブルーチンを返してやる必要があります。逆に利用しない場合はundefを返してやらねばなりません。

また、このサブルーチンがundef以外を返すと、それ以降に実行されるプラグインでtemplateサブルーチンが定義されていても実行されません。他のプラグインとの排他的な利用になるということなので、利用の際には細心の注意を払いましょう。

entries

entriesサブルーチンはデフォルトのエントリ検索サブルーチンを上書きするために定義されているものです。entries_indexでの利用がリファレンス的な実装になります。

このサブルーチンをプラグインで利用する場合、templateサブルーチンと同じく、プラグイン側では無名サブルーチンを返してやる必要があります。逆に利用しない場合はundefを返してやらねばなりません。

また、このサブルーチンがundef以外を返すと、それ以降に実行されるプラグインでentriesサブルーチンが定義されていても実行されません。他のプラグインとの排他的な利用になるということなので、利用の際には細心の注意を払いましょう。

filter

filterサブルーチンはリストアップされたエントリをフィルタリングするために定義されているものです。excludeでの利用がリファレンス的な実装になります。

引数は、

$files_ref: エントリとみなされた$datadir以下にあるファイル
$others_ref: エントリとはみなされないが$datadir以下にあるファイル

の二つです。

skip

skipサブルーチンは出力の生成が始まる少し前に呼ばれます。lastmodifiedでの利用がリファレンス的な実装になります。

このサブルーチンが0を返すとそのままblosxomの処理は続行されますが、1を返すとinterpolateとhead、sort、date、story、foot、lastの各サブルーチンはスキップされます。つまり、きちんと出力を生成する必要が無い場合には、このサブルーチンを利用することによってblosxomの処理速度を大幅に上げることが出来ます。

具体的にはIf-Modified-Since付きのリクエストに対して、Statusで304 Not Modifiedを返す場合などでしょうか。304 Not Modifiedを返す場合は、HTTPヘッダ以外を出力する必要はないので、出力を生成する必要はなくなります。こういった場合にはskipサブルーチンが大きな意味を持ちます。

また、このサブルーチンがundefや0以外を返すと、それ以降に実行されるプラグインでskipサブルーチンが定義されていても実行されません。他のプラグインとの排他的な利用になるということなので、利用の際には細心の注意を払いましょう。

interpolate

interpolateサブルーチンはデフォルトのフレーバー処理サブルーチンを上書きするために定義されているものです。interpolcate_fancyでの利用がリファレンス的な実装になります。

デフォルトのフレーバー処理サブルーチンは、フレーバー内に記述された変数の処理を担当します。多くの公開されているプラグインはデフォルトのフレーバー処理サブルーチンを前提にして作成されているので、プラグインでこのサブルーチンを利用する場合は、デフォルトの処理を継承した形で実装することが推奨されます。

また、このサブルーチンがundef以外を返すと、それ以降に実行されるプラグインでinterpolateサブルーチンが定義されていても実行されません。他のプラグインとの排他的な利用になるということなので、利用の際には細心の注意を払いましょう。

head

headサブルーチンは出力の開始に呼ばれ、このサブルーチンの終了後にhead.flavourが実際に処理されます。

引数は、

$path: $blosxom::path_infoと等価
$head_ref: head.flavourの内容

の二つです。

sort

sortサブルーチンはデフォルトのエントリ・ファイルのソートサブルーチンを上書きするために定義されているものです。

また、このサブルーチンがundef以外を返すと、それ以降に実行されるプラグインでsortサブルーチンが定義されていても実行されません。他のプラグインとの排他的な利用になるということなので、利用の際には細心の注意を払いましょう。

date

dateサブルーチンはエントリの出力処理ごとに呼ばれ、このサブルーチンの終了後にdate.flavourが実際に処理されます。しかしながらdate.flavourの出力に変化がなかった場合には、実際には出力に追加されません。

引数は、

$path: 処理中のエントリ・ファイルのあるディレクトリのパス
$date_ref: date.flavourの内容
$mtime: 処理中のエントリ・ファイルの更新時刻(unix time形式)
$dw: 処理中のエントリ・ファイルの更新時刻の曜日にあたる部分
$mo: 処理中のエントリ・ファイルの更新時刻の月(文字列)にあたる部分
$mo_num: 処理中のエントリ・ファイルの更新時刻の月(数字)にあたる部分
$da: 処理中のエントリ・ファイルの更新時刻の日にあたる部分
$ti: 処理中のエントリ・ファイルの更新時刻の時間にあたる部分
$yr: 処理中のエントリ・ファイルの更新時刻の年にあたる部分

の九つです。

story

storyサブルーチンはエントリの出力処理ごとに呼ばれ、このサブルーチンの終了後にstory.flavourが実際に処理されます。

引数は、

$path: 処理中のエントリ・ファイルのあるディレクトリのパス
$fn: 処理中のエントリ・ファイルのファイル名
$story_ref: story.flavourの内容
$title_ref: 処理中のエントリ・ファイルのタイトル部分
$body_ref: 処理中のエントリ・ファイルの本文部分

の五つです。

foot

footサブルーチンは出力の最後に呼ばれ、このサブルーチンの終了後にfoot.flavourが実際に処理されます。

引数は、

$path: $blosxom::path_infoと等価
$foot_ref: foot.flavourの内容

の二つです。

last

lastサブルーチンは出力の生成が完了した後、出力する直前に呼ばれます。つまり、生成した結果をいじりたい時やそれを利用して何かしたいに使えます。

end

endサブルーチンは出力が終わった後に呼ばれます。lastとは違い、skipが1を返していたとしても必ず呼ばれるので、プラグインの後始末などにはこれを利用するのが良いでしょう。

プラグイン・ヘルパー・スクリプト

ヘルパー・スクリプトというかプラグインのスケルトン作成スクリプトです。

$ blosxom-plugin-helper.pl test

などと引数にプラグイン名を渡してやると、うまいことスケルトンを作成してくれます。

Download: http://hail2u.net/archives/blugins/blosxom-plugin-helper.pl

プラグインのテンプレート

コピー・アンド・ペーストで利用できるプラグインのテンプレートです。

# Blosxom Plugin: foo
# Author(s): Your Name <your@mail.address>
# Version: 
# Blosxom Home/Docs/Licensing: http://www.blosxom.com/

package foo;

use strict;
use vars qw($bar);

# --- Configurable variables -----------

# --- Plug-in package variables --------

# --------------------------------------

use Foo::Bar;

sub start {
  return 1;
}

sub template {
  return sub {
    my($path, $chunk, $flavour) = @_;
    
    return join '', ($blosxom::template{$flavour}{$chunk} || $blosxom::template{error}{$chunk} || '');
  };
}

sub entries {
  return sub {
    my(%files, %indexes, %others);
    return(\%files, \%indexes, \$others);
  };
}

sub filter {
  my($pkg, $files_ref, $others_ref) = @_;
  return 1;
}

sub skip {
  return 0;
}

sub interpolate {
  return sub {
    package blosxom;
    my $template = shift;
    return $template;
  };
}

sub head {
  my($pkg, $path, $head_ref) = @_;
  return 1;
}

sub sort {
  return sub {
    my($files_ref) = @_;
    return keys %$files_ref;
  };
}

sub date {
  my($pkg, $path, $date_ref, $mtime, $dw, $mo, $mo_num, $da, $ti, $yr) = @_;
  return 1;
}

sub story {
  my($pkg, $path, $fn, $story_ref, $title_ref, $body_ref) = @_;
  return 1;
}

sub foot {
  my($pkg, $path, $foot_ref) = @_;
  return 1;
}

sub end {
  return 1;
}

sub last {
  return 1;
}

1;

Last-Modified: 2006-11-21T18:34:31+09:00