FAQ -Wicurio-contentsxプラグイン
概要
ページの目次を作成する #contents のプラグイン化、拡張
本体組み込み #contents との違い
- 設置行以降の見出しのみリストする機能
- MenuBar に設置しても有効
- 見出しレベル指定機能
- 表示件数指定機能
- 正規表現による見出しのフィルタ機能
- 正規表現による見出しの除外フィルタ機能
- キャッシュ機能
- リンク形態指定機能(リンクしないなど)
- 固定アンカ必須
使い方
固定アンカ必須です。pukiwiki.ini.php で $fixed_heading_anchor = 1; と設定します。 PukiWiki Plus! の場合デフォルトで有効です。
固定アンカは編集保存する際に自動作成されます。 今まで設定していなかった場合、全てのページを編集保存しなおす必要があります。
書式
#contentsx(オプション)
option=bool なオプションは共通して、 option, option=true, option=on でそのオプションが有効になり、option=false, option=off で無効になります。
page=ページ名
見出しリストを行うページを指定できる。デフォルトはカレントページ。
fromhere=bool
#contentsx がある行以降の見出しのみをリストする。デフォルトで有効。
備考：page オプションで別ページを指定した場合は強制的に off になります。
hierarchy=bool
階層的表示。デフォルトで有効。
compact=bool
リストのレベルを詰める。デフォルトで有効。気になる場合は使用例参照のこと。
num=数字
表示件数指定。正数は前からＮ件目、負数は後ろからＮ件目の意味。
num=1:10 で先頭１件目から１０件目までの意味。num=-10:-1 で後ろ１０件目から後ろ１件目までの意味。num=2: で先頭２件目から最後までの意味。 num=5+2 で先頭５件目から、そこから２件先まで(5,6,7)の意味。
depth=数字
見出しレベル限定。数字の指定は num と同じ書式。
includeページタイトルはレベル0になる。compact=on,off に関わらず絶対値指定。
except=正規表現
リストしない見出しを正規表現にて指定。
ヒント： ereg で判定を行います。 except=Test|sample → Test または sample を含む見出しを除く。
filter=正規表現
リストする見出しを正規表現で限定する。
ヒント： ereg で判定を行います。
include=bool
#include プラグインで取り込んでいるページとその見出しも扱う。 デフォルトで有効。
cache=on | off
キャッシュの利用。デフォルトで有効。
link=on | off | anchor | page
リンク形態指定。デフォルトは on。
on - 柔軟に、現在ページへは link=anchor、page オプションで別ページが指定されていた場合 link=page。 anchor - 強制的にアンカーのみ使用。 page - 強制的にページ名も含めたリンク。 off - リンクしない。
ヒント： link=anchor で include したページに対してもページ内アンカーによるリンクを貼れます。include にはもともと対応していますが、類似のものにも対応できると思います。link=page はついでです。
動作例(仕様)
次のような「とあるページ」があったとします。
**AA #contentsx *B ***BBB **BC #include(別のページ) *D
「別のページ」の内容は次のとおりだったとします。
*1 #contentsx **11
「とあるページ」の #contetnsx が変更されると思ってください。
まず参考に #contents
#contents
出力）
AA
B
BBB
BC
D
#contentsx //デフォルト動作 == #contentsx(include,fromhere,compact,hierarchy)
出力）
B
BBB
BC
別のページ
1
11
D
#contentsx(include=off,fromhere=off,compact=off,hierarchy=off) 出力） AA B BBB BC D
#contentsx(include=off,fromhere=off,compact=off,hierarchy) // 以下 hierarchy 略 出力） AA
B
BBB
BC
D
#contentsx(include=off,fromhere=off,compact) // compact
出力）
AA (<-注目)
B
BBB (<-注目)
BC
D
完全に #contents と同じものはないが、compact としてはこの挙動が正解だと思っている(#contents の場合は先頭要素だけが compact されている)。
#contentsx(include=off,fromhere,compact=off) // fromhere
出力）
B
BBB
BC
D
#contentsx(include,fromhere=off,compact=off) // include 出力） AA
B
BBB (表現できない。もう1段下がる)
BC
別のページ
1
11
D
include がある場合、全体的に１段階下がる。
#contentsx(depth=1:2,compact=false)
出力）
B
BC
1
11
D
include が depth=0
#contentsx(depth=1:2) // compact
出力）
B
BC
1
11
D
#contentsx(depth=1:2,filter=B)
出力）
B
BC
#contentsx(depth=1:2,except=B)
出力）
1
11
D
#contentsx(depth=1:2,except=B,num=1:2)
出力）
1
11
#contentsx(page=別のページ)
出力）
1
11
FAQ
MenuBar に設置する場合？
MenuBar に設置する際は
#contentsx(fromhere=off)
のように記述しておきます*1。
CSSデザイン
#contentsx は
<table border="0" class="toc"><tbody>
<tr><td class="toctitle">
<span>Table of Contents</span>
</td></tr>
<tr><td class="toclist">
<ul class="contentsx">
<li> ... </li>
<li> ... </li>
</ul>
</td></tr>
</tbody></table>
のようなタグを出力します(微妙にMediaWikiの真似)。クラス toc、toctitle、toclist を利用します。
このサイトでは以下のようにしています。 サイトのデザインは各々で違うと思いますので、参考までに。
Table of Contents の文字を消したい場合は
div#body .toc .toctitle {
display: none;
}
ちなみに #lsx プラグインからの呼び出しの場合 <ul class="contentsx">....</ul> の部分のみが出力されます。toc, toctitle, toclist は #contentsx 単体呼び出し用と考えて使用できます。
キャッシュについて
１ページにつき１キャッシュです。
cache/ページ名.toc のような形で保存されます。
ページを毎回パースして見出しを見つける処理を短縮するためのキャッシュです。そこの計算量が多すぎなのです。
最終出力HTMLをキャッシュしているわけではありません。
最終出力HTMLをキャッシュしたい場合は ecache.inc.php を使用してください（更新タイミングは contentsx と同じです）
ページ参照時に（プラグイン実行時に）キャッシュファイルとdiffファイルのタイムスタンプを比べて、Wikiページのほうが新しければ更新します。
Wiki ページではなく diff ファイルのタイムスタンプを見ることによって「タイムスタンプを更新しない」編集でもキャッシュを最新に保つことができます。
アクション型(?cmd=contentsx)で管理者ならばキャッシュのリセットができます。
当プラグインについて
このプラグインはsonots
様のlsx.inc.phpを使用しています。