MODXのスニペットの使い方

最終更新日
2017.10.12

移行作業中のため一部のページが正しく表示されていない場合があります(o-ω-))

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

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

タグの書き方

一番シンプルなスニペットタグです。

[[mySnippet]]

スニペットのキャッシュを無効にしたい場合以下のように書きます。

[!mySnippet!]

例えばランダム表示や、ログイン状態によって結果が変わるような場合キャッシュを無効にしてタグを記述する必要がありますが基本的にはキャッシュ有りで問題ないと思います。

キャッシュ有効と無効の使い分け

キャッシュ有効にした場合スニペットは結果をキャッシュさせて2回め以降のアクセスはその結果部分をすぐに返します。どんな状態でアクセスしても同じ結果を返すスニペットならキャシュを有効にしておくと良いです。

逆にログインユーザー名を表示するような結果が変わるスニペットの場合キャッシュを有効にしていると表示が変わらなかったり、タイミングが悪ければ最初にキャッシュを作成した時のユーザーの名前が埋め込まれたキャッシュが未ログイン状態や他のユーザーに表示されてしまいます。ユーザー情報やアクセス制限をしている情報を扱うスニペットはキャッシュ無効でコールします。

スニペットパラメータ

スニペットタグにパラメータを付けてスニペットに値を渡すことが出来ます。パラメータがある場合はスニペット名の後に?を付けて&で区切って繋げます。文字列の場合クォート「`」「"」「'」で囲みます。URL のクエリと似た感じですね。パラメータが長い場合は見やすく改行をすることも出来ます。

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

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

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

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

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

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

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

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

スニペット名: mySnippet

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

テンプレートやリソースの適当な場所で以下のようにスニペットタグを記述します。

[[mySnippet?message=`hello`]]

上記の例は単純な文字列「hello」を渡しているので以下のように表示されます。

<div class="message">hello</div>

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

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

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

プレースホルダ

プレースホルダとは Ditto のようにテンプレートを使う場合その中で使用される一時的な変数です。

Ditto のように他のリソースの情報を表示するタイプのスニペットではスニペットのテンプレートに[*id*]と記述しても、スニペットタグを記述した元のリソースのIDが参照されてしまいます。そのためそれぞれの記事に一時的に生成されるプレースホルダを使用します。

基本的に*+に変更するだけで使用できる場合が多いですが Wayfinder では wf. というプレフィックスがついたり、Ditto の [+ditto_iteration+] のように固有の変数が追加で登録されていたりする事がしばしばあります。プレースホルダの名前はスニペットによって変わるので各スニペットのドキュメントを読んで下さい。

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

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

以下の例はリソース一覧表示用スニペットの「Ditto」で使用するテンプレートの中で複数の別のスニペットやモディファイアを使用しています。UltimateParent は上位ツリーのリソース情報を取得するスニペットです。以下は「ID10」よりも下の最初の親のリソース名を表示させます。

<li>
  <div class="date">
    [+date+]
  </div>
  <div class="title">
    [+pagetitle+]
  </div>
  <div class="category">
    [*pagetitle:id(`[[UltimateParent? &top="10" &id="[+id+]"]]`)*]
  </div>
</li>

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

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

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

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

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

公式サイトからいくつかの拡張機能をダウンロードする事ができます。一般的なインストールは以下のような手順で行います。

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

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

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

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

アップデートしたいスニペットを選択して、フォーム内を一度空にして新しい本文コードをコピペします。 assets内のファイルの上書きと管理画面から編集できるスニペットの起動コードの両方の更新をしましょう。

外部情報