DocListerで記事の一覧
DocListerをDittoの代わりに使ってみよう
フォーラムによると、「Dittoの代替として使えます。軽い動作・柔軟性の高さが特長です。」ということなので、使ってみます。おそらく解説がロシア語ということがハードルの高さなのかな？私はロシア語もPHPもMySQLも詳しくないので、説明に間違いがあるかもしれません。実力としてはhtmlがちょっと読めるくらいの程度です(わからなくてもどうにかなるのがMODXの良いところ)。
さて、こちらにDittoとの比較が掲載されています。なんかは良い感じらしいことを書いてるのでしょう。
DocListerのダウンロード
まずはDocListerのサイトにファイルとインストールの方法が書いてあります。ダウンロードはGitHubからもできます。
DocListerのインストール
ダウンロードしたファイルの中には、スニペットやプラグインなどたくさんのファイルがあります。
しかし今回はDocListerだけが使えたらよいのです。
展開したディレクトリにある「assets」ディレクトリに、「lib」ディレクトリと「snippets」ディレクトリがあります。
FTPソフトなどを使って、「snippets」の中にある「DocLister」と「lib」ディレクトリとをアップロードします。
| アップロードするディレクトリ | アップロード先 |
|---|---|
| assets/lib | assets |
| assets/snippets/DocLister | assets/snippets |
次にDocListerのスニペットを新規作成します。
「install/assets/snippets」の中にDocLister.tplがありますので、その中身を
管理画面から「エレメント」→「エレメント管理」→「スニペット」→「スニペット作成」にある、スニペットコードの中に貼り付けます。
return require MODX_BASE_PATH.'assets/snippets/DocLister/snippet.DocLister.php';
これでインストールは完了です。
DocListerのパラメータ
2016年5月13日追記：MODX Evolution1.1への採用に伴い英語のドキュメントができています。（https://rtfm.modx.com/extras/evo/doclister/）
スニペット全般の使い方として言えることですが、表示させたい箇所に[[DocLister]]か[!DocLister!]と書き、後は必要に応じてパラメータを設定します。
同様にパラメータもDocListerのサイトに書いています。Google先生に聞けばある程度わかります。パラメータの種類はおおよそDittoと似ていますが、それでも少しは違いがありますので、高い頻度で使いそうなものをメモっておきます。
親リソースを指定して記事一覧を出力する
[[DocLister?
&parents=`リソースID,リソースID`
&depth=`0`]]指定がない場合は現在のリソースIDです。「&depth=`数字`」で階層を指定できます。
リソースを指定して記事を出力する
[[DocLister?
&documents=`リソースID,リソースID`]]「&idType=`documents`」または「&idType=`parents`」を書くことで出力方法を変更できますが、documentsパラメータかparentsパラメータを書くこと自動的に変更されるので省略できます。
並び順を指定する
[[DocLister?
&parents=`リソースID`
&sortType=`other`
&orderBy=`c.id DESC`]]「&sortType」はデフォルト(指定しない場合)で「other」になっています。「none」を指定すると自動で並びます。「doclist」を指定するとスニペットに読み込まれた順で並ぶようです。自分で指定する場合は「other」が良いでしょう。
「&orderBy=`c.id DESC`」の他に「&sortBy=`id`&order=`DESC`」でも指定できます。orderByもsortByもSQLで指定する文字列です。
ランダムで表示する場合は「&orderBy=`RAND()`」にします。リソース変数(site_content)から使用する場合、プレフィックスとして「c.」をつけることが望ましいようです。カンマ(,)区切りで複数指定可能です。
データフォーマットの指定
[[DocLister?
&parents=`リソースID`
&dateSource=`pub_date`
&dateFormat=`%y年%m月%d日 %H:%M`
&tpl=`@CODE:<p>[+title+]([+date+])</p>`]]テンプレートを指定する
[[DocLister?
&parents=`リソースID`
&ownerTPL=`@CODE:<ul>[+dl.wrap+]</ul>`
&noneWrapOuter=`0`
&noneTPL=`@CODE:<p>記事はありません。</p>`
&tpl=`@CODE:<li class="[+dl.class+]">[+title+]</li>`
&tplFirst=`@CODE:<li class="[+dl.class+]">[+title+]</li>`
&tplLast=`@CODE:<li class="[+dl.class+]">[+title+]</li>`
&tplCurrent=`@CODE:<li class="[+dl.class+]">[+title+]</li>`]]もちろんチャンクで指定(&tpl=`chunk.name`)もできます。「&noneWrapOuter」を「0」に指定すると「&ownerTPL」で指定したテンプレートは出力されません([+dl.wrap+]のみになる？)。「&noneTPL」で記事がない場合の出力を指定できます。
コードに「[+dl.wrap+]」とありますが、これは例えば「&syskey=`text`」と指定することで「[+text.wrap+]」にすることができます。また「[+dl.class+]（first,current,last,even,oddのクラスを追加）」や「[+dl.active+](出力されているものが現在のページであれば1(true)そうでないなら0)」も同様に変わるので注意が必要です。
テンプレートパラメータの指定
チャンクで指定できますが、@Bindingsも使用できます。
| 項目 | 説明 |
|---|---|
| @FILE | assets/templates内のhtmlファイルを読み込む |
| @CHUNK | チャンクを読み込む |
| @TPL @CODE |
インラインで使用できる |
| @DOCUMENT @DOC |
リソースの内容から読み込む |
| @PLH @PLACEHOLDER |
プレースホルダーから読み込む |
| @CFG @CONFIG @OPTION |
グローバル設定から読み込む |
| その他 | extenderは工事中 |
参考：http://blog.agel-nash.ru/addon/doclister.html
プレースホルダー
お馴染みの[+title+]、[+url+]、[+date+]などが使えます。[+interarion+]は表示しているページのアイテムに連番(1から始まる)を振ります。
概要を使う
[[DocLister?
&documents=`リソースID`
&summary=`tags:0,len:300`
&tpl=`@CODE:<p>[+title+]<br />[+summary+]</p>`]]「summary」に特定のリソース変数を指定する場合は、「&introField=`任意のリソース変数`」を指定すると変わります。設定は「&summary=`アクション:設定,アクション2:設定`」というように書きます。
テンプレート変数を使う
[[DocLister?
&parents=`リソースID`
&tvList=`テンプレート変数1,テンプレート変数2,テンプレート変数3`
&tpl=`@CODE:<li><a href="[+tv.テンプレート変数1+]">[+title+][+tv.テンプレート変数2+]([+tv.テンプレート変数3+])</a></li>`
&ownerTPL=`@CODE:<ul>[+dl.wrap+]</ul>`]]「&tvList」に使用したいテンプレート変数をカンマ区切りで指定します。後は[+tv.テンプレート変数+]というように、テンプレート変数のプレフィックスとして「tv.」を付けます。
フィルターを使う
[[DocLister?
&parents=`リソースID`
&filters=`tv:テンプレート変数1:is:値`
&tvList=`テンプレート変数1,テンプレート変数2,テンプレート変数3`
&tpl=`@CODE:<li><a href="[+tv.テンプレート変数1+]">[+title+][+tv.テンプレート変数2+]([+tv.テンプレート変数3+])</a></li>`
&ownerTPL=`@CODE:<ul>[+dl.wrap+]</ul>`]]フィルターにはテンプレート変数を使います。複数指定する場合は、「OR(tv:テンプレート変数1:is:値;tv:テンプレート変数2:like:値)」や「AND(tv:テンプレート変数1:is:値;tv:テンプレート変数2:like:値)」と指定します。リソース変数を使う場合は、「content:pagetitle:is:値」など。
| 演算子 | 説明 |
| = is eq |
値と一致するもの 例1 content:c.id:is:3 例2 tv:テンプレート変数:is:MODX |
| != no isnot |
値と一致しないもの 例1 content:c.id:no:3 例2 tv:テンプレート変数:no:MODX |
| > gt |
値より大きいもの 例1 content:c.menuindex:gt:3 例2 tv:テンプレート変数:gt:3 |
| < lt |
値より小さいもの 例1 content:c.menuindex:lt:3 例2 tv:テンプレート変数:lt:3 |
| <= elt |
値以下のもの 例1 content:c.menuindex:elt:3 例2 tv:テンプレート変数:elt:3 |
| >= egt |
値以上のもの 例1 content:c.menuindex:egt:3 例2 tv:テンプレート変数:egt:3 |
| % like |
値を含むもの 例1 content:c.content:like:MODX 例2 tv:テンプレート変数:like:MODX |
| like-r | 値で始まるもの 例1 content:c.content:like-r:MO 例2 tv:テンプレート変数:like-r:MO |
| like-l | 値で終わるもの 例1 content:c.content:like-l:DX 例2 tv:テンプレート変数:like-l:DX |
| regexp | 値が正規表現で一致するもの 例1 content:c.pagetitle:regexp:MODX 例2 tv:テンプレート変数:regexp:MODX |
| against | 値がフルテキストインデックスに含まれるもの 例1 content:pagetitle,description,content:against:MODX 例2 tv:values:against:MODX |
| containsOne | いずれかの値を含むもの 例1 content:c.content:containsOne:MODX,CMS 例2 tv:テンプレート変数:containsOne:MODX,CMS |
| in | いずれかの値に一致するもの 例1 content:c.pagetitle:in:MODX,CMS 例2 tv:テンプレート変数:in:MODX,CMS |
| notin | いずれかの値に一致しないもの 例1 content:c.pagetitle:notin:MODX,CMS 例2 tv:テンプレート変数:notin:MODX,CMS |
againstはフルテキストインデックスに内包されているものを選択しなければならないので、modx_site_contentテーブルを検索する場合は「pagetitle,description,content」を一緒に指定しないとエラーになります。modx_site_tmplvar_contentvaluesテーブルを検索する場合は「values」のみです。他のものから検索しようとするとエラーになります。
WHERE句を使う
addWhereListを使用します。
[[DocLister?
&parents=`リソースID`
&addWhereList=`c.hidemenu=0 AND c.isfolder=0`]]SQLのWHEREで指定する文字列になるようです。
リソース変数で指定することで出力するものを制御できます。
&filtersと&addWhereListを組み合わしてみる
各エントリーに関連記事を表示します。
例：同一カテゴリーで現在の記事以外をランダムに表示（条件付きGETを有効にしている場合はランダム表示を更新しません）
[!DocLister?
&id=`related`
&parents=`親リソースID`
&filters=`tv:カテゴリー:is:[*カテゴリー*]`
&addWhereList=`c.id<>[*id*]`
&display=`5`
&orderBy=`RAND()`
&ownerTPL=`@CODE:<ul>[+dl.wrap+]</ul>`
&tpl=`@CODE:<li><a href="[+url+]">[+title+]</a></li>`
&noneWrapOuter=`0`
&noneTPL=`@CODE:<p>関連する記事はありません。</p>`!]「&filters」だけで制御するには、「AND(tv:カテゴリー:is:[*カテゴリー*];content:c.id:isnot:[*id*];)」にすると同様の結果になります。
ページネーション
[[DocLister?
&parents=`リソースID`
&id=`text`
&paginate=`pages`
&display=`5`
&tvList=`テンプレート変数1,テンプレート変数2,テンプレート変数3`
&tpl=`@CODE:<li><a href="[+tv.テンプレート変数1+]">[+title+][+tv.テンプレート変数2+]([+tv.テンプレート変数3+])</a></li>`
&ownerTPL=`@CODE:<ul>[+dl.wrap+]</ul>`
&pageAdjacents=`4`
&PrevNextAlwaysShow=`1`
&TplNextP=`@CODE:<a href="[+link+]">次へ</a>`
&TplNextI=`@CODE:<a href="[+link+]" class="disabled">次へ</a>`
&TplPrevP=`@CODE:<a href="[+link+]">前へ</a>`
&TplPrevI=`@CODE:<a href="[+link+]" class="disabled">前へ</a>`
&TplPage=`@CODE:<a href="[+link+]" class="page">[+num+]</a>`
&TplCurrentPage=`@CODE:<b class="current">[+num+]</b>`
&TplWrapPaginate=`@CODE:<div class="[+class+]">[+wrap+]</div>`
&PaginateClass=`class`]]
[+text.totalPages+][+text.isstop+][+text.isstart+][+text.pages+]ページネーションを表示するには、「&id」を任意の文字列で指定します。そして表示したい場所に[+指定したid.pages+]と書きます。テンプレートやクラスの指定もできます。その他のパラメータも「[+指定したid.totalPages+](総ページ数)」「[+指定したid.isstop+](現在のページが最後なら1そうでなければ0)」「[+指定したid.isstart+](現在のページが最初なら1そうでなければ0)」に変わるので注意してください。「TplNextI」と「TplPrevI」はページがない場合のテンプレートです。「PrevNextAlwaysShow」を「0」にすれば非表示になります。Dittoと違い、最初のページに戻るときにはURLの「?〜」がなくなります。ページ数が増えてきたら、「&pageAdjacents=`数字`」を指定することで、間の数字は「...」で省略されて表示されるようになります。
「&display=`数字`」を指定することで、1ページごとの表示件数の変更もできます。
デバッグ
[[DocLister?
&parents=`リソースID`
&debug=`1`]]デフォルトでは「0」になっています。デバッグのレベルは「1」か「2」で、「2」の方がより詳細が表示されます。
まとめ
MODX自体も日本語ドキュメントが少なかったり古かったりしますが、DocListerはこれで自分で使う分には困らない程度にめぼしい物をまとめられた気がします。ロシア語なのでとっつきにくいですが、やっていくうちになんとかなるでしょう。extenderなど他にもパラメータはありますので、これから使う人はDocListerのサイトを見てがんばってください。わかったことは適宜変更・追記していきます。
保留中のパラメータ
- api
- controller
- extender
- tree
- prepare
- contentPlaceholder
- lang
- locale
- JSONformat
- offset
- start
- total
- config
- customLang
- filter_delimiter
- showParent
- queryLimit
- tagsDate
- tabel
- idField
- parentField
- introField
- contentField
- pageLimit