adiary開発マニュアル

リアルタイムメモ書き。

• 共通
• プラグイン開発時のadiary.conf.cgiの設定
• before/after修飾（Ver3.10～）
• 状態イベント
  • タグ、コンテンツ
• インストール、アンインストールイベント
• フォームからの記事投稿時
  • 記事登録の直前
  • 記事登録の後（成功時のみ）
• フォームからのコメント投稿時
  • コメント登録前
  • コメント登録後（成功時のみ）
• 記事の表示状態変更・削除
• コメントの表示状態変更・削除
• その他
  • プライベートモード
  • ブログの設定変更（Ver3.04以降）
  • 記事インポート後
  • ブログクリア、再構築
  • プラグインやデザインの状態変化
  • テーマの状態変化(Ver3.10～)
• 表示イベント(Ver3.10～)
• JavaScript/CSS
• 要望について

共通

• $name …… pluginの名前（インストール名）
• $form …… 投稿時のフォームの内容

細かいルールなど。

• イベントは示した順番に呼ばれる。
• 同じイベントに複数のプラグインがイベントを登録した場合、プラグイン名のアルファベット順（昇順）で呼ばれる。
• 戻り値をチェックするイベントは「0」以外の戻り値のとき失敗とみなされる。
• スケルトンで処理する場合、ファイル先頭にプラグマ「<@40>」を書いてスケルトン関数で処理する。戻り値はreturn構文（例:<$return(0)>）で返す。
• $self->{event_name} (<@v.event_name>）にイベント名が設定される。イベント名に「:」を含む場合は「:」の手前までが設定される。

プラグイン開発時のadiary.conf.cgiの設定

# シンボリックリンクでプラグインをインストール。
# 開発時には便利だけども、実用には向かない。
# Options +FollowSymLinks を忘れずに。
<$v.plugin_symlink = 1>

プラグインを書き換える度に、プラグインを設定画面からインストールをし直すのは大変ですので、この設定をしておくと（シンボリックリンクが使える環境ならば）圧倒的に開発が楽になります。

# すべてのプラグインの実行を止める。プラグインでのトラブル時に。
#<$v.stop_all_plugins = 1>

プラグインの記述等を間違えて本体に影響を与えてしまい、プラグインのアンインストールすらできなくなったときに使用します。

before/after修飾（Ver3.10～）

イベント名の後ろに「#before」や「#after」を定義することで、イベント本体の「前」や「後」に処理するイベントを定義できます。

# 例
BLOG_SETTING#after=skel/_sub/generate_spmenu

• 複数のプラグインで同じ処理が定義されていた場合、1度だけ呼ばれます。
  • その際の呼び出しプラグイン名は不定です。
• 「#」が付かない本体イベントは処理部が重複しても、定義回数だけ実行されます。

状態イベント

投稿などではなく、状態が変化したときに発生するイベントです。1度に複数の記事を削除しても、イベントは1回だけ発生します。

• $artkeys …… 状態が変化した可能性のあるデータのpkeyの配列
  • コメントの場合は、$artkeysのコメントが存在する（した）記事のpkeyの配列
• $comkeys …… 状態が変化した可能性のあるデータのpkeyの配列
  • 未定義の場合は$artkeysに存在するコメントとみなす
• $tag_state_nochange …… trueのときのみ、タグの状態は変化してない

両方未定義の時はすべての記事やコメントが変化したとみなす。

# ブログに存在する記事の状態が変化したとき
$self->call_event('ARTICLE_STATE_CHANGE', $name, $artkeys, $tag_state_nochange);
# ブログに存在するコメントの状態が変化したとき
$self->call_event('COMMENT_STATE_CHANGE', $name, $artkeys, $comkeys);
# ブログに存在する記事かコメントのいずれかの状態が変化したとき
$self->call_event('ARTCOM_STATE_CHANGE' , $name, $artkeys, $comkeys);

最近の記事一覧や、最近のコメント一覧などで使用するイベントです。

タグ、コンテンツ

# タグの状態が変化したとき
$self->call_event('TAG_STATE_CHANGE', $name, $tag_tree);
# コンテンツの状態が変化したとき
$self->call_event('CONTENT_STATE_CHANGE', $name, $content_tree);

インストール、アンインストールイベント

• $name …… プラグイン名

# インストール成功後
$self->call_event("INSTALL:$name", $name);
# アンインストール直前（エラーが返るとアンインストールに失敗する）
my $re = $self->call_event("UNINSTALL:$name", $name);
# 設定値変更後
my $re = $self->call_event("SETTING:$name", $name);

フォームからの記事投稿時

• $art …… 投稿処理後の記事データ

記事登録の直前

my $re = $self->call_event('ARTICLE_BEFORE', $name, $form);
# 記事編集時のみ
my $re = $self->call_event('ARTICLE_BEFORE_EDIT', $name, $form);
# 記事投稿時のみ
my $re = $self->call_event('ARTICLE_BEFORE_POST', $name, $form);

１つでもイベントに失敗したら、記事を登録せずに戻る。

記事登録の後（成功時のみ）

# 記事を初公開時かつPING通知ONのとき（Ver3.14以降）
$self->call_event('ARTICLE_FIRST_VISIBLE', $name, $art, $form);
# 記事を初公開時
$self->call_event('ARTICLE_FIRST_VISIBLE', $name, $art, $form);
# 常に
$self->call_event('ARTICLE_AFTER', $name, $art, $form);
# 記事編集時のみ
$self->call_event('ARTICLE_AFTER_EDIT', $name, $art, $form);
# 記事新規投稿時のみ
$self->call_event('ARTICLE_AFTER_POST', $name, $art, $form);

呼ばれるのはこの順番。

フォームからのコメント投稿時

• $art …… 投稿対象記事の情報

コメント登録前

my $er = $self->call_event('COMMENT_BEFORE', $name, $form, $art);

1つでも失敗した（ret != 0）イベントがあれば、投稿せずに終了する。

コメント登録後（成功時のみ）

$self->call_event('COMMENT_AFTER', $name, $form, $art);
# ブログ編集権限者以外からのコメントの時
$self->call_event('COMMENT_NEW', $name, $form, $art);

• $form->{pkey} …… コメントのプライマリキー

記事の表示状態変更・削除

# 表示状態変更後
$self->call_event('ARTICLES_EDIT',   $name, $keylist, $cnt);
# 削除後
$self->call_event('ARTICLES_DELETE', $name, $keylist, $cnt, $comkeylist);

• $keylist …… 削除した記事のpkeyのリスト（必ずしも削除した記事とは限らない）
• $comkeylist …… 記事の削除により消えたコメントのpkeyリスト
• $cnt …… 実際に削除した記事の数

コメントの表示状態変更・削除

# 表示状態変更後
$self->call_event('COMMENTS_EDIT',   $name, $a_pkeys, $keylist, $cnt);
# 削除後
$self->call_event('COMMENTS_DELETE', $name, $a_pkeys, $keylist, $cnt);

• $a_pkeys …… 変更・削除したコメントがついていた（可能性のある）記事のpkeyリスト
• $keylist …… 変更・削除したコメントのpkeyのリスト（必ずしも変更・削除したとは限らない）。未定義のこともある。
• $cnt …… 実際に変更・削除した記事の数。未定義のこともある。

その他

プライベートモード

# プライベートモードに設定された
$self->call_event('PRIVATE_MODE_ON',  $name);
# プライベートモードが解除された
$self->call_event('PRIVATE_MODE_OFF', $name);

ブログの設定変更（Ver3.04以降）

$self->call_event('SETTING_CHANGE', $name);

「基本設定」「詳細設定」のみです。

記事インポート後

$self->call_event('IMPORT_AFTER', $name, $a_pkeys, $c_pkeys);

ブログクリア、再構築

# ブログが再構築された
$self->call_event('BLOG_REBUILD', $name);
# ブログの付加情報が再構築された
$self->call_event('BLOG_INFO_REBUILD', $name);
# ブログがクリアされた（全記事削除された）
$self->call_event('BLOG_CLEAR', $name);

プラグインやデザインの状態変化

# 何かしらのプラグインがインストールまたはアンインストールされた
$self->call_event('PLUGIN_STATE_CHANGE', $name);
# プラグインの設定が保存された
$self->call_event('PLUGIN_SETTING', $name, $setting_plugin_name);
# デザインが編集された
$self->call_event('EDIT_DESIGN', $name);

テーマの状態変化(Ver3.10～)

# テーマが変更された
$self->call_event('EDIT_THEME', $name);

表示イベント(Ver3.10～)

記事が表示されたときに呼び出されるイベントです。このイベントは引数なく呼び出されます。

• VIEW_ARTICLE : 記事単一表示。_article.html の直後に呼ばれます。
• VIEW_MAIN : 記事の複数表示。_main.html の直後に呼ばれます。

JavaScript/CSS

• イベント名 : JS
  • 指定したJavaScriptファイルを読み込ませる（非同期読み込み/async）。
• イベント名 : JSLIB
  • 指定したJavaScriptファイルを読み込ませる（先に読み込む必要のあるライブラリでのみ使用）。
• イベント名 : CSS
  • 指定したcssファイルを読み込ませる。
• イベント名 : CSSLIB
  • 指定したcssファイルを読み込ませる（先に読み込む必要のある場合）。

要望について

• イベントの種類を増やしてほしい
• イベントの引数を変えてほしい
• イベントの呼び出し順仕様を変更してほしい

などなどイベントシステムへの要望は実装したい機能とそのために必要な要望を具体的に記述して連絡してください。具体性のない要望はおそらく無視します。

要望時に提示した機能（プラグイン）を要望した人が実際に実装しなくても構いません。