Outline

書式プラグイン(version 1.3.9 ～)

書式プラグイン(version 1.3.9 ～)

1. 概要

書式プラグインは、ブログ記事の書式を拡張するためのプラグインです。

書式プラグインは、ブログへの記事投稿時のブログ記事本文上の {{example}} もしくは {{example(param)}} を生成した文字列で置き換えます。

2. 要件

2.1. 必須要件

plugin/format 以下のフォルダにプログラムファイルを格納してください。
プログラムファイルのファイル名は、書式プラグイン名 + '.rb' にしてください。
- ブログ記事本文上に {{example}} と記述する書式プラグインのファイル名は example.rb となります。
書式プラグインのクラス名は、必ず先頭が大文字のアルファベットでなければなりません。
書式プラグインのクラス名は、必ず _FormatPlugin にしてください。
ブログ記事本文上に {{example}} もしくは {{example(param)}} と記述された場合、インスタンス化されるクラスは Example_FormatPlugin となります。
- ルールは単純に先頭のアルファベットを大文字にし、後ろに _FormatPlugin を足した文字列をクラス名としたクラスです。
書式プラグインクラスは、以下に相当するメソッドを持つ必要があります。
- 引数無しのコンストラクタ
書式プラグインクラスは、必要に応じて以下のメソッドを定義して下さい。不要な場合は定義しなくても構いません。
- 単独行処理
  - def plugin_preset(param, vars) - 事前処理
  - def plugin_contents(param, vars) - 書式変換
- インライン処理
  - def plugin_preset_inline(param, vars) - 事前処理
  - def plugin_contents_inline(param, vars) - 書式変換
インスタンス変数を利用してはいけません。
- 内部メソッドを定義する場合は、インスタンス変数で値を渡すのではなく、必ずメソッドの引数による受け渡しを行ってください。
- 書式プラグインインスタンスのキャッシュ利用を想定した要件です。
利用者に不正な引数指定などを知らせる場合は、メソッド内で FormatPluginWarning を raise してください。
- FormatPluginWarning.new の第１引数には、ブログ本文に埋め込む文字列を指定してください。
- FormatPluginWarning.new の第２引数には、詳細な説明を記載してください。

2.2. 慣習

FormatPluginUtils クラスをミックスインし、get_format_plugin_parameter を利用することで標準的な書式に従った param の解析を行うことを推奨します。
- 詳細は読み進めれば後に説明あり。
FormatPluginWarning.new の第１引数のブログ本文に埋め込む文字列の書式は以下の通りとします。
- メッセージ(参考情報名１ = 参考情報値１, 参考情報名２ = 参考情報値２, ...)
- 例）画像番号指定ミス(画像番号 = 0)
FormatPluginWarning.new の第２引数の詳細な説明の書式は以下の通りとします。
- ですます系のメッセージ(参考情報名１ = 参考情報値１, 参考情報名２ = 参考情報値２, ...)。
- 例）画像番号に対応する添付ファイルがありませんでした(画像番号 = 0)。

3. メソッド概要

3.1. 単独行とインラインについて

本文の書き方に応じて呼び出される処理が分かれます。

１つは単独行処理で、以下のように本文を記述した場合に起動する処理を言います。

メール本文の１行目。上下ともに１行空いて example 書式プラグインが単独行で書かれている場合

{{example}}

メール本文の５行目

この場合、plugin_preset および plugin_contents メソッドが呼び出されます。

もう１つはインライン処理で、以下のように本文を記述した場合に起動する処理を言います。

１行の文章中に {{example}} のように書式プラグインを書いた場合

この場合、plugin_preset_inline および plugin_contents_inline メソッドが呼び出されます。

3.2. メソッドの引数について

４つあるメソッドの引数はいずれも同じ意味合いを持っています。

3.2.1. param

param は {{example(param)}} の () の中の文字列です。param は単独行の文字列であることもあれば、複数行の文字列である場合もあります。

書式プラグインは param を自由に解釈できますが、標準的な書式及びその書式に従った解析メソッド（FormatPluginUtils#get_format_plugin_parameter）の利用を推奨します。

標準的な書式は以下の通りです。

単一行の場合

{{書式プラグイン名(パラメータ１/パラメータ２/.../オプション名１@オプション値１/オプション名２@オプション値２/.../!無効対象オプション名)}}

複数行の場合

{{書式プラグイン名(パラメータ１/パラメータ２/.../オプション名１@オプション値１/オプション名２@オプション値２/.../!無効対象オプション名
コンテンツ１行目
コンテンツ２行目
コンテンツ３行目
...
)}}

標準的な書式の解析方法

まずは以下のように書式プラグインに FormatPluginUtils をミックスインしてください。

require 'plugin/format/lib/format_plugin_utils'

class Example_FormatPlugin
	include FormatPluginUtils

	# ...
end

こうすることで書式に従った解析を行う get_format_plugin_parameter メソッドを利用できるようになります。

get_format_plugin_parameter メソッドの引数は以下の通りです。

順番	名前	概要	デフォルト値
1	param	param をそのまま指定してください。	－
2	vars	vars をそのまま指定してください	－
3	required_param_count	必須パラメータ数を指定して下さい。必須パラメータ数以降のパラメータをオプションと見なします。もしも param に含まれるパラメータが数に満たなかった場合は、エラーと見なします。	0
4	option_alias	オプション名の省略形と正式名の対応を Hash で指定します。	{}
5	option_defaults	オプションにデフォルト値がある場合は、オプション名をキー／デフォルト値を値とした Hash を指定してください。オプション名には省略名と正式名の両方が利用できます。推奨は正式名です。	{}

get_format_plugin_parameter メソッドの戻り値は、以下の値を持つ Array です。

順番	名前	概要
1	params	パラメータの値を Array で返します。
2	option	オプションの値を Hash で返します。キーは正式名です。
3	content	単一行の場合は nil を複数行の場合は、コンテンツの内容を文字列で返します。コンテンツには改行も含みます。

get_format_plugin_parameter メソッドを利用することで option に param の内容だけではなく、以下の内容も反映されます。

3.2.2. vars

vars は、ブログID(:blogid)や投稿ID(:postid)やなどの情報を持った Hash です。

vars が持つ Hash の主なキーと値の対応を以下に示します。

キー	値	plugin_preset 系での利用可否	plugin_contents 系での利用可否
:postid	ブログ上で投稿記事を一意に識別する投稿ＩＤ	○	○
:encoding	ブログから情報を取得する場合のエンコーディング（詳細は文字コードを参照のこと）	○	○
:attachment_urls	添付ファイルの URL を格納したハッシュ（添付ファイルの格納順に 1 から 2, 3, 4 ... というインデックスで URL 文字列が格納されている）	－	○
:thumbnail_urls	添付ファイル（画像）のサムネイル URL を格納したハッシュ（添付ファイルの格納順に 1 から 2, 3, 4 ... というインデックスで URL 文字列が格納されている）	－	○
:related_attachment_urls	関連ファイルの URL を格納したハッシュ（関連ファイルのＩＤをキーとし、URL 文字列が格納されている）	－	○
:related_thumbnail_urls	関連ファイル（画像）のサムネイル URL を格納したハッシュ（関連ファイルのＩＤをキーとし、URL 文字列が格納されている）	－	○
plugin_preset 系メソッドで返した Hash のキー	plugin_preset 系メソッドで返した Hash の値	△	○
ブログヘッダーのキー（省略形および正式名）	ブログヘッダーのキーに対応する値	○	○

ただし、plugin_preset 系と plugin_contents 系では呼び出しのタイミングによって利用可能／不可能な値があります。

参考までにシステムの動作の概要を以下に示します。

ブログ本文に埋め込まれた書式プラグインの plugin_preset 系メソッドを全て呼び出す。呼び出す順番は、ブログ本文の上から順番から。
一時的にブログ記事を投稿し、投稿ＩＤを取得する。
添付ファイルを投稿する。
書式プラグインの plugin_preset 系メソッドの戻り値で何らかの処理の指示があれば、それを処理する。
ブログ本文に埋め込まれた書式プラグインの plugin_contents 系メソッドを呼び出し、ブログ本文に結果を埋め込む。呼び出す順番は、ブログ本文の上から順番。
書式プラグインを適用した内容を再投稿する。

上記順序でシステムが動作するために利用できる vars の内容が異なります。

plugin_preset 系メソッドはブログ本文の上から順番に呼び出されるため、下にある plugin_preset 系メソッドはそれよりも上にある plugin_preset 系メソッドが設定した内容を参照できます。利用可否を△と書いた理由は、順番に応じて参照できる情報が変わることを表しています。

plugin_preset 系メソッドで返した Hash については、後に説明する plugin_preset 系メソッドの情報を参照してください。

ブログヘッダーの情報とは、例えば以下のような情報です。

省略名	正式名	概要
"tit"	"title"	ブログ記事タイトル（指定していない場合は nil）
"dat"	"dateChanged"	ブログ記事投稿日時（指定していない場合は nil）
"cats"	"categories"	カテゴリ（指定していない場合は nil）
"keys"	"mt_keywords"	キーワード（指定していない場合は nil）
"tags"	"mt_tags"	タグ（指定していない場合は nil）
－	他、ヘッダーのキー	対応する値（指定していない場合は nil）

上記の表に記載のあるブログヘッダーは標準仕様として定めたものです。参照の際は必ず太字の省略名のキーを利用してください。

3.3. plugin_preset 系メソッドについて

plugin_contents 系メソッドに先立って呼び出される事前処理用メソッドです。

本メソッドは以下の目的で利用します。

ウェブログプラグインに対して指示を出すため。
- 例えば画像のサムネイル作成の指示を出したい場合などです。
- 詳細は「ウェブログプラグイン－書式プラグイン間通信」を参照して下さい。
他の書式プラグインに対して指示を出すため。
- 現時点ではまだ具体的利用事例が無いためうまく説明できませんが、例えばある特定の書式プラグインの呼び出し一覧を出したい場合などに利用できます。

本メソッドを定義する場合は、必ず Hash を返して下さい。

返した Hash は vars にマージされ、他の書式プラグインから参照できるようになります。

3.4. plugin_contents 系メソッドについて

ブログ本文に埋め込まれた書式プラグインの記述をどのように変換するかを具体的に支持するメソッドです。

メソッドの戻り値が、任意の HTML 文字列となるように定義してください。

書式プラグインを呼び出すきかっけとなった、ブログ記事本文上の {{example}} もしくは {{example(param)}} が戻り値の文字列によって置き換えられて、ブログ本文となります。

4. 書式プラグインの共通設定の参照方法について

書式プラグインの共通設定とは conf/02_user/plugin.rb の以下の設定のことです。

M2W_FORMAT_PLUGIN_CONF = { # 書式プラグインの書式を設定します。 'COMMON' => { 'key1' => '値１', 'key2' => '値２', 'key3' => '値３', }, }

この設定値を参照することで、動作が変わるよう書式プラグインを実装できます。

まずは以下のように書式プラグインに FormatPluginUtils をミックスインしてください。

require 'plugin/format/lib/format_plugin_utils'

class Example_FormatPlugin
	include FormatPluginUtils

	# ...
end

こうすることで書式プラグインの共通設定を取得する format_plugin_common_conf メソッドを利用できるようになります。

format_plugin_common_conf メソッドの引数は以下の通りです。

順番	名前	概要	デフォルト値
1	vars	vars をそのまま指定してください。	－
2	key	取得する設定のキーを指定してください。	－

指定したキーに対する値が返ってきます。

5. 事例

img.rb

 # coding: UTF-8
 
 require 'plugin/format/lib/format_plugin_warning'
 
 #=添付画像を貼り付ける書式プラグイン
 #
 # 最初の著者:: トゥイー
 # リポジトリ情報:: $Id: img.rb 194 2011-08-11 13:36:56Z toy_dev $
 # 著作権:: Copyright (C) Ownway.info, 2011. All rights reserved.
 # ライセンス:: CPL(Common Public Licence)
 class Img_FormatPlugin
 
         def plugin_contents(param, vars)
                 src_url = get_url(param, vars)
 
                 if src_url != nil then
                         return %Q!<div><img src="#{src_url}" /></div>!
                 else
                         raise FormatPluginWarning.new(
                                 "画像番号指定ミス(画像番号 = #{param})",
                                 "画像番号に対応する添付ファイルがありませんでした(画像番号 = #{param})。")
                 end
         end
 
         def plugin_contents_inline(param, vars)
                 src_url = get_url(param, vars)
 
                 if src_url != nil then
                         return %Q!<img src="#{src_url}" />!
                 else
                         raise FormatPluginWarning.new(
                                 "画像番号指定ミス(画像番号 = #{param})",
                                 "画像番号に対応する添付ファイルがありませんでした(画像番号 = #{param})。")
                 end
         end
 
         def get_url(param, vars)
                 attachment_urls = vars[:attachment_urls]
 
                 if attachment_urls != nil then
                         if param == nil then
                                 param = "1"
                         end
 
                         if param =~ /^([0-9]*)$/ then
                                 index = param.to_i
                                 if attachment_urls.has_key?(index) then
                                         return attachment_urls[index]
                                 end
                         else
                                 return nil
                         end
                 end
         end
 
 end

6. 変更履歴

version 1.0.1 ～
- とりあえずの仕様を記述した。
version 1.0.4 ～
- 基礎的な仕様を整理し、記述した。
version 1.0.5 ～
- 書式プラグインファイルの格納フォルダ／ファイル名および書式プラグインクラス名の仕様を追加した。
- インスタンス変数の利用を禁止する仕様を追加した。
- 警告通知の仕様を追加した。
version 1.2.3
- FormatPluginUtils#get_format_plugin_parameter メソッドを利用した param の解析を慣習として追加した。
- plugin_preset 系メソッドの記述を追加した。
- その他、全体的に内容を充実させ、単純なケアレスミスや表現も修正した。
- 変更履歴を追加した。

version 1.2.3（追加で変更）
- ブログヘッダーの情報を利用する場合は、省略名でも正式名でもどちらでも良いとしていたが、必ず省略名を利用するよう修正した。正式名は metaWeblog API を想定したものだが Atom API には関係ないため省略名で統一するためこのような仕様とする。

version 1.3.0
- HTML メールに対応するため vars に related_attachment_urls および related_thumbnail_urls を追加した。

2013/06/28
- 「4. 書式プラグインの共通設定の参照方法について」を追記した。時期の調査までは行わないが、この方法自体はかなり初期のことから使えたものである。
- vars から blogid を削除した((恐らく 1.3.7 から存在しないと思われる。))。

version 1.3.9
- vars の postid の「plugin_preset 系での利用可否」を「○」に変更した*1。

*1なぜ postid を plugin_preset 系で使えるようにしていなかったのか…ものすごい疑問である。何か理由があったのか？とても重要な情報なのに。しかも対応は簡単だったのに。1.3.7 のときに混入したバグかもしれない。しかし、1.3.9 以降、使えるようにする。

Latest File Release

トピックス (Topics)

最近の更新 (Recent Changes)

2015-05-21

2015-05-13

2015-03-05

2014-10-03

2013-08-22