Source of PukiWiki/1.4/マニュアル/プラグイン/独自に追加したもの/lsx

**ページをリストアップするプラグイン ls.inc.php の拡張[#lf048c18]
#contentsx

*説明 [#o45abdfa]

ページをリストアップするプラグイン ls.inc.php の拡張です。ls2.inc.php の拡張でもありそれの拡張であった旧 ls2_1.inc.php の拡張でもあります。

**標準プラグイン ls2 との違い [#k9cb86b6]
-相対パス的表示。
-階層的リスト表示。
-階層指定。
-表示件数指定
-pukiwiki.ini.php で設定する $non_list の利用。
-正規表現によるページのフィルタ
-正規表現による除外ページ指定
-更新日時表示
-New 表示
-更新日時によるソート
-link オプション消去
-複数ページ include

**旧 ls2_1.inc.phpからの変更点 [#m17ed6bb]

-#ls2_1(パターン,オプション) -> #lsx(prefix=パターン,オプション)
--#ls2_1(,オプション) -> #lsx(オプション)
--相対指定が可能
-relative -> linkstr=relative (デフォルト)
-デフォルトで hierarchy 
--存在していない上階層のページを補完
-datesort -> sort=date
-depth=2-5 -> depth=2:5
--depth=-1:-5 (最後から、最後から５番目まで) が可能に
--depth=-1+5 なども可能
--depth=(1,3,5:9) のように複数指定も可能
-number -> num
--number=10 (10個) ではなく num=1:10 (depth と同じ書式)
-title 系オプション -> contents=(contentsx のオプション)
--プラグイン contentsx を呼ぶ
-include (#include しているページ名もリスト) -> include=(include のオプション) (#include する)
--ls2_1 の include は contents=(include,depth=0) で見た目は同じになるかもしれない（見出しも探すので処理は重い）
--実質消去され、各ページを include するオプションができたと思ってもらいたい
-compact 消去
--hierarchy が上階層のページを補完するようになったので用なし。
-display 消去
--inline 却下
---これ１つのために inline_before, after 等のオプションとインライン型プラグインサポートと、もう１つ表示エンジンを持たなければならない
-link 消去
--これのためにアクション型プラグインと、もう１つ小さいが表示エンジンを持たなければならないし、そもそも使わない
-アクション型プラグイン消去
-インライン型プラグイン消去
-filter, except
--ページ名全体ではなく、prefix を除いたページ名で評価
-tree=leaf|dir

変更なし

-non_list
-reverse
-date
-new

**競合相手 [#b483b6ec]
-[[org:自作プラグイン/lls.inc.php]] - 横並びもできる階層型ページ一覧表示プラグイン
--横並びは却下しました。横並びにしたい場合は CSS を頑張って編集してください。
-[[org:自作プラグイン/treepagelist.inc.php]] - エクスプローラのようなツリーを実現します。
--javascript (消失)
-[[org:自作プラグイン/ls3.inc.php]] - お手軽な階層一覧表示
--ページ名による階層表示ではなく、ページの先頭にリンクをおき、リンクされたページを子ページと判断するらしい。
-[[org:自作プラグイン/listing.inc.php]] - 多機能ページ一覧表示
--ページ名の一覧そのものよりも付加情報に着目しているように見受けられる。
-[[org:自作プラグイン/pagetree.inc.php]] - JavaScript を使わないツリーメニュー
--MenuBar での設置目的。このサイトでも使用している。
-[[dev:BugTrack/745#q2e37ce3]] - 他
*書式 [#jcb5f796]
 #lsx([オプション])

オプション名=bool なオプションは共通して、 オプション名, オプション名=true, オプション名=on でそのオプションが有効になり、オプション名=false, オプション名=off で無効になります。

-prefix=文字列
--リストするページ名の接頭辞。
省略時はカレントページ+"/"が指定されたことになる。
また / を指定した場合はすべてのページにマッチする。
相対指定(例えば Plugin ページにおける ./lsx.inc.php/ = Plugin/lsx.inc.php/)も可能。 

-num=数字
--表示件数指定。正数は前からＮ件目、負数は後ろからＮ件目の意味。~
num=1:10 で先頭１件目から１０件目までの意味。num=-10:-1 で後ろ１０件目から後ろ１件目までの意味。num=2: で先頭２件目から最後までの意味。~
//((num=:10 と書くこともできる。num=10:1 も同義。)) ((num=-10: と同義。num=-1:-10 とも書いても同じ。))~
num=5+2 で先頭５件目から、そこから２件先まで(5,6,7)の意味。~
//((num=5-2 で先頭５件目から、そこから2件前まで(3,4,5)の意味。))((さらに num=(1,3,5+2) のような表記も可能。))

-depth=数字
--下位階層指定。数字の指定は num と同じ書式。

-hierarchy=bool
--階層的リスト表示。デフォルトで有効。

-tree=leaf|dir
--末端ページ(leaf)、またはその逆(dir)のようなものを表示する。デフォルトは単純に無効。tree=dir は DOS コマンドの tree のようなニュアンス。~
備考:ようなものなので、ページ名を意識して付けていない場合効果は薄いでしょう。

-sort=name|date|reading
--ソートの方法。name はページ名によるソート。date は更新日付(上が最新)によるソート。デフォルトは name。reading は「読み」によるソート。~
備考:sort=date の場合、hierarchy は強制的に off になります。~
備考:「読み」の設定は[[:config/PageReading]] で行います。kakasi または chasen を用いた漢字の読みカナ自動設定は [[dev:PukiWiki/1.4/マニュアル/一覧表示の五十音順分類]] 参照。

-reverse=bool
--逆順にソートする

-non_list=bool
--pukiwiki.ini.php で定義される $non_list によるリスト排除。デフォルトで有効。

-except=正規表現
--リストしないページを正規表現にて指定。prefixを取り除いたページ名で判定。~
ヒント： マッチングには mbstring が利用可能な場合 [[mb_ereg>http://us2.php.net/mb_ereg]] をそうでない場合 [[ereg>http://us2.php.net/ereg]] を使用します。
except=Test|sample → Test または sample を含むページを除く。

-filter=正規表現
--ページパターンをさらに正規表現で限定する。prefixを取り除いたページ名で判定。
prefix=/ (全ての意味) にしてこちらだけを使うのもあり。~
ヒント： マッチングには mbstring が利用可能な場合 [[mb_ereg>http://us2.php.net/mb_ereg]] をそうでない場合 [[ereg>http://us2.php.net/ereg]] を使用します。

-date=bool
--更新日付をページ名の横に表示。

-new=bool
--更新日付に対して&color(#ff0000){New!};も表示。~
備考:設定を再利用するため new プラグインを使用しています。

-contents=(オプション)
--ページ内の見出しもリストする。~
備考:内部で contentsx プラグインを使用しているので、詳しいオプションは [[../contentsx]] を参照してください。オプションを複数指定する場合は contents=(num=1,depth=1) のようにできます。contents=(num=1,depth=(1,2)) のように入れ子もできます((pukiwiki プラグインは csv チックな入力 "contents=num=1,depth=1" をサポートしますが、"contents="num=1,2",depth=1" のように入れ子にできなかったので () サポートをわざわざ作った。))。

-include=(オプション)
--ページを include する~
備考：この場合ページリストは中止され、include だけされます。~
備考：内部で includex プラグインを使用しています。詳しいオプションは [[../includex]] を参照してください。オプションを複数指定する場合は include=(num=1:10,title=off) のようにできます

-linkstr=relative|absolute|basename|title|headline
--リンク文字列を制御できます。~
relative で相対パス的文字列表示（デフォルト）。~
absolute で絶対パス的文字列表示（ls2の動作）。~
basename でページ階層化機能でのベース名部分、例：Note/Plugin/lsx.inc.php -> lsx.inc.php。~
title で各ページの TITLE: 行で指定された文字列。~
headline で各ページの第一見出し。~
備考：title と headline は [[../contentsx]] を使用します。インストールしておいてください。TITLE: とは PukiWiki Plus! において HTML のタイトル<title></title> を設定する書式です。

-link=page|anchor|off
--リンク形式。link=page は通常通りページへのリンク。link=anchor は #lsx(include) 用。取り込んだページタイトルへのアンカー。link=off はリンクしない。

''ベータ機能''

-tag=文字列
-- /tag.inc.php で付けたタグを指定。tag=タグ１^タグ２ とすることで、共通ページを（積集合 ∩ のイメージ）、tag=タグ１-タグ２ とすることで差ページ(差集合のイメージ)をリスト~
備考：hierarchy, prefix は強制的に off になります。ベータ機能です。たぶん将来的には別のプラグインに移送されます。

''アルファ機能''

-newpage=on|except~
--on で新規作成ページのみを、except で新規作成ページ以外をリスト。デフォルトでは単純に無効。~
備考：backup ファイルが作成されているかどうかで新規かどうかを判断しています。

-next
--num オプションで件数を制限した場合に、次の５件、前の５件を表示するためのリンクを表示する
**動作例 [#ac62520e]

以下のページ群があったとする。
-test
-test/a
-test/a/aa
-test/a/aa/aaa
-test/a/bb/bbb
-test/c/cc/ccc

test というページで記述したものとする。[] はリンクの意。
----
 #lsx
-[a]
--[aa]
---[aaa]
--bb
---[bbb]
-c
--cc
---[ccc]
----
 #lsx(prefix=test/)
-[a]
--[aa]
---[aaa]
--bb
---[bbb]
-c
--cc
---[ccc]
----
 #lsx(hierarchy=off)
-[a]
-[a/aa]
-[a/aa/aaa]
-[a/bb/bbb]
-[c/cc/ccc]
----
 #lsx(tree=leaf,hierarchy=off)
-[a/aa/aaa]
-[a/bb/bbb]
-[c/cc/ccc]
----
 #lsx(tree=dir)
-[a]
--[aa]
--bb
-c
--cc
----
 #lsx(depth=1)
-[a]
----
 #lsx(depth=1:2)
-[a]
--[aa]
----
 #lsx(depth=2+1)
-a (←注目)
--[aa]
---[aaa]
--bb
---[bbb]
-c
--cc
---[ccc]
----
 #lsx(num=1:2)
-[a]
--[aa]
----
 #lsx(num=-1:-2)
-a
--bb
---[bbb]
-c
--cc
---[ccc]
----
 #lsx(num=(1:2,4))
-[a]
--[aa]
--bb
---[bbb]
----
 #lsx(except=cc|aaa$)
-[a]
--[aa]
--bb
---[bbb]
----
 #lsx(date)
-[a] 2004-10-10 (日) 23:03:05 
--[aa] 2004-11-30 (金) 12:11:43 
---[aaa] 2004-03-03 (月) 16:04:05 
--bb
---[bbb] 2004-12-26 (水) 23:55:55 
-c
--cc
---[ccc] 2004-10-11 (月) 01:02:04 
----
 #lsx(sort=date,date,new)
-[a/bb/bbb] 2004-12-26 (水) 23:55:55 &color(#ff0000){New}; 
-[a/aa] 2004-11-30 (金) 12:11:43 
-[c/cc/ccc] 2004-10-11 (月) 01:02:04 
-[a] 2004-10-10 (日) 23:03:05 
-[a/aa/aaa] 2004-03-03 (月) 16:04:05 
----
 #lsx(sort=date,new)
-[a/bb/bbb] &color(#ff0000){New}; 
-[a/aa] 
-[c/cc/ccc]
-[a] 
-[a/aa/aaa]  
----
 #lsx(depth=1:2,contents=(num=1))
-[a]
--見出し
--[aa]
---見出し
----
 #lsx(num=1:2,include)

 #includex(a)
 #includex(a/aa)

の結果が出力される。

*FAQ [#i7b02f35]

** #ls または #ls2 を一度に置き換えたい [#w5f71eab]

プラグインの置き換え用プラグインとして replaceplugin.inc.php を作成してありますので利用してみてください。

** ひょっとして recent プラグイン変わりに使える？ [#hfc6304f]

 **recent(10)
 #lsx(prefix=/,sort=date,num=1:10)

のように使用すれば同じような動作にはなります。しかし recent プラグインはキャッシュ機構を持っていて動作が高速なのと特別な表示インターフェースを持っているので recent プラグインを使用することをおすめします。


** MenuBar に設置しても良い？ [#sb71803d]

ls 系プラグイン全般は実行毎に毎回全てのページ名を処理し直します。
ページが多い場合中々処理が重くなるので MenuBar に設置することはお奨めしません。

それでも MenuBar に設置したい場合は止めはしませんが、私ならば ecache.inc.php プラグインを使用して少しでも PukiWiki の軽量化を狙います。

 #ecache(page=MenuBar){{
 #lsx(prefix=/,depth=1,tree=dir)
 }}

といいつつ、この Wiki では同じく ls 系の [[revulo:pagetree.inc.php>http://www.revulo.com/PukiWiki/Plugin/PageTree.html]] を MenuBar に設置していたりします。ページ数が 100 もないので大丈夫でしょう。
** popular プラグインでも同じような機能を使いたい [#l76d9e19]

暫定版ですが、lsx を使用した popular プラグイン拡張 popularx を作ってあります。
もちろん lsx 必須です。

書式
 #popularx(total|today|yesterday|recent[,lsx options])
-prefix=/ デフォルト
-hierarchy=off 固定
-num=1:10 デフォルト
-sort 使用不可 (popular 数でソート)

以下のファイルを右クリックから保存し、plugin ディレクトリにおいてください。常に開発版です。


-[[svn:plugin/popularx.inc.php]]
-[[svn:plugin/lsx.inc.php]]
-[[svn:plugin/contentsx.inc.php]]
-[[svn:plugin/includex.inc.php]]

&l(en){What's new};&l(ja){更新履歴};
[[viewcvs>viewcvs:plugin/popularx.inc.php]]

TIPS: 気にしたことがなかったかもしれませんが、popular 系プラグインも ls 系プラグインと同等の処理時間がかかります。MenuBar に total,today,yesterday と３つ設置すれば３倍かかるかもしれません。[[上で記述>#sb71803d]] したように ecache.inc.php プラグインを使用して一時間毎更新にしたりすると良いのかもしれません。

** sort の順序を指定したい [#c596f56a]

「読み」を設定し、sort=reading を指定すると、sort の順序を指定したような動作にすることが可能です。

「読み」は [[:config/PageReading]] ページで設定します。例えば
 -[[Plugin/lsx.inc.php]] Plugin/00
 -[[Plugin/includex.inc.php]] Plugin/01

のように設定すれば、通常の sort=name ではページ名の文字列順にソートするため、
-includex.inc.php
-lsx.inc.php

の順番になるのですが、sort=reading とすると「読み」の文字列順にソートするため、Plugin/00 と Plugin/01 を比べて
-lsx.inc.php
-includex.inc.php

となります。

「読み」の本来の用途は、漢字の読みを設定することによる５０音順での sort のサポートです。
kakasi または chasen を用いた漢字の読みカナ自動設定は [[dev:PukiWiki/1.4/マニュアル/一覧表示の五十音順分類]] を参照してください。
*技術的詳細 [#b04f20ed]

**リストHTMLについて [#s373907c]

PukiWiki の標準ではリストで無茶なレベル指定(例: 2→1→3→2)がされた場合、最初のレベル2 <li> で
 <ul><li style="padding-left:2*16px;margin-left:2*16px">
のような（意味の）HTML が出力されます。その際の 16px というのは default.ini.php で設定されているため、css の編集だけで見た目を変えることができなくなります。
この一見不思議な仕様により、BugTrack や質問箱、2ch のスレや個人のウェブページでたびたび「なぜ default.ini.php で設定されているのか」という同じ質問を見かけます。
しかし、それにも理由があります。その理由は [[dev:BugTrack2/126]] [[dev:開発日記/2003-03-29]] あたりが参考になります。

それが正しいのもわかるのですが、あまりにも不便なため、lsx ではそこは妥協して
 <ul><li style="list-type:none"><ul><li>
のような HTML を出力するようにしています。これも XHTML valid です。PukiWiki 本体のほうでもそこは妥協してほしいと思っています。
**関連 [#q06a7e2d]
-[[dev:PukiWiki/1.4/ちょっと便利に/更新日順に表示できるls2プラグイン]] -- 更新日順に表示できるls2 プラグイン（実現）
-[[org:欲しいプラグイン/172]] -- ls拡張 階層下の特定パターンを列挙（実現）
-[[org:欲しいプラグイン/176]] -- 更新状況で並び替え（ソート）（実現）
-[[org:続・質問箱/318]] -- 見出しオプションで見出し1だけ（実現）
-[[org:続・質問箱/462]] -- ls2使用時の下位層ページへのリンク表示「○○○/×××」の「○○○/」の部分を消すには？（実現）
-[[org:続・質問箱/471]] - -見出しオプションで見出し一覧の表示件数を制限するには？（実現）
-[[org:続・質問箱/603]] -- 複数ページを代表して更新履歴を表示させる（実現）
-[[dev:morikawa#b0b5084e]] -- ひとつ下の階層の一覧だけ表示する ls3 プラグイン（実現）
-[[org:質問箱/63]] -- 階層図出来ませんかね？（実現）
-[[org:PukiWiki/mbstring無しのPHPでの動作]] - レンタルサーバなどで mbstring がサポートされていない場合は jcode.phpで代用するという手もあります。

**アイデア [#ia9f2903]
-ページ新規作成、削除時に recent.dat のようにキャッシュを作れれば楽なのだが、無理。デフォルトプラグインがうらやましい。
--毎回実行時に recent.dat の先頭をチェックして、キャッシュファイルより新しいのがあれば更新。
--non_list 取得できないなぁ。
--全体で１つ（そこ%8