開発（PHP）：コメントアウトからの各種情報の反映
スニペットやプラグインを作成する際や、インストール時に「install/assets」に格納しておいたチャンクやスニペット、プラグインをインストールした際、コードの先頭に特殊なコメントを記述することで、名称やカテゴリーなどを自動的に登録しておくことができます。
スニペットやプラグインの場合は、管理画面で作成する際や一括で更新する際に「DocBlock パーサー」という項目にチェックを入れておくことで、保存時に各項目に記述されます。
目次
基本書式
書式としては次のような感じです。
PHP
/**
* 名称
*
* 説明
*
* @category 種類
* @internal @properties プロパティ
* @internal @modx_category カテゴリー
* @internal @installset base, sample
* @internal @disabled 無効
*/
名称
チャンク名、スニペット名、プラグイン名に当たる項目です。
この項目は必須です。
例
/**
* GetDocument
*
* ...
*/説明
なんの機能であるかを説明する項目です。
この項目は必須です。
反映されるのは最初の行のみで、次の行は無視されます。
例
/**
* GetDocument
*
* リソースの情報を取得する。テンプレート変数も取得可能。
* 続くこの行は無視される。
*
* ...
*/@category
チャンクなどなんの機能であるかの種類を指定する項目です。
この項目は必須です。
次の何れかの値を設定することができます。
| 値 | 説明 |
|---|---|
| chunk | チャンクであることを示します。 |
| snippet | スニペットであることを示します。 |
| plugin | プラグインであることを示します。 |
| module | モジュールであることを示します。 |
例
/**
* ...
* @category snippet
* ...
*/@internal @events
プラグインでどのタイミングで発火するかのイベントを指定する項目です。
複数指定する場合は、カンマ区切りで指定します。
イベントについては次のページをご覧ください。
プラグインのシステムイベント一覧
例
/**
* ...
* @internal @events OnBeforeDocFormSave,OnDocFormSave
* ...
*/@internal @properties
「プロパティ」タブおよび「設定」タブに掲載する項目です。
この項目は必須です。
未指定にしたい場合は&を指定します。
指定方法はパラメーターのように指定します。
例えば次のように記述するとします。
例
/**
* ...
* @internal @properties &foo=テキスト;text;初期値;
* ...
*/
書式
書式としては&ID=項目名;種類;初期値;;補足説明;か、&ID=項目名;種類;選択肢;初期値;補足説明;で指定します。
1つの項目に対して設定をセミコロンで繋ぎます。
複数の項目を指定したい場合は、&ID=項目名;種類;初期値; &ID=項目名;種類;初期値;のように続けて指定します。
ID
&ID=は&に続けて項目の固有の識別子を指定します。
プラグインでは $modx->getPluginCodeメソッドから取得することができます。
項目名
=項目名;のようにイコールの後に表示する項目名を指定します。
種類
コンポーネントの種類を指定します。
指定できる値は次の通りです。
| 設定値 | 説明 |
|---|---|
| text | 単一行の入力欄です。 |
| textarea | 複数行の入力欄です。 |
| list | ドロップダウンリストです。 |
| menu | ドロップダウンリストです。
|
| list-multi | listをスクロールありの表示にし、複数の選択をできるようにしたリストです。 |
| checkbox | チェックによる複数選択できる項目です。 |
| radio | チェックによる単一選択できる項目です。 |
選択肢
listやcheckboxなど複数の選択肢が並ぶ場合に指定します。
値はカンマ区切りで指定します。
例
/**
* ...
* @internal @properties &convert=変換処理;list;enabled,disabled;disabled;
* ...
*/
初期値
初期に入力または選択する値を指定します。
複数選択可能な項目で複数選択したい場合は、カンマ区切りで指定します。
補足説明
項目に対して補足したい説明がある場合に指定します。
項目名の下に表示されます。
@internal @modx_category
分類するカテゴリーを指定します。
既に登録済みのカテゴリーがなければ新規でカテゴリーが追加されます。
この項目は必須です。
未指定にしたい場合は0を指定します。
@internal @installset
- ※ 不明です。
この項目は必須です。
baseかsample、またはその両方を指定します。
@internal @disabled
機能を停止（無効）にするかどうかを指定します。
停止（無効）にする場合は1、有効にする場合は0を指定します。
初期は0です。
その他
他にもいくつかの項目を記述することができます。
例
/**
* GetDocument
*
* リソースの情報を取得する。テンプレート変数も取得可能。
*
* @category snippet
* @version 1.0.0
* @license GNU General Public License (GPL), https://www.gnu.org/licenses/gpl-3.0.html
* @author Taro (https://www.example.co.jp/)
* @lastupdate 2012/03/04
* @internal @properties &
* @internal @modx_category Custom
* @internal @installset base, sample
* @param string &docId 対象のリソースID
* @param string &name 取得するリソース変数名またはテンプレート変数名
* @example [[GetDocument? &name=`pagetitle`]]
*/@version
機能のバージョンを記述します。
「情報」タブに表示されます。
また、「説明」項目にも先頭にbタグを付けて記述されます。
@license
コードのライセンスを記述します。
「情報」タブに表示されます。
@author
著者や作成者、責任者を記述します。
「情報」タブに表示されます。
名前の後には丸括弧でソースコードの提供元のURLを記述することができます。
@authorを複数行指定でき、複数のURLを記述することができます。
例
/**
* ...
* @author Taro (https://www.example.co.jp/)
* @author Hanako
* ...
*/@lastupdate
最終更新日を記述します。
「情報」タブに表示されます。
書式は問わずそのまま表示されます。
例
/**
* ...
* @lastupdate 2012/03/24
* ...
*/@logo
ロゴ画像を記述します。
ルート相対パスで指定します。
（Evolution CMSのインストール先がサブディレクトリであっても、自動的に置き換えてくれるため問題ありません。）
「情報」タブの右上に表示されます。
例
/**
* ...
* @logo /assets/plugins/example/images/logo.png
* ...
*/@reportissues
問題が起きた場合に報告先のURLを記述します。
「情報」タブに表示されます。
@documentation
リファレンスなどのドキュメントとなるページのURLを記述します。
@documentationを複数行指定でき、複数のURLを記述することができます。
「情報」タブに表示されます。
例
/**
* ...
* @documentation https://doc.example.co.jp/
* @documentation https://github.com/foo/bar/docs
* ...
*/@link
その他関連するページのURLを記述します。
@linkを複数行指定でき、複数のURLを記述することができます。
「情報」タブに表示されます。
例
/**
* ...
* @link https://www.example.co.jp/
* @link https://github.com/foo/bar
* ...
*/@param
スニペットのパラメーターについての情報を記述します。
PHPDocの引数と同じ指定の仕方をします。
表向きどこにも表示はされません。
@return
チャンクやスニペットの戻り値についての情報を記述します。
PHPDocの同じ指定の仕方をします。
表向きどこにも表示はされません。
@example
チャンクやスニペットの使い方についてを記述します。
PHPDocの引数と同じ指定の仕方をします。
表向きどこにも表示はされません。