Movable Type用ShortCodeプラグイン・その12（yamlファイルの書き方の詳細）

ShortCodeプラグインの最終回として、config.yamlファイルの詳細な書き方を解説します。

1.yamlファイルの書き方

ShortCodeプラグイン用のyamlファイルの書き方は、以下のようになります。

name: プラグインの名前
id: プラグインのID
author_name: プラグインの作者名
author_link: プラグイン作者のサイトのアドレス
description: プラグインの概要
plugin_link: プラグインのページのリンク
version: バージョン番号
shortcodes:
  ショートコード名:
    template: ショートコードの変換方法
    handler: ショートコードを処理するサブルーチン
    description: ショートコードの概要
    snippet: ショートコードのスニペット
    js: ショートコードのスニペットを挿入するJavaScript
    snippets:
      - description: ショートコードの概要
        snippet: ショートコードのスニペット
        js: ショートコードのスニペットを挿入するJavaScript
      - description: ショートコードの概要
        snippet: ショートコードのスニペット
        js: ショートコードのスニペットを挿入するJavaScript
      ・・・
    recurse: 0または1
    cut_br: 0または1
    cut_br_line: 0または1
    cut_p: 0または1
    cut_p_no_content: 0または1
    ltrim: 0または1
    rtrim: 0または1
    trim_first_br: 0または1
    trim_last_br: 0または1
  ショートコード名:
    ・・・

2.プラグインの情報の定義

上記のリストのうち、「バージョン: バージョン番号」までの行は、プラグインの情報を定義する部分です。
各部分の内容は以下の通りです。

2-1.プラグインの名前

Movable Typeの管理画面に表示するプラグイン名を指定します。

2-2.プラグインのID

プラグインを識別するためのIDを、半角英数字で決めます。

2-3.プラグインの作者名

ご自分の名前を入れます。

2-4.プラグイン作者のサイトのアドレス

ご自分のサイトのアドレスを入れます。

2-5.プラグインの概要

プラグインの機能等の概要文を入れます。

なお、作者名および概要文を日本語化することもできます。
その方法は、拙著の「Movable Type Developer's Guide Volume 1」の中で解説しています。

2-6.プラグインのページのリンク

プラグインの利用方法等を解説したページを作って、そのページのアドレスを指定します。

2-7.バージョン番号

プラグインのバージョン番号を決めます。

3.ショートコードの情報の定義

前述のリストの「shortcodes:」の行から後が、ショートコードの情報を定義する部分です。
この部分の書き方は以下のようになります。

3-1.ショートコード名

ショートコードの名前を指定します。
例えば、「foo」という名前のショートコードを使えるようにしたい場合、この行に「foo:」と書きます。
また、この行は「shortcodes:」の行よりインデントして書きます。

3-2.template: ショートコードの変換方法

ショートコードの変換方法をテンプレートタグで定義する際に、そのテンプレートタグを「ショートコードの変換方法」の部分に書きます。
具体的な書き方の例は、こちらの記事を参照してください。

なお、「template:」の行と、次の「handler:」の行は、どちらか1つを指定します。
また、「template:」以降の行は、その前の「ショートコード名:」の行よりインデントして書きます。

3-3.handler: ショートコードを処理するサブルーチン

ショートコードの変換方法をPerlのサブルーチンで定義する場合に、そのサブルーチン名を「$プラグインのID::モジュール名::サブルーチン名」のように書きます。
具体的な書き方の例は、こちらの記事を参照してください。

3-4.description: ショートコードの概要

ブログ記事の編集画面のショートコード一覧に、ここで指定した概要文が表示されます。

3-5.snippet: ショートコードのスニペット

ブログ記事の編集画面で、「ショートコードの挿入」のボタンがクリックされたときに、記事に入力するスニペット（ショートコードの書き方の例）を指定します。
具体的な書き方は、こちらの記事を参照してください。

なお、スニペットをJavaScriptで動的に出力する場合は、この行を使わずに、代わりに次の「js:・・・」の行を使います。

3-6.js: ショートコードのスニペットを挿入するJavaScript

ブログ記事の編集画面で、「ショートコードの挿入」のボタンがクリックされたときに、記事に入力するスニペットをJavaScriptで出力する場合に、そのJavaScriptを指定します。

なお、「js:・・・」の行を指定する場合は、前の「snippet:・・・」の行は指定しません。

3-7.snippets:

1つのショートコードに対して、複数のスニペットを使い分けられるようにしたい場合は、「snippets:」の行の後に、インデントを1段下げて、「description:」「snippet:」「js:」の行を指定します。「description:」の行の先頭には「- 」を入れます。
また、3.4「snippet:・・・」～3.6「js:・・・」の各行は指定しません。

ちなみに、ShortCodeプラグイン本体の「template」および「templatew」ショートコードでは、1つのショートコードに対して、スニペットを4種類ずつ使い分けられるようにしています。
「snippets:」行を使う場合の書き方は、ShortCodeプラグイン本体のconfig.yamlファイルを参照してください。

3-8.recurse

そのショートコードに他のショートコードを入れ子にできるようにする場合は、「recurse: 1」とします。
入れ子をできないようにする場合は、「recurse: 0」とします。

この行を指定しない場合は、「recurse: 1」と指定したのと同じになります。

3-9.cut_br: 1など

ショートコードでは、対象部分に含まれるbrタグ等を自動的に削除したりする機能があります（こちらの記事を参照）。
プラグインでショートコードを追加する場合、それらの機能をデフォルトでオンにするかどうかを指定することができます。
「フラグ名: 1」と書くと、その機能がデフォルトでオンになります。
また、「フラグ名: 0」と書くと、その機能がデフォルトでオフになります。

フラグの種類は以下の通りです。
また、フラグを指定しなかった場合は、「フラグ名: デフォルト値」を指定したのと同じになります。

フラグ内容デフォルト値
cut_br「brタグ+連続するスペースや改行」を単一の改行に変換1
cut_br_line各行末のbrタグを削除0
cut_pブロックの前後のpタグを削除0
cut_p_no_content空のp要素の削除1
ltrim先頭のホワイトスペースの削除1
rtrim最後のホワイトスペースの削除1
trim_first_brブロックの先頭のbrタグの削除0
trim_last_brブロックの最後のbrタグの削除0

例えば、yamlファイルに「cut_p: 1」の行を書くと、ブロック前後のpタグを削除する機能が、デフォルトでオンになります。
一方、「cut_p:」の行を書かない場合、デフォルト値が0なので、「cut_p: 0」と書いたのと同じ動作になります（デフォルトではブロック前後のpタグを削除しない）。