MODx Reflectスニペットのごく簡単な解説

2007-05-19(17:36) /
ネット全般

MODxのDittoスニペット2.x系とセットで提供されるようになったReflectスニペットについて、ごく簡単に。これ自分メモに近いんで、いずれ誰かくわしい人がまとめてくれたらうれしいです。
Dittoスニペット・Reflectスニペット公式解説

Reflectスニペットとは

ドキュメントを、主に日付順で簡潔に表示するためのスニペット。ブログとかでよくある「2007年5月の記事一覧」みたいな日付アーカイブをを作るために使います。Dittoスニペットから分化。MODx0.9.6で正式採用です。なお、2007年5月上旬に発売されたMODx本「MODxでつくる!最強のCMSサイト」は、MODx0.9.5を中心に書かれた解説書なので、Dittoは1.x系。Reflectスニペットの動作解説はありません（少なくともぼくは気づかなかった）。
ちなみに、Ditto内蔵テンプレートの日付アーカイブ表示は、Ditto1.x系とDitto2.x系で以下のような違いがあります。

Ditto1.x……「最近のドキュメントは普通に一覧表示。その下に、古いドキュメントをまとめて日付アーカイブ簡略表示」という動作。
Ditto2.x……Ditto本体は「ドキュメントの高度な並べ替えや、指定した形式での出力」に特化。日付アーカイブ風表示機能はReflectスニペットにおまかせしている。そのため、Ditto内蔵テンプレートから「古いドキュメントの簡略表示」機能がなくなってる（設定次第では出せるのかもしれないけど、素や素に近い状態では表示されない）。

Reflectスニペットの基本動作

Reflectスニペットの実際の動作を超おおざっぱに見てみると、

ドキュメントを日付アーカイブ風表示する。
日付関連の各種指定を、MODx的な書式（≒パラメータをちょこっと付け足す）で割と簡単に出来るようにしている。
ちょっとした設定の工夫でDittoとReflectを連携させ、細かい表示の切り替えを（MODx的には）割と簡単に出来るようにしてる。
なお、内部的にはReflect自体が高度な処理を行っているわけではなく、Dittoの機能を借りて基本的な処理をしている。

です。（※注意：PHPやMySQLは初歩的な事しか知らないんで、あくまでsnippet.reflect.phpやhttp://ditto.modxcms.com/をざっと見た印象です。実際の内部動作はぜんぜん違うかもしれません）

Reflectスニペットのごく簡単な設定方法

http://ditto.modxcms.com/にはいろいろ書いていますが、要するに

dittoSnippetParametersに、Dittoのパラメータを「パラメータ名:値」の形式で入れる。
複数パラメータを指定する場合は「パラメータ名1:値1|パラメータ名:値2」のようにパイプで区切る。

のが基本です。
現状では、表示開始の基準ドキュメントIDを指定するパラメータ（parentsなど）はほぼ必須（※startIDでも一応動くけど、Ditto2.x系では確か非推奨になったはず）。


[!Reflect? &dittoSnippetParameters=`parents:0`!]

という感じで書けば、基準点（上記の例ではID0。つまりサイトトップ）から見て一番上の階層（depth:1）にあるドキュメントが、年・月などをグループ化の基準とした日付アーカイブ風に表示されます。
パラメータを「&dittoSnippetParameters=`parents:0|depth:2`」とすれば、2階層目のドキュメントまで含めて表示。depthを0にする（&dittoSnippetParameters=`parents:0|depth:0`）と、サイト内の全ドキュメントを表示。

Dittoとの連携で、より細かい動作

Reflectは単体でも使えるけど、Dittoと組み合わせるとより複雑な動作を実現できます。以下は、公式サイトの参考例を元に、少しわかりやすく書き足したものです。原文はWordPress style archivesをどぞ。

上記ページに何が書いてあるかというと「WordPressみたいな普通のブログの月別アーカイブ表示っぽいモノを、MODxで作ってみよう」です。もう少し詳しく言うと、

Reflectスニペットで月別アーカイブ表示。Reflectスニペットは「March 2007」「December 2006」のように、月別リンクのみを表示。
月別リンクをクリックすると「その月に書かれたドキュメント一覧」が見れる。これはReflectスニペットではなくDittoスニペットで生成している。
さらに各ドキュメントへのリンクをクリックすると、ドキュメントを見れる。

原文は「ID2」を使いすぎてて少々ややこしいので、以下の例では、

ReflectスニペットはドキュメントID47に設置。
DittoスニペットはドキュメントID48に設置。
で、ReflectとDittoは、ドキュメントID2に属するドキュメント群を日付アーカイブ表示する。

とします。

ReflectスニペットのあるドキュメントID47側の記述


[!Reflect?config=`wordpress` &targetID=`48` &getDocuments=`1` &dittoSnippetParameters=`parents:2`&id=`wp`!]

targetID……Dittoを設置しているドキュメントのID（上の例では「48」）を指定。この指定により、Reflectスニペットが生成する月別リンクなどをクリックすると、ドキュメントID48に飛ぶようになる。「48」は自分のサイトの中身に応じて書きかえ。
getDocuments……1に設定すると、idを指定していてもドキュメントを取得（？）。とりあえず、idを指定した時はgetDocuments=`1`、idを指定しない時はgetDocuments=`0`またはgetDocuments省略、でないとエラーが出る。
dittoSnippetParameters=`parents:2`……Reflectの日付アーカイブ表示の基準となるドキュメントID（上の例では「2」）を指定。後で述べるけど、ここの値は基本的にDitto側のparentsの値と同じにする。
id……ドキュメントID48のDittoインスタンスに割り当てられた固有名。上記例では「wp」。同じサイト内では名前が重複しないようにする。Reflectはこのidを元にパラメータを作成しURLに入れる。idを指定しないとDittoに正しく変数を渡せなくなり、Ditto側のextenders=`dateFilter`などが無意味になる。なお、idを指定しなかった場合、1～1000のうち適当な値がランダムに入れられる。

DittoスニペットのあるドキュメントID48側の記述


<h2>[+wp_month+] [+wp_day+] [+wp_year+]</h2>
 [!Ditto? &id=`wp` &extenders=`dateFilter` &parents=`2`!]

id……Dittoインスタンスの固有名。
extenders=`dateFilter`……Dittoにこの記述を入れる事で、「Reflectが生成したパラメータ付リンクを日付主体で処理し、Reflect経由で来た人に最適なドキュメントのみを表示する」ようになります。たとえばReflect側ドキュメントの「March 2007」リンクをクリックしてDitto側ドキュメントに飛んだ場合、Dittoは「2007年3月」のドキュメントのみを抽出して表示。この記述がないと、Dittoは最新の記事のみ表示したりします。
parents……Dittoの表示の基準となるドキュメントID（上記の例では「2」）を指定。基本的にReflect側でdittoSnippetParameters=`parents:2`みたいにしたなら、Ditto側ではparents=`2`という風に一致させる事。これが不一致の場合、ややおかしな動作になる。
たとえばReflectでdittoSnippetParameters=`parents:0`、Dittoでparents=`2`とすると、Reflect側では「サイトトップ（ID0）から見たドキュメント群を元に生成した、月別アーカイブ」が表示される。だが、たとえば「March 2007」をクリックしてDitto側に飛ぶと「ドキュメントID2に属する、2007年3月に作成されたドキュメント」のみが表示される。よって、Reflect側ではその月に作成されたドキュメントが存在するように見えるのに、リンクをクリックしてみると適合するドキュメントがなく「no document found」と出てくる、といった問題が起こる事がある。

Ditto2:xでページ分割する場合はDitto2.xと1.xの違いを参照。まぁ要するに、「idで指定した値がプリフィックスとなって使われる」事が、MODxではしばしばあるわけです。
…
……

「日記しか書かない」って事なら、きっとWordPressの方が簡単ですよね。うん

こうやって書き連ねてみると、「ブログなら、仕組みをほとんど意識する事なく直感的に設定出来る」事が、MODxでは結構面倒だと改めて気づきました。というか、ぼく自身は「MODxで日付アーカイブを作る」という考えがほとんどなかったし。「日付重視で記事を書く？　なら、ブログを使った方がいいよ」という発想だったんで。
レンタルブログやWordPressやMovable Typeあたりは、「ReflectとDittoを連携させて…」みたいな事をあまり考えなくても、割と簡単に月別アーカイブを表示出来るわけだし。

それでも、MODxはぜひ使ってみてほしいわけです。理解してしまうとそれなりに簡単だし。つーか、そもそもMODxは「日付順にあまりこだわらず、自由な順番にコンテンツを並べ、自由な配置をする」のに向いたCMS、と思う。
後、サイト内であれこれ細かい数値処理をやる場合は、「どうこう言ってMODxが圧倒的に簡単」な場合が多いんで。