プラグインによるテンプレートタグの実装

PowerCMS Xでは、これまでの PowerCMSと同様にプラグインによってテンプレート・タグを追加することができます。追加できるタグの種類は以下の4種類です。各タグについては、テンプレート・タグの基本 のページを参照してください。また、プラグインの作成方法については、プラグイン作成の基礎のページを参照してください。

  • ファンクションタグ
  • 条件・ダグ
  • ブロックタグ
  • グローバル・モディファイア

サンプル・プラグインには、条件タグ「ifmyfirstplugin」、ファンクションタグ「myfirstpluginfunction」の実装サンプルが含まれています。


PowerCMS との違い

  • プラグインはPerlではなく、PHPで記述します。
  • PowerCMSのダイナミック・パブリッシング(DynamicMTML)プラグインについては、一部互換性があります。
  • ブロックタグでは、第5引数「$counter(何回目のループか)」が渡されます。
  • ブロックタグでは、予約変数をセットするためのメソッド(set_loop_vars)が利用できます。
  • ブロックタグでは、プロパティlocal_vars(ブロック内でだけ有効なローカル変数)、local_params(ブロック内でだけ有効なローカル配列)が指定できます。

config.json でのテンプレート・タグの定義

    "tags": {
        "function": {
            "タグ名" : {
                "component" : "クラス名",
                "method" : "クラスのメソッド名"
            }
        },
        "conditional": {
            "タグ名" : {
                "component" : "クラス名",
                "method" : "クラスのメソッド名"
            }
        },
        "block": {
            "タグ名" : {
                "component" : "クラス名",
                "method" : "クラスのメソッド名"
            }
        },
        "modifier": {
            "タグ名" : {
                "component" : "クラス名",
                "method" : "クラスのメソッド名"
            }
        },
    },

テンプレート・タグのPHPコード

カスタム・テンプレートタグは、PowerCMS Xのために開発されたテンプレートエンジン「PAML」のプラグインとして登録します。


クラス「PAML」のメソッド


$ctx->assign( $name, $value );

変数に値をセットします。

パラメタ
  • mixed $name : セットする変数名もしくは変数の配列
  • array $value : セットする値の配列

$ctx->stash( $name, $value );

変数の格納場所です。

パラメタ
  • string $name : セットまたは取得する変数名
  • mixed $value : セットする値
戻り値
  • mixed $var : 格納された値

$ctx->false();

ブロックタグが1回もループせずに終了する時、このメソッドを呼び出します(最初のループもスキップされます)。

パラメタ(なし)
戻り値
  • bool false : 常にfalseを返します

$ctx->build_page( $path, $params, $cache_id, $disp, $src );

テンプレートをビルドし、出力するか結果を返します。

パラメタ
  • string $path : テンプレートファイルのパス
  • array $params : テンプレート変数にセットする値の配列
  • string $cache_id : キャッシュID
  • bool $disp : 結果を出力するかどうか
  • string $src : ファイルの代わりに利用するテンプレートのソース文字列
戻り値
  • string $content : ビルドされた結果のテキスト
戻り値
  • string $content : ビルドされた結果のテキスト

$ctx->render( $src, $params, $cache_id );

ファイルからではなく、テンプレートのソースからビルドします。

パラメタ
  • string $src : テンプレートのソース
  • array $params : テンプレート変数にセットする値の配列
  • string $cache_id : キャッシュID
戻り値
  • string $content : ビルドされた結果のテキスト

$ctx->build( $src, $compiled = false );

テンプレートのソースからビルドした値を返します。コンパイル結果をキャッシュしません。

パラメタ
  • string $src : テンプレートのソース
  • bool $compiled : 指定した場合、ビルド結果ではなくコンパイル後のPHPコードを返す
戻り値
  • string $build : ビルドされた結果のテキスト

$ctx->set_loop_vars( $counter, $params );

ブロックタグ内で、カウンタ値とループ対象の配列変数またはオブジェクトから予約変数に値をまとめてセットします ( '__index__', '__counter__', '__odd__','__even__', '__first__', '__last__', '__total__' )。

パラメタ
  • int $counter : ループのカウンタ値
  • array $params : ループ対象の配列変数またはオブジェクト

$ctx->localize( [ 'name1', 'name2', [ 'name3', 'name4' ] ] );

$ctx->restore ( [ 'name1', 'name2', [ 'name3', 'name4' ] ] );

変数のスコープをローカライズします。
ブロックの初回 ( $counter == 0 )で localize をコールし、ブロックの最後で restore をコールしてください。 引数には、対象の変数名を配列で指定します。 配列の中に配列で指定されたものは $ctx->__stash[ 'vars' ][ $value ] が対象となり、文字列を指定した場合は $ctx->stash( $value ) が対象となります。

$ctx->get_any( $key );

$local_vars[ $key ] と $vars[ $key ] のいずれかに値が存在する時に、その値を受け取ります。


クラス「PAML」のプロパティ(括弧内は初期値)


$vars([])

グローバル・テンプレート変数。

$__stash([])

$__stash['vars'] は $varsの別名。

$local_vars([])

ブロックスコープ内のローカル変数。

$local_params([])

ブロックスコープで主にループ処理に使われる変数やオブジェクト。

プロパティ $local_vars と $local_params は常にローカル変数となります。 ブロックを抜ける時には、これらは自動的にブロックの直前の状態に戻されます。


ファンクションタグ

ファンクションタグは、次のように記述されるタイプのタグです。

    <mt:functiontagname attr="value">

ファンクションタグのコードは、以下のように書きます。メソッドの戻り値がタグの部分と置き換えられます(例: <mt:var>)。または、何も出力せずに単に他のタスクを実行する事ができます(例: <mt:setvar>)。

    function hdlr_function_tagname ( $args, $ctx ) {
        // return 'Something';
    }

ファンクションタグに渡されるパラメタ

  • array $args : タグ属性の配列
  • object $ctx : クラス PAML

クラスPAMLから、PowerCMS Xのアプリケーション・クラス $app にアクセスするには、プロパティ「app」を呼び出します($ctx->app)。データベースアクセスを担うORマッパクラス「PADO」へアクセスするには、$ctx->app->db を呼び出します。


条件タグ

条件タグは、次のように記述されるタイプのタグです。

    <mt:ifconditionaltagname name="name"> ... </mt:ifconditionaltagname>

条件タグ内では、<mt:else> と <mt:elseif> が利用可能です。 条件タグは true(出力) か false(出力しない) のいずれかを返します。

    function hdlr_conditional_tagname (  $args, $content, $ctx, $repeat, $context ) {
        // return true; // or false;
    }

条件タグに渡されるパラメタ

  • array $args : タグ属性の配列
  • string $content : 常に null
  • object $ctx : クラス PAML
  • boolean $repeat : 常に true
  • boolean $context : false を指定すると unless として動作します。

新たに条件タグを作成する際は、true、false を返すかわりに $ctx->conditional_if を返すことによって eq、ne、likeなどのタグ属性を利用できるようになります。

ブロックタグ

ブロックタグは、次のように記述されるタイプのタグです。第4引数「$repeat」が「true」の間、繰り返し実行されます。

    <mt:blocktagname name="name"> ... </mt:blocktagname>

ブロックタグでは、出力される $content を戻り値に指定します。

ブロックタグに渡されるパラメタ

  • array $args : タグ属性の配列
  • string &$content : ※1
  • object $ctx : クラス PAML
  • boolean &$repeat : ※2
  • numeric $counter : ループのカウンタ

※1 $content にはテンプレートの出力結果がセットされます。 $content は最初のループでは null、2回目以降のループではテンプレートブロックのコンテンツがセットされています。

※2 $repeat は最初のループでは true、2回目以降のループでは falseがセットされています。 タグの中で $repeat を true にセットすると、 <mt:blocktagname> ... </mt:blocktagname> ブロック内は繰り返しビルドされ、$content パラメータに新しいブロックコンテンツが格納された状態で再び呼び出されます。

最もシンプルなブロックタグの実装例(1度だけブロックがビルドされます)。

    function some_block_tag ( $args, $content, $ctx, &$repeat, $counter ) {
        return ( $counter ) ? $content : null;
    }

配列の回数だけループするシンプルなブロックタグの実装は下記の通りです。

    function hdlr_blocktag_name ( $args, $content, $ctx, &$repeat, $counter ) {
        // $app = $ctx->app;
        $local_vars = ['local_var1', 'local_var2', 'local_var3'];
        if (! $counter ) {
            $loop_params = ['var1', 'var2', 'var3'];
            if ( empty( $loop_params ) ) {
                return $ctx->false(); // ループをスキップする時
            }
            $ctx->localize( $local_vars ); // 変数のローカライズ
            $ctx->local_params = $loop_params;
        }
        $params = $ctx->local_params;
        $ctx->set_loop_vars( $counter, $params ); // 予約変数をセット
        if ( isset( $params[ $counter ] ) ) {
            $param = $params[ $counter ];
            $ctx->local_vars['__value__'] = $param; // ローカル変数 __value__ に値をセット
            $repeat = true;
        } else {
            $ctx->restpre( $local_vars ); // 変数のリストア
            $repeat = false;
        }
        return $content;
    }

グローバルモディファイア

モディファイアは、テンプレートの変数が表示される前または他のコンテンツに使用される前に適用される関数です。 モディファイアは複数指定できますが、同じモディファイアを一つのテンプレート・タグに指定することはできません。

    function filter_modifier_name (  $str, $arg, $ctx, $name ) {
        // return "Processed {$str}.";
    }

グローバルモディファイアに渡されるパラメタ

  • string $str : テンプレートの出力
  • mixed $arg : 属性値
  • object $ctx : クラス PAML
  • string $name : 呼び出されたモディファイアの名前