Dittoで使えるプレースホルダ全一覧
Dittoは記事(リソース)の一覧を出力するスニペットです。出力パターンを作る必要がありますが、パターン記述に用いるタグがプレースホルダです。ここで解説するDitto用のプレースホルダは、Dittoのスニペットコールを記述しているページ内のみで有効です。テンプレートに記述している場合は、そのテンプレートを設定しているページ全てで有効です。
<li><a href="[+url+]">[+title+]</li>
プレースホルダを使って上記のようにパターンを作ると、
<li><a href="各記事のURL">各記事のタイトル</li>
というパターンの繰り返しで記事の一覧を展開します。
いっけん無機質な文字列や数値であったりするプレースホルダを、MODXならではのデザインの自由度の高さでしっかりとスポットライトを当てて映えさせると、エキサイティングな見せ方ができるはずです。どの情報がユーザにとって重要であるかをしっかり見極めることが大切です。
パターンの指定方法
チャンクを使う方法
<li><a href="[+url+]">[+title+]</li>
チャンク作成画面を開き、パターンを記述して保存します。
<ul>
[[Ditto?tpl=チャンク名]]
</ul>
リソース編集画面またはテンプレート編集画面を開き、上記のように記述して呼び出します。
インラインで記述する方法
<ul>
[[Ditto?
&tpl=`@CODE:
<li><a href="各記事のURL">各記事のタイトル</li>
`
]]
</ul>
リソース編集画面またはテンプレート編集画面を開き、上記のように記述します。
※パターン内に「=」を含むため、MODX 1.0.5J-r3以前では上記のようにスニペットコール内にインラインで記述することはできません。最新MODXと互換動作を行なうパッチプラグインを準備中です。
パターン内で使うプレースホルダ
よく使うプレースホルダ
| [+id+] | ID - リンクを張るためにリンクタグと組み合わせて[~[+id+]~] として使うことが多いです。 |
|---|---|
| [+pagetitle+] | リソース名 |
| [+longtitle+] | 長いタイトル 入力を省略することもあるので[+longtitle:ifempty=`pagetitle`+] として補うとよいでしょう。 |
| [+description+] | 説明(description) |
| [+introtext+] | 要約(序説) 省略時に[+content+]から段落を選んで補う[+summary+]も便利です。 |
| [+content+] | 本文 |
| [+alias+] | エイリアス |
| [+menutitle+] | メニュータイトル |
便利なプレースホルダ
| [+title+] | リソース名。 [+pagetitle+]の別名です。 |
|---|---|
| [+author+] | 投稿者名。 [*createdby*]の値(メンバーID)を参照して名前を出力します。 |
| [+date+] | 投稿日。デフォルトでは[*createdon*]を参照しますが、&dateSourceパラメータで[*pub_date*]や[*editedon*]に変更できます。 日付の書式は&dateFormatパラメータで変更できます。 [+date+]プレースホルダを用いずに、PHx(Dittoの機能として組み込まれています)を用いる方法もあります。 ( 例：[+createdon:date=`%Y年%m月%d日`+] ) |
| [+url+] | URLを出力します。[~[+id+]~]との違いは、httpから始まるかどうかです。 使用例 <h3><a href="[+url+]">[+title+]</a></h3> |
| [+ditto_iteration+] | 記事ごとに連番を振ります(ページ単位)。通常は連番の出力に用いますが、PHxなどを併用すると、記事ごとに背景色を変更したりできます。 0番からカウントが始まるので、連番を表示するために利用したい場合は、 [+ditto_iteration:math=`?+1`+] というふうにPHx記述を組み合わせるとよいでしょう。 |
| [+ditto_sort+] | 記事ごとに連番を振ります。ページング処理を行なっている場合は次ページ以降も連番が引き継がれます。 |
| [~[+id+]~] | パスを出力します。[+url+]と違い、ルート基準の相対パスなので、フレンドリーURLで運用している場合は<head>要素内にbaseタグを指定する必要があります。 使用例 <h3><a href="[~[+id+]~]">[+title+]</a></h3> |
その他のプレースホルダ
- text ・・・文字列
- 0|1 ・・・ 0または1
- int ・・・ 整数値(0も含む)
- unixtime ・・・ UnixTIME形式
主なプレースホルダ
そのまま出力して意味のある値ではないケースがほとんどなので、PHxモディファイア記述を利用すると便利です。
例：[+type:is=`reference`:then=`(外部リンク)`:else=``+]
| [+content+](text) | 本文。Dittoは記事の一覧を出力するスニペットなので、要約を出力する[+description+]や[+introtext+]・[+summary+]のほうが実用的かもしれません。 |
|---|---|
| [+parent+](int) | 親リソース |
| [+isfolder+](0|1) | コンテナ属性を持つかどうか。サブリソースがある場合は必ずコンテナ属性になりますが、手動でコンテナ属性をつけることもできます。 |
| [+menuindex+](int) | メニューオーダーを出力します。 |
| [+hidemenu+](0|1) | 「メニューに表示」の反対。 |
| [+type+] (documentまたは reference) |
リソースタイプを表示します。「document(通常のリソース)」「reference(ウェブリンク)」どちらかの文字列を返します。 |
| [+contentType+](text) | コンテントタイプ 投稿画面内で設定したコンテントタイプを表示します。通常は「text/html」です。 |
| [+richtext+](0|1) | リッチテキストで編集 投稿画面内でリッチテキストエディタを使うかどうかの設定。通常はDittoで使うことはありません。 |
| [+template+](int) | 設定しているテンプレートのIDを出力します。 |
| [+searchable+](0|1) | 検索対象に含める このページが検索対象になっているかどうか。あくまでも設定値に過ぎないので、これを利用する検索機能(AjaxSearchなど)を別途に用意する必要があります。 |
| [+donthit+](0|1) | このページがトラッキング（アクセス解析）の対象になっているかどうか。[+searchable+]と同様、この設定値を利用する機能を別途に用意する必要があります。 |
| [+content_dispo+] (inline または attachment) |
リソースの内容をブラウザに対してどう出力するか。「inline」または「attachment」のいずれかを返します。通常はinlineです。attachmentに設定されている場合は、このリソースにアクセスするとダウンロードダイアログボックスが表示されます。 PHx記述を利用して、この値がattachmentである時に「ダウンロード」という文字列を出力するなどの用途が考えられます。 |
日時に関するプレースホルダ
UnixTIME形式の数値が格納されているため、PHxモディファイア記述を利用するとよいでしょう。
例：[+pubdate:date=`%Y年%m月%d日`+]
| [+pub_date+](unixtime) | 公開開始日時を出力します。投稿画面で指定しない場合は空白になることもあるのでご注意ください。 【ヒント】 [+pub_date:ifempty=`[+publishedon+]`:date=`%Y年%-m月%-d日`+] 上記のように記述すると、pub_dateが空の場合はpublishedonを出力します。 |
|---|---|
| [+unpub_date+](unixtime) | 公開終了日時を出力します。 |
| [+createdon+](unixtime) | 記事の作成日時 |
| [+editedon+](unixtime) | 直近の編集日時 |
| [+publishedon+](unixtime) | 実際に記事が公開された日時(pub_dateで公開日時を指定した場合は、公開日時になった後の最初のアクセスがあった時・または管理画面操作を行なった時に公開処理が行なわれ、この時の日時がセットされます) |
| [+deletedon+](unixtime) | 記事を削除した日時。通常はこのプレースホルダをDittoで用いることはありませんが、削除した記事の一覧を出力したい場合などには便利です。 |
投稿メンバーに関するプレースホルダ
メンバーIDが格納されているので、PHxモディファイア記述を利用するとよいでしょう。
例：[+createdby:userinfo=`fullname`+]
| [+createdby+](int) | 投稿者(記事を新規作成したメンバー)のメンバーID |
|---|---|
| [+editedby+](int) | 直近の編集者のメンバーID |
| [+deletedby+](int) | 記事を削除した編集者のメンバーID。通常はこのプレースホルダをDittoで用いることはありません。 |
ページの状態に関するプレースホルダ
0または1で値が管理されているので、PHxモディファイア記述を利用するとよいでしょう。
例：[+cacheable:is=`1`:then=`キャッシュ有効`:else=`キャッシュ無効`+]
| [+published+](0|1) | 公開されているかどうか |
|---|---|
| [+deleted+](0|1) | 記事が削除状態かどうか(ごみ箱を空にしていない状態で)。ここが1になっているということは記事が削除されているということなので、通常はこのプレースホルダをDittoで用いることはありません。 |
| [+cacheable+](0|1) | キャッシュ有効 このページがキャッシュ制御の対象になっているかどうか。 |
| [+privateweb+](0|1) | このページがウェブユーザとしての認証を必要としているかどうか |
| [+privatemgr+](0|1) | このページが管理画面のメンバーとしての認証を必要としているかどうか |
非推奨のプレースホルダ
| [+haskeywords+](0|1) | このページがキーワードを持っているかどうか。この設定は古いバージョンのMODXの基本仕様に基づくものなので、現在は利用をおすすめしません。この設定を用いる場合は、グローバル設定を変更してMETAタグ管理機能を有効にする必要があります。 |
|---|---|
| [+hasmetatag+](0|1) | このページが管理しているMETAタグがあるかどうか。[+haskeywords+]と同様、この設定の利用はおすすめしません。管理画面の機能を用いるより、自前でテンプレート変数を作って実装するほうがシンプルで扱いやすいです。 |
テンプレート変数
| [+テンプレート変数名+] | テンプレート変数の内容を出力します。 |
|---|
エクステンダの組み込みにより利用可能になるプレースホルダ
| [+summary+] | [*introtext*]が入力されている場合はその内容を出力します。入力されていない場合は[*content*]の内容から最初の段落及び句点(。)の区切り・適当な文字数などで切り取って出力します。 |
|---|---|
| [+link+] | 「Read more...」(続きを読む)リンクを出力します。 |
パターン外で使うプレースホルダ
ページング操作に関係するプレースホルダ
出力するリソース数が数十件・数百件以上ある場合は、１ページ内に出力しきれないことがあります。そのような時は、10件ごと・20件ごとなど適当にページを区切って出力すると便利です。これをページングまたはページネーションと呼びます。
以下のプレースホルダは、ページングを行なうためにページングナビゲーションを作るために用います。Dittoのパターン内ではなく、一覧を出力するリソースまたはテンプレート内に記述します。
| [+next+] | 「次へ」リンクを出力します。&paginateAlwaysShowLinksオプションをセットすると、次ページが存在しない場合はリンクを張らず「次へ」を文字列として出力します。 |
|---|---|
| [+previous+] | 「戻る」リンクを出力します。[+next+]と同様です。 |
| [+splitter+] | スプリッター（区切り文字または記号） 戻る | 次へ |
| [+pages+] | ページボタンのリスト。[1] [2] [3] [4] [5] ・・・ |
| [+totalPages+] | ページの総数 |
| [+start+] | そのページに表示されている最初のアイテムが、全体の中で何番目か。たとえば1ページあたり20件を出力する設定になっている場合、3ページを開くと[+start+]は「41」(20x2+1)になります。 |
| [+urlStart+] | URLの$_GET['start']パラメータの値。[+start+]の値と連動していますが、内部的なPHP処理で直接扱うため、0からカウントします。そのため[+start+]より１つ少ない数値になります。 |
| [+stop+] | そのページに表示されている最後のアイテムが、全体の中で何番目か。この値は最終ページで利用すると便利でしょう。 |
| [+currentPage+] | 現在、何ページ目か。たとえば３ページ目を開いている時は「3」が出力されます。 |
| [+perPage+] | ページあたり何件を出力するか。この値はDittoスニペットコールのオプション&displayで指定する値と同じです。 |
| [+total+] | ページあたりのアイテム件数 |
| [+ditto_pagination_set+] | このページでページングが有効になっているかどうかを0または1の数値で出力します。通常はこの値を参照することはありませんが、ページングの有効無効を設定でコントロールできるようにサイトを作っている場合には、この値が役に立つことがあります。 |
特殊なプレースホルダ
| [+item[x]+] | Dittoのパターン内ではなく、Dittoスニペットコールを書いたページ内、またはそれを呼び出すテンプレート内で使えます。[x]のxには整数が入ります。たとえば[+item[0]+]と記述すると、スニペットコール記述で最初に呼び出されるアイテムと同じ内容を、そこに出力できます。 item[0]という記述は配列のように見えますが、実際は[0]も含めて通常の文字列です。 ※使い方の実例をブログ記事にまとめました。 |
|---|
