ブログに設定を追加するプラグイン(その2)

昨日に続いて、今日はConfig Assistantプラグインのyamlファイルの書き方を紹介します。

1.yamlとは

「yaml」は「YAML Ain't Markup Language」の略で、配列やリストなど、構造化されたデータを記述するための言語です。
XMLも同じような用途に使うことができますが、XMLよりも簡潔に記述できるのが特徴です。

2.config.yamlファイルの作成

Config Assistantプラグインは、「config.yaml」というyamlファイルに基づいて、設定の画面を出力したり、テンプレートタグを追加したりします。
config.yamlファイルの書き方は以下のようになります。
昨日公開したサンプルのconfig.yamlファイルを見ながら、以下の解説をお読みいただくと良いでしょう。
なお、インデントは必ずスペースで行います。タブは使うことができません。

id: プラグインのID
key: プラグインのキー
name: プラグインの名前
blog_config_template: '<mt:PluginConfigForm id="テンプレート情報のID">'
author_name: プラグインの作者の名前
description: プラグインの概要
settings:
  フィールド名1:
    scope: blog
    default: 初期値
  フィールド名2:
    scope: blog
    default: 初期値
  ・・・
  フィールド名n:
    scope: blog
    default: 初期値
plugin_config:
  テンプレート情報のID:
    fieldset:
      フィールド名1:
        type: フィールドのタイプ
        values: セレクトの選択肢のリスト(typeがselectの場合のみ)
        rows: テキストエリアの行数(typeがtextareaの場合のみ)
        label: フィールドのラベル
        hint: フィールドの下に表示するヒント
        tag: フィールドに対応させるテンプレートタグ名
      フィールド名2:
        ・・・
      フィールド名n:
        ・・・

個々の項目の内容は以下の通りです。

id: プラグインのID

config.yamlファイルは、内部的にはプラグインとして認識されます。
「プラグインのID」の部分には、自分でIDを決めます(IDは英数字で付けます)。

id:プラグインのキー

プラグインのIDと同様に、プラグインのキーを自分で決めます(キーも英数字で付けます)。

name: プラグインの名前

プラグインの名前を指定します。
この名前は、MTのプラグイン一覧のページに表示されます。

blog_config_template: '<mt:PluginConfigForm id="テンプレート情報のID">'

後で設定ページのテンプレートの情報を定義しますが、その情報につけたIDを、この部分の「テンプレート情報のID」に指定します。

author_name: プラグインの作者の名前

プラグインの作者の名前(通常はご自分の名前)を指定します。
この作者名は、MTのプラグイン一覧のページに表示されます。

description: プラグインの概要

プラグインの概要を指定します。
これもMTのプラグイン一覧のページに表示されます。

settings:

「settings:」行以降に、設定を保存するフィールドの情報を指定していきます。

それぞれのフィールドの名前は、「フィールド名1」等の部分に指定します。
フィールド名は英数字で付けます。
また、フィールドの初期値を指定したい場合は、「default: 初期値」の部分に指定します。

plugin_config:

「plugin_config」行以降で、設定画面のテンプレートの情報と、各フィールドに対応させるテンプレートタグ名を指定します。

まず、設定画面のテンプレートの情報にご自分でIDを付けて、「テンプレート情報のID」に指定します。
「フィールド名1」等には、「settings:」の部分で指定したフィールド名を入れます。

「type: フィールドのタイプ」では、フィールドのタイプを指定します。
フィールドのタイプは、以下のいずれかから選ぶことができます。

「フィールドのタイプ」に指定する値フィールドのタイプ
text1行のテキスト入力欄
textarea複数行のテキスト入力欄
checkboxチェックボックス
selectセレクト

タイプとしてselectを指定する場合、「values:」の後に、選択肢をコンマで区切って並べます。
また、タイプとしてtextareaを指定する場合、「rows:」の後に、入力欄の行数を指定します。

「label: フィールドのラベル」と「hint: フィールドの下に表示するヒント」では、フィールドのラベル(フィールドの左に表示される文章)と、ヒント(フィールドの下に表示される文章)を指定します。

「tag:」では、フィールドに対応させるテンプレートタグの名前を指定します。
ただし、タグ名には先頭の「MT」はつけません。

通常はファンクションタグが追加され、そのファンクションタグで設定値を読み取ることができます。
また、フィールドとしてチェックボックスを使う場合、そのチェックの値を出力するファンクションタグにすることもできますが、チェックのオン/オフを判断するブロックタグにすることもできます。
その場合は、タグ名の最後に「?」を付けます。

3.config.yamlファイルのアップロード

Movable Typeの「plugins」ディレクトリの中にサブディレクトリを作り、そこへconfig.yamlファイルをアップロードします。
これで、config.yamlファイルがプラグインとして認識され、プラグイン一覧のページに表示されるようになります。
また、テンプレートタグも追加されます。

なお、アップロード先のサブディレクトリの名前は、プラグインの内容に合わせたものにするようにします。

4.フィールドの表示順序の問題

プラグインの設定のページには、config.yamlファイルの「plugin_config」部分に基づいて、設定画面が表示されます。
ただ、plugin_config部分でのフィールドの順序と、設定画面でのフィールドの順序は、必ずしも一致しません(Perlではハッシュの順序は不定なため)。

今のところ、順序を指定する方法は用意されていません。
順序を指定できるようにするには、プラグインのコードを改良することが必要です。

MT Cloud Starter Kit
Movable Typeのプラグイン集「MT Cloud Starter Kit」をぜひご利用ください