また更新。
やることやって、これで落ち着きそうです。

各種リスト出力に特化したプラグインです。 blog（ブログリスト）, category（カテゴリーリスト）, archive（アーカイブリスト）, recentitem（最新アイテムリスト）, writeback（コメント・TBリスト） のサブプラグインを同梱。 サブプラグインを追加することで機能を拡張できます。 またスキン変数のパラメータで設定を統一的に制御できます。

Download: NP_List v0.4

Nucleus v3.31SP1 UTF-8、PHP5で確認。

v0.4での更新内容：

  • アイテム変数に対応。記事の中に任意のリストを配置できます。
  • フィルター処理の修正（従来は"!="等の記号処理が不適切だった）。
  • フィルター記号 "=~"、"!~" の追加（それぞれ"LIKE"、"NOT LIKE" 相当）。ワイルドカード "%" を利用した文字列比較ができます。
  • archive, recentitem, writeback サブプラグインでのカテゴリー付きリンク処理を改良。またrecentitem, writeback でフラグ "catlink" （カテゴリー付きリンク出力）を追加。
  • サブプラグインごとに初期パラメータを持てるようにした（_setDefaultParams()メソッドの追加）。
  • サブプラグインのサンプルコードを更新。

このプラグインの特徴

NP_ContentsList等のメニュー系プラグインとリスト出力プラグインを混ぜ合わせたようなものです。

  • サブプラグインでリストタイプを追加できます。
  • 各リストを統一的なパラメータ指定で制御できます。並び順、条件フィルター等。条件フィルターには現在の値を埋め込む "@" が使えるのでカテゴリーの絞込みなどをリストに自動的に反映させることができます。
  • すべての指定をスキン・テンプレート上に記述します。スキン・テンプレートの書き出し＆読み込みのみで全ての設定を保存・復元できます。NP_Containerによるカスタムテンプレートにも対応。
  • ブログリストからカテゴリーリストを呼び出せます1。blog - categoryによる2層メニューが作れます。
  • アイテム変数に対応。記事内にリストを配置できます。

インストール

ZIPを展開すると出てくる NP_List.php と listディレクトリ をNucleusのプラグインディレクトリへアップロードします。その後、管理画面のプラグインリストからインストールしてください。

スキンへの記述

このプラグインの設定は、すべてスキン・テンプレートに記述するように作ってあります。プラグインの管理画面はありません。一見めんどくさそうですが、その代わりにパラメータの記述がわかりやすくなるよう配慮してあります。

シンプルな指定例

<%List(type:blog, tpl:テンプレート名)%><!-- ブログリスト  -->
<%List(type:category, tpl:テンプレート名)%><!-- カテゴリーリスト -->
<%List(type:archive, tpl:テンプレート名)%><!-- 月別アーカイブリスト -->
<%List(type:recentitem)%><!-- 最新アイテムリスト -->
<%List(type:writeback)%><!-- コメント・トラックバックリスト -->

デフォルトでは「定義リスト」形式によるリスト出力を想定してます。なので、実際には以下のように前後に記述します。
※出力形式は変更できます（後述）

<dl>
<dt>リストのタイトル</dt>
<%List(type:blog, tpl:テンプレート名)%><!-- <dd>が出力される -->
</dl>

高度な指定例

いろいろなパラメータを指定できます。リストの並び順、条件フィルター、オプションフラグ等。パラメータの順番は自由です。

<%List(type:blog, tpl:テンプレート名, order:blogdesc ASC, corder:catdesc ASC, flag:stripe)%>
<%List(type:category, tpl:テンプレート名, filter:arcdate=@, order:catdesc ASC, flag:stripe hidenoamount)%>
<%List(type:archive, tpl:テンプレート名, filter:blogid=@ catid=@, flag:stripe)%>
<%List(type:recentitem, filter:catid=1|2|3, flag:stripe catlink)%>
<%List(type:writeback, filter:blogid!=4|5)%>

スキン変数の主要パラメータの説明

  • type - リストタイプを指定。
    • blog - ブログリスト
    • category - カテゴリーリスト
    • archive- 月別アーカイブリスト
    • recentitem - 最新アイテムリスト
    • writeback - コメント・トラバリスト
    • （さらに拡張可能）
  • tpl - テンプレートを使うリストタイプの場合、テンプレート名を指定。
  • order - ソート順を指定。指定方法は "対象カラム名 (ASC|DESC)"。
  • filter - フィルターを指定。半角スペースをはさんで複数指定可。
    • blogid - ブログID
    • catid - カテゴリーID
    • arcdate - アーカイブ日付（yyyy-mm）
    • （・・・さらに拡張可能・・・）
      各項目には、 "=", "!=", ">", "<" などの記号をはさんで右側に、単数値（"1"など）または複数値（"1|2|3"など）を指定します。数値には現在の値をあらわす記号 "@" を指定することができます。
      "=~", "!~" などの"LIKE" "NOT LIKE"相当の記号とワイルドカードを組み合わせれば "columnname=~%キーワード%" などのフィルター処理が可能です。

その他のパラメータの説明

  • tplprefix - NP_Containerによるカスタムテンプレートを使うリストタイプで、複数のカスタムパーツセットを使い分けるときにプレフィックスを指定。
  • amount - 出力数を指定。デフォルトは"5"。
  • len - リスト項目の文字数を指定。recentitem, writeback で使用。デフォルトは"25"。
  • trimmarker - lenで指定した文字数を超えた場合の省略マーカーを指定。デフォルトは".."。
  • yorder, morder - archiveタイプの年月のソート順を個別に指定。指定方法は "ASC"または"DESC"。
  • flag - オプションフラグを指定。半角スペースをはさんで複数指定可。サブプラグイン毎に固有に用意されています。
    • stripe - <%class%>（後述）に１つ置きに"stripe"を出力。これを利用してスタイルシートでリスト行を色分けできます。
    • hidenoamount - amountが0の項目を出力しない（categoryタイプ）。
    • nolimit - amount指定を無視して全項目を出力する（archiveタイプ）。
    • shownolink - リンクが無いリストも出力する（archiveタイプ）。
    • catlink - リンク出力を常にカテゴリー付きにする（recentitem, writebackタイプ）。
    • （・・・さらに拡張可能・・・）

テンプレートへの記述

blog, category, archive タイプは、テンプレートを指定してリストを整形します。テンプレートには、通常のテンプレート変数のほかに拡張変数として <%amount%>、<%class%>、<%catlist%>が使えます。

まずは出発点のスキン記述を先に出します。

スキンの記述例

ブログリスト、カテゴリーリスト、月別アーカイブの例です。

<dl class="menu">
<dt>メニューリスト（ブログ-カテゴリーの2層リスト）</dt>
<%List(type:blog, tpl:テンプレート名)%>
</dl>

<dl class="menu">
<dt>メニューリスト（カテゴリー）</dt>
<%List(type:category, tpl:テンプレート名)%>
</dl>

<dl class="monthly">
<dt>月別アーカイブ</dt>
<%List(type:archive, tpl:テンプレート名)%>
</dl>

テンプレートパーツ「ブログ一覧の本体」の例

上記スキンに対応した、ブログリストのテンプレートパーツの記述例です。ここでは最後に<%catlist%>を記述することで、入れ子でカテゴリーリストを呼び出して2層リストにしています。シンプルなブログリストのみで良い場合は、最後の行を省いてください。

<dt<%class%>>
<a href="<%bloglink%>" title="<%blogdesc%>"><%blogname%></a>
</dt>
<%catlist%>

テンプレートパーツ「カテゴリー一覧の本体」の例

カテゴリーリストの記述例です。<%amount%>でリスト毎にアイテム数を表示するようにしています。

<dd<%class%>>
<a href="<%catlink%>" title="<%catdesc%> <%archivedate%>"><%catname%></a> [<%amount%>]
</dd>

テンプレートパーツ「アーカイブ一覧の本体」の例

アーカイブ一覧の本体では strftime 形式（%Y, %mなど）が使えます。

<dd<%class%>>
<a href="<%archivelink%>">%Y年%m月<span class="amount">[<%amount%>]</span></a>
</dd>

アーカイブ一覧のヘッダーでは strftime 形式は使えませんが、代わりに<%year%>が使えるようになっています。

拡張テンプレート変数の説明

  • <%amount%> - 項目内のアイテム数
  • <%class%> - スタイル装飾用のクラス出力（項目が特定条件に合致した場合に"current"クラスが指定される等）。たとえばカテゴリーAを選択しているときにカテゴリーリストの該当項目を目立たせるなどが可能になります。
  • <%catlist%> - カテゴリーリストの呼び出し

ブログリストからカテゴリーリストを呼び出す

上で書かれた例の繰り返しになりますが、blogタイプの「ブログ一覧の本体」テンプレートに<%catlist%>が記述されていると、入れ子でcategoryタイプが呼び出されます。

※ blogタイプからcategoryタイプを呼び出すときに、カテゴリー側の order, filter パラメータを設定したい場合は、それぞれ"corder", "cfilter"と指定してください。

<%List(type:blog, tpl:テンプレート名, order:blogdesc ASC, corder:catdesc ASC, filter:blogid!=1, cfilter:catid!=10)%>

NP_Containerによるカスタムテンプレート

recentitem, writeback タイプは各々デフォルトの出力テンプレートを内部に持っています（Nucleusのテンプレートでの整形はできません）。これを整形する場合は、listディレクトリ内に収められている各サブプラグインファイルを直接書き換える2か、NP_Containerを使ってスキンにテンプレートパーツを書き込んで指定します。後者の方法だと、表示に関するカスタマイズ情報をスキンにすべて集約できます。

writebackタイプ＋カスタムテンプレート指定の例

以下の例では、リストヘッダーのパーツをNP_Containerで指定、書き換えています。パーツ名はリストタイプ_パーツ名と指定します。詳細は各リストタイプのファイルに記述された内部のテンプレートを確認してください。

<%Container(begin,List)%>
<!--PART name="WRITEBACK_LISTHEADER" --><dt<%class%>><a href="<%itemlink%>"><%itemtitle%></a><!--/PART-->
<%Container(end)%>

<dl class="writeback">
<dt>最近の反響</dt>
<%List(type:writeback)%>
</dl>

その他いろいろ

blog/categoryタイプの並び順や非表示項目の設定

ブログリストやカテゴリーリストを表示するときに、並び順を制御したい場合は、（原始的な方法ですが）管理画面でブログやカテゴリーの「説明」項目の頭に"01:","02:"と数字を振っておくと、"order:blogdesc ASC", "order:catdesc ASC" などの指定で並び順を制御できます。

同様に非表示にしたい項目がある場合は（フィルターで除外指定する以外にも）ブログやカテゴリーの「説明」項目の頭に"[!]"と振ることで非表示にすることもできます。

フィルター指定について

フィルターに"arcdate"を利用することで、月別アーカイブ閲覧時のリスト出力を絞り込むことができます（ただし日別アーカイブには対応していません）。

"blogid", "catid"とあわせて、カレント（"@"）指定することで閲覧条件に合わせた柔軟なリスト出力ができます。複数値の中にカレント指定を混ぜたいときは、"blogid=3|4|@" のように最後に @ を置きます。

リストタイプによっては使い勝手を考慮して、filter指定が無い場合に blogid が自動的に補完されるものがあります。
blogidが補完されないリストタイプは、デフォルトでは複数ブログをまたいだリストになります。ブログ内の内容に絞りたいときは明示的に "blogid=@" 等、フィルタリングしてください。

フィルターの柔軟性は利点ですが、DBからのデータ取得コストが上がることにもなりますのでご注意ください。重いなと思ったら、条件をシンプルにするか、キャッシュ系プラグインの導入を検討してください。

プラグインの拡張

以下はプラグインの中身の話です。
プラグインを改造・拡張しやすいように、サブプラグインを別クラスで用意してそれぞれに処理を委譲しています（listディレクトリ内の NP_ListOf～ が各処理を担います）。サブプラグインからは $this->caller で呼び出し元（NP_List）にアクセスできます。同梱のサンプルコードに日本語コメントつきの解説があるので参考にしてください。

また、Nucleus標準のテンプレートを使うものなら NP_ListOfBlog が、NP_Containerによるカスタムテンプレートを使うものなら NP_ListOfRecentItem が参考になるとおもいます。

  1. 実際には片方のサブプラグインからもう一方のサブプラグインを呼んでるだけです。 ↩

  2. サブプラグイン内の_getDefaultTemplate()に記述があります。 ↩