MODXのスニペットの使い方

MODX のスニペットの使い方を説明します。

リソース内の記述した場所で実行できるプログラムで、PHP の関数をコールするようなイメージです。管理画面から作成できるので1行プログラムなども簡単に追加できるほか、外部の PHP ファイルを include することもできるので掲示板など複雑な処理を行うスニペットも作成可能です。

書き方

一番シンプルなスニペットコールです。

[[mySnippet]]

スニペットの結果キャッシュを無効にしたい場合以下のように書きます。例えばランダム表示のように URL パラメータ等に関係なくスニペットの出力内容が変わるような場合キャッシュを無効にしてコールする必要がありますが、大抵の場合は上のキャッシュ有りで問題ないと思います。

[!mySnippet!]

パラメータがある場合はスニペット名の後に?を付けて、&で始まるパラメータを繋げていきます。文字列の場合バッククォート「`」で囲みます。URL のパラメータと似た感じですね!パラメータが長い場合は下の例のように見やすく改行をすることも出来ます。

[[mySnippet?
&var1=0
&var2=`hello`
]]

スニペットコール内にコメントを入れる事もできます。

[[mySnippet?
// コメント
&var1=0
&var2=`hellow` // コメント
]]

パラメータはスニペット側でそのままの名前で使用できます。

$var1; // 0
$var2; // hello

スニペットコールは PHP でいうとこんなイメージ…

<?php
mySnippet({
var1: 0,
var2: 'hellow'
});
?>

簡単なスニペットを作ってみる

スニペットコードは PHP で書かれているので、オリジナルのスニペットを作成する場合は PHP の知識が必要になります。
パラメータが空でなければタグ付きで返すという簡単なスニペットを作ってみます。

からスニペット作成画面を開きます。

スニペット名: mySnippet

if ($var) {
  return '<div class="point">'. $var .'</div>';
}

ドキュメントの適当な場所で以下のようにスニペットをコールします。

[[mySnippet?var=`hellow`]]

上記の例は以下のように HTML に表示されます。

<div class="point">hellow</div>

パラメータは MODX タグを使用する事ができます。

[[mySnippet?var=`[*テンプレート変数A*]`]]

この場合[*テンプレート変数A*]に値がなければ何も表示されません。

プレースホルダ

プレースホルダとは Ditto のようにテンプレートを使う場合その中で使用される一時的な変数です。
Ditto のように他のリソースを拾ってくるタイプのスニペットで[*id*]と記述しても、スニペットをコールした元のリソースのIDが参照されてしまいます。
そのためそれぞれの記事用に用意されたプレースホルダを使用します。

基本的に*+に変更するだけですが、Ditto の[+ditto_iteration+]のように固有の変数が追加で登録されていたりするので、これはスニペットによって何が登録されているか変わります。

スニペットを組み合わせて使う

サイトを作りこんでいくとこんな感じで表示したいんだけどなーという細かい希望がいろいろと出てきます。MODX タグはネストによって複数のスニペットを組み合わせてそれぞれの機能をサポートする事ができます。

例えば以下の例はリソース一覧表示用スニペットの「Ditto」で使用するテンプレートの中で複数の別のスニペットやモディファイアを使用しています。

<li>
<span style="font-size:85%">
  [+date+] ([[GetField? &parent=`1` &topid=`59` &docid=`[+id+]`]])
</span><br>
<a href="[~[+id+]~]">
[[if:limit=`23`?is=`[+longtitle+]:!empty`
  &then=`[+longtitle:+]...`
  &else=`[+pagetitle+]`
]]
</a>
</li>

このテンプレートの中でしている処理

  • スニペットの GetField を使用してID59の直下にある親リソースのタイトルを取得しています。
  • スニペットの if を使用して、「長いタイトル」がない場合は「ページタイトル」を使用するという分岐をしています。さらに、モディファイアのlimitを使用してifの結果が長い場合は23文字で切り落とします。

あまり複雑過ぎるネストやモディファイアの乱用はソースの見通しを悪くしたりパフォーマンスを悪化させるみたいなのでほどほどにしておいた方がよさそうです。

配布されているスニペットを新しく追加する

MODX の Evo の拡張機能は自動インストール機能がありません。
既存のスニペットを追加する場合も、配布ページで説明されている手順でインストールする必要があります。

公式サイトからいくつかの拡張機能をダウンロードする事ができます。

一般的なインストールは以下のような手順で行います。

解凍したファイル内にフォルダがあって内容をコピーする必要がある場合、その中のファイルをサーバーの「/assets/」内にコピーします。これもファイルをコピーする必要があるか説明に書いてあると思うので確認してください。

拡張機能によって本体コードのファイル名が違いますが、解凍したファイルの直下にある「スニペット名.tpl」や「スニペット名.txt」というファイルがスニペットの本体コードの場合が多いです。配布ページなどを確認してください。

既存のスニペットをアップデートする

インストールと同じ手順でアップデートしたいスニペットに新しいコードを上書きします。

アップデートしたいスニペットを選択して、フォーム内を一度空にして新しい本文コードをコピペします。

assets内のファイルの上書きと管理画面から編集できるスニペットの起動コードの両方の更新をしましょう。

外部情報