PowerCMS Xのテンプレート変数名に関する考察

公開
更新

PowerCMS Xを利用した大規模サイトのテンプレートを書いていて改めて変数名について考えたのですが、結論としては「変数の内容を端的に表した名前であれば何でも良い」と考えました。ポイントを踏まえつつ何らか接頭辞を付けた分かりやすい名前が良いかなと思います。またルールがプロジェクト内で統一できればなお良しでしょう。

カラム名やCMSがセットする変数名に注意

まず、カラム名と同じ変数名は避けます。冒頭に「何らか接頭辞を付けた分かりやすい名前」と書いた理由はカラム名との一致を避ける意図です。以下のようなテンプレートを書いた場合、mt:entriesの外ではテストが、mt:entriesの中では記事オブジェクトのタイトルが表示されます。カラム名と変数名がバッティングしてしまったとしてもCMS本体やプラグインでは$ctx->localize()・$ctx->restore()で変数の退避・リストアをしているはずなので、オブジェクトをループするタグ区間の前後で出力が異なる以外に問題は発生しません。

<mt:setvar name="title" value="テスト" />
((<mt:var name="title" />)) → テスト
<mt:entries model="entry">
<li><mt:var name="title" /></li> → 記事オブジェクトのタイトル
</mt:entries>
((<mt:var name="title" />)) → テスト

もう一つは予約変数のCMSがセットする変数です。以下のような名前は避けます。全てを列挙していないので気になるときは<mt:vardump />で確認しましょう。

  • __first__
  • __last__
  • __even__
  • __odd__
  • __index__
  • __counter__
  • __end__
  • __total__
  • object_count
  • offset_last
  • next_offset
  • prev_offset
  • current_* (current_archive_titleなど)
  • application_* (application_pathなど)

定数があれば…

変数名を付ける際に悩むことは「既に他所で同じ変数名を使っていないか？」ではないでしょうか。例えばテンプレートの冒頭でincludeしているモジュールテンプレート内で変数を色々セットしているケースです。この変数を色々セットするテンプレートの内容は上書きされたくないことが多い気がしており、「定数（const）があれば…」と考えました。

定数（const）のタグは割と簡単に実装できました。$ctx->vars内にこれから使うキー（＝定数名）がなければキーとバリューをセットする仕様により値の上書きを防止します。<mt:setconst />ファンクションタグとsetconstモディファイアを実装してみました。（varsにはないけれどlocal_varsにはあるケースも検討する必要があるかもしれない）

private function set_const( $ctx, $key, $value ) {
    if ( ! array_key_exists( $key, $ctx->vars ) ) {
        $ctx->vars[ $key ] = $value;
        return '';
    }
    return "Error: Constant `{$key}` is already defined.";
}

public function hdlr_function_set_const ( $args, $ctx ) {
    if ( is_string( $args[ 'name' ] ) ) {
        return $this->set_const( $ctx, $args[ 'name' ], $args[ 'value' ] );
    }
}

public function hdlr_modifier_set_const( $value, $arg, $ctx, $name ) {
    if ( is_string( $arg ) ) {
        $this->set_const( $ctx, $arg, $value );
    }
}

以下のようなテンプレートを書いたとき、h1要素の内容は記事のタイトル（entrytitle）になります。

<mt:entrytitle setconst="page_title" />
<mt:entrytext setconst="page_title" />
<h1><mt:var name="page_title" escape /></h1>

その他

値を出力の際にescapeを付けることを基本としており、HTMLを含むコンテンツを変数から出力する場合などは変数名に接尾辞として_htmlを付けることをしています。