====== データテンプレートプラグイン ======

---- plugin ----
description: データプラグインへのテンプレート機能の追加
author     : Christoph Clausen
email      : christoph.clausen@gmail.com
type       : syntax
lastupdate : 2011-08-27
compatible : rincewind
depends    : data, sqlite
conflicts  : 
similar    : dataloop, templater
tags       : data, database, listing, template

downloadurl: https://github.com/ccl/dokuwiki-plugin-datatemplate/zipball/master
bugtracker : https://github.com/ccl/dokuwiki-plugin-datatemplate/issues
sourcerepo : https://github.com/ccl/dokuwiki-plugin-datatemplate/
donationurl: 
----

このプラグインは、[[data|データプラグイン]]の構造化データを、テンプレートを使用して表示する機能を追加します。
テンプレートは、データ入力や複数の入力のリストに対して個々に適用できます。
更に、このプラグインは、検索フォーム・ページ割付け・結果のキャッシュを提供します。

===== ダウンロードとインストール =====

プラグインのダウンロードとインストールは、上記の URL を使って [[plugin|プラグイン管理]] でできます。手動インストール方法は [[ja:plugins|プラグイン]] を参照してください。

==== 変更履歴 ====

{{rss>http://github.com/feeds/ccl/commits/dokuwiki-plugin-datatemplate/master date}} 

===== テンプレート定義 =====
テンプレートは、プレースホルダを含む別のWikiページです。
プレースホルダは次の2種類があります：
  * ''@@'' で囲まれたプレースホルダ（例：''@@Title@@''）は、テンプレートのページをwiki 構文に従って処理した //後から// 置き換えられます。データプラグインの特殊な型の変換規則は適用されます。''_mail'' という接尾語を持つフィールドは、e-mail のリンクとして出力されます。
  * プレースホルダ名の直前に感嘆符を付加したプレースホルダ（例：''@@!Title@@''）は、テンプレートを Dokuwiki パーサーに処理される //前に// 置き換えられます。これにより、画像の使用といった特定の状況下でのよりきめ細かな制御が可能です。

==== 例 ====
以下のようなテンプレートの場合、
<code>
=== @@Page@@ ===

{{@@!imgname@@?nolink&70 }}
**Phone**: @@phone@@ \\
**E-Mail**: @@email@@
</code>
''imgname'' フィールドの値を、DokuWikiの画像構文でファイル名として扱い、電話やメールアドレスを右側に置いた、左フロート画像となります。''datatemplatelist'' のカラムのパラメータに列挙された際、''email'' フィールドに ''_mail'' が付加されていれば、e-mail のリンクとして出力されます。

===== 構文 =====
このプラグインには、** 3個の **異なる構文のブロックがあります。
最初の二つは、基本的にデータプラグインの場合と同じですが、''template'' パラメータが追加されます：
  * ''datatemplateentry'' はデータプラグインの ''[[data#data_entry_入力|dataentry]]'' に相当します。置換用のプレースホルダとして（与えられた場合） ''headers'' パラメータに与えられた名前を使用する必要があることに注意してください。
  * ''datatemplatelist'' はデータプラグインの ''[[data#data_list_出力|datalist]]'' に相当します。兄弟とは違い ''datatemplatelist'' にはページ割付け機能があります。

上記のように、''template'' パラメータの値は、テンプレート定義を含む Dokuwiki ページです。''datatemplateentry'' の一例は以下のとおりです：
<code>
---- datatemplateentry member ----
template   : tpl_member
firstname  : Christoph
lastname   : Clausen
type       : PhD Student
active     : yes
addr       : GAP-Optique \\ Rue de l'Ecole de Medecine 20 \\ CH-1211 Geneve 4
----
</code>

==== Filter Form ====
Filter Form は、データプラグインやデータテンプレートプラグインに新機能を追加します。すでに ''datatable''、''datalist''、''datatemplatelist''が含まれるページで使用できます。構文例は次のようになります：
<code>
---- filterform ----
fields: Any, Title, Journal, Author, Volume, Page, Year, Abstract
----
</code>
''fields'' パラメータは、ページが出力される際にドロップダウンリストになります。値は、カラム名かヘッダーのリストです。ドロップダウンリストの隣はテキストフィールドです。フォームが送信されると、ドロップダウンで選択した場所にテキストフィールド内のテキストが含まれているデータだけが表示されます。例えば ''datatable'' のソース内に ''filter: Title~*weather*'' みたいな行を追加することと事実上同じです。

繰返しフォームを送信することで、次々にフィルター条件を追加することができます。また、適用されたフィルタを、個別に削除することができます。
 
===== デモ =====
ジュネーブ大学で応用物理学のグループの [[http://www.gap-optique.unige.ch/wiki/publications:start|Publications page]] を参照してください。 datatemplatelist と  filter form が動いています。リストの各項目は、datatemplate 項目です（BibTex を入力とする別のプラグインで作成しています）。[[http://www.gap-optique.unige.ch/wiki/members:start|Members page]] は同じように、このプラグインに基づいています。

===== キャッシュについての技術メモ =====
データプラグインは、単純なキーと値のペアとして、データを SQLite データベースに格納します。これは多くの柔軟性をもたらす一方で、データベースからデータを照会する時欠点があります。"普通の" SQLテーブルから結果のように見える内容を得るため、データプラグインは JOIN 操作を使って目的に合わせます。これは非常に時間がかかることがあります。前述した出版物のリストのケースで、一明細あたり約 300 項目の数件を得るのに、数秒かかりました。これはそんなに悪くない場合だが、抽出や一行で幾つかのそのような要求が発生するページナビゲーションでは、すぐイライラの原因になる。

datatemplatelist の単純なキャシュ技術は、大幅にページのクエリーを高速化します。主要な動作は以下のとおりです：
  - **検証：**ページ割付けや GET や POST から追加された抽出条件以外の単純なクエリは、要求されたデータを含んだページの ID のみを含んで、処理されます。このクエリーはとても限られた JOIN 操作数としか関係しないので、とても高速です。ページを含むファイルの修正時刻がチェックされており、キャッシュよりも新しいバージョンがない場合は、キャッシュが有効とみなされます。別のチェックは存在しないページに対応するキャッシュエントリを削除します。
  - **構築：** キャッシュを再構築する必要がある場合には、完全なクエリが実行されます。しかし、キャッシュファイルが多くなり過ぎるのを防ぐため、同じデータが繰返しキャッシュされるのを防ぐため、ページ割付けの制限やオフセット同様、GET や POST から追加された抽出条件は削除されます。
  - **保管：** キャッシュファイルは、Dokuwiki のキャッシュディレクトリに保管されます。ファイル名は、SQLクエリ文のハッシュ値です。

[[devel:caching#purging_the_cache|Dokuwiki purge mechanism]] を利用してキャッシュを強制的に再構築することができます。

===== 問題点 =====
現状、このプラグインには改善の余地があります。以下は既知の問題点を一部です：
  * テンプレート描画上の循環依存関係を検出できません。
  * テンプレートに相対リンクが含まれる場合、修正されません。
  * <del>テンプレートの描画はキャッシュされません。</del>
  * <del>テンプレートがページの最初のヘッダを与える場合、ページタイトルはヘッダーに応じて更新されていません。</del>
  * インクルードプラグインと同時に使用するといくつか問題があります。
  * 長時間使用しなかったキャッシュファイルを検出し自動的に削除することができません。

しかも、これらの（または他の）問題について将来のリリースで対処する約束はありません。。

===== 謝辞 =====
このプラグインは Martyn Eggleton の [[plugin:dataloop|dataloop plugin]] にインスパイヤされました。テンプレートの描画コードの多くの部分は、
Jonathan Arkell の [[plugin:templater|templater plugin]] が基になっています。

===== バグ、機能リクエスト、パッチ =====

バグや機能リクエストは、最上部のリンクにある課題トラッカーに対して提出してください。