contentsxプラグイン の変更点

Top > contentsxプラグイン
*概要 [#y5695158]
ページの目次を作成する #contents のプラグイン化、拡張
**本体組み込み #contents との違い [#xf34b3f4]
-設置行以降の見出しのみリストする機能
-MenuBar に設置しても有効
-見出しレベル指定機能
-表示件数指定機能
-正規表現による見出しのフィルタ機能
-正規表現による見出しの除外フィルタ機能
-キャッシュ機能
-リンク形態指定機能(リンクしないなど)
-固定アンカ必須

*使い方 [#h482fea2]
固定アンカ必須です。pukiwiki.ini.php で $fixed_heading_anchor = 1; と設定します。 PukiWiki Plus! の場合デフォルトで有効です。

固定アンカは編集保存する際に自動作成されます。 今まで設定していなかった場合、全てのページを編集保存しなおす必要があります。

**書式 [#neae4d12]
 #contentsx(オプション)

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

***page=ページ名 [#f2bee01e]
見出しリストを行うページを指定できる。デフォルトはカレントページ。

***fromhere=bool [#e78d19e0]
 #contentsx がある行以降の見出しのみをリストする。デフォルトで有効。

備考：page オプションで別ページを指定した場合は強制的に off になります。

***hierarchy=bool [#r167c6bc]
階層的表示。デフォルトで有効。

***compact=bool [#y45222f6]
リストのレベルを詰める。デフォルトで有効。気になる場合は使用例参照のこと。

***num=数字 [#j130988a]
表示件数指定。正数は前からＮ件目、負数は後ろからＮ件目の意味。

num=1:10 で先頭１件目から１０件目までの意味。num=-10:-1 で後ろ１０件目から後ろ１件目までの意味。num=2: で先頭２件目から最後までの意味。 num=5+2 で先頭５件目から、そこから２件先まで(5,6,7)の意味。

***depth=数字 [#t6ce90b2]
見出しレベル限定。数字の指定は num と同じ書式。

includeページタイトルはレベル0になる。compact=on,off に関わらず絶対値指定。

***except=正規表現 [#h19de4f9]
リストしない見出しを正規表現にて指定。

ヒント： ereg で判定を行います。 except=Test|sample → Test または sample を含む見出しを除く。
filter=正規表現

リストする見出しを正規表現で限定する。

ヒント： ereg で判定を行います。

***include=bool [#xcedd776]
#include プラグインで取り込んでいるページとその見出しも扱う。 デフォルトで有効。

***cache=on | off [#tda9731e]
キャッシュの利用。デフォルトで有効。
link=on | off | anchor | page

リンク形態指定。デフォルトは on。

    on - 柔軟に、現在ページへは link=anchor、page オプションで別ページが指定されていた場合 link=page。
    anchor - 強制的にアンカーのみ使用。
    page - 強制的にページ名も含めたリンク。
    off - リンクしない。

ヒント： link=anchor で include したページに対してもページ内アンカーによるリンクを貼れます。include にはもともと対応していますが、類似のものにも対応できると思います。link=page はついでです。

*動作例(仕様) [#ycf25583]
次のような「とあるページ」があったとします。
 **AA
 #contentsx
 *B
 ***BBB
 **BC
 #include(別のページ)
 *D

「別のページ」の内容は次のとおりだったとします。
 *1
 #contentsx
 **11

「とあるページ」の #contetnsx が変更されると思ってください。

まず参考に #contents

 #contents
 出力）
    AA
    B
        BBB
        BC
    D
#hr
 #contentsx //デフォルト動作 == #contentsx(include,fromhere,compact,hierarchy)
 出力）
    B
        BBB
        BC
    別のページ
        1
            11
    D
#hr
 #contentsx(include=off,fromhere=off,compact=off,hierarchy=off)
 出力）
    AA
    B
    BBB
    BC
    D
#hr
 #contentsx(include=off,fromhere=off,compact=off,hierarchy) // 以下 hierarchy 略
 出力）
    AA

    B
        BBB
        BC
    D
#hr
 #contentsx(include=off,fromhere=off,compact) // compact
 出力）
    AA (<-注目)
    B
        BBB (<-注目)
        BC
    D

完全に #contents と同じものはないが、compact としてはこの挙動が正解だと思っている(#contents の場合は先頭要素だけが compact されている)。
#hr
 #contentsx(include=off,fromhere,compact=off) // fromhere
 出力）
    B
        BBB
        BC
    D
#hr
 #contentsx(include,fromhere=off,compact=off) // include
 出力）
    AA

    B
        BBB (表現できない。もう1段下がる)
        BC

    別のページ
        1
            11
        D

include がある場合、全体的に１段階下がる。
#hr
 #contentsx(depth=1:2,compact=false)
 出力）
    B
        BC
    1
        11
    D

include が depth=0
#hr
 #contentsx(depth=1:2) // compact
 出力）
    B
        BC
    1
        11
    D
#hr
 #contentsx(depth=1:2,filter=B)
 出力）
    B
        BC
#hr
 #contentsx(depth=1:2,except=B)
 出力）
    1
        11
    D
#hr
 #contentsx(depth=1:2,except=B,num=1:2)
 出力）
    1
        11
#hr
 #contentsx(page=別のページ)
 出力）
    1
        11

*FAQ [#d68d5ad4]
**MenuBar に設置する場合？ [#z92616a4]
MenuBar に設置する際は
 #contentsx(fromhere=off)
のように記述しておきます*1。

**CSSデザイン [#yb25d555]
 #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)で管理者ならばキャッシュのリセットができます。

*当プラグインについて [#oeb31f90]
このプラグインは[[sonots>http://pukiwiki.sonots.com]]様の[[lsx.inc.php>http://pukiwiki.sonots.com/index.php?Plugin%2Fcontentsx.inc.php]]を使用しています。