差分

このページの2つのバージョン間の差分を表示します。

--- ja:devel:templates [2008-11-18 09:30] – Include Hooks 更新 118.105.223.245
+++ ja:devel:templates [2010-03-14 05:25] (現在) – 222.11.220.47
@@ 行 1: / 行 1: @@
+====== DokuWiki テンプレート開発 ======
+[[ja:DokuWiki]] のデザインは、新しいテンプレートを作ることでカスタマイズすることができます。テンプレートは ''<dokuwiki>/lib/tpl'' ディレクトリの直下のディレクトリに格納されている PHP ファイルと CSS ファイルからなっています。（実際には、テンプレートは HTML でできていますが、ページのコンテンツを挿入するために PHP が使われています）
+===== 始めましょう =====
+テンプレートを新しく作成する最も簡単な方法は、既存のテンプレートを起点とすることです。デフォルトのテンプレートを使うのはよい考えです。きれいな上に DokuWiki テンプレートの標準に倣っているからです。テンプレート名（ディレクトリ）は小文字で、"." や
+ "_" は使えません。
+  - ''lib/tpl/default'' のディレクトリのデータを ''lib/tpl/yourname'' へコピーします
+  - 設定マネージャーで新しいテンプレートを選択します
+  - そしてテンプレートファイルの中身を見ます ([[#ディレクトリ配置]] 参照)
+  - [[ja:DokuWiki]] が [[ja:devel:css|CSS dispatcher]] を用いてどのように [[CSS]] を扱うかを見ます
+  - 構成設定の扱いは[[common_plugin_functions|プラグイン]]と似ています。カスタムテンプレート設定を取得するには ''%%tpl_getConf(<setting>)%%'' を用いてください。
+===== ディレクトリ配置 =====
+テンプレートは以下のディレクトリ構造に倣うべきです（すべてのパスはテンプレートディレクトリから相対的です）。 CSS ファイルは ''[[CSS#style.ini]]'' で指定されますが、少なくともスクリーン用と印刷用に一つずつ用意するべきです。
+  * ''<dokuwiki>/lib/tpl/<template>/''
+    * ''<filename>.css''
+    * ''[[devel:templates:main.php]]'' -- DokuWiki の全体的なレイアウト
+    * ''[[devel:templates:detail.php]]'' -- 画像の詳細ページ
+    * ''[[devel:templates:mediamanager.php]]'' -- メディア選択のポップアップ
+    * ''images/'' -- テンプレートの中で使われるすべての画像
+    * ''conf/''
+      * ''default.php'' -- [[configuration#デフォルトの設定]] （''[[#tpl_getConf]]'' 参照）
+      * ''metadata.php'' -- [[configuration#メタデータの設定]] （''[[#tpl_getConf()]]'' 参照）
+    * ''lang/'' -- 言語ファイル
+      * ''<lang code>/lang.php'' -- テンプレート内で使用されている言葉をローカライゼーションします
+      * ''<lang code>/settings.php'' -- 設定マネージャーで使用されている言葉をローカライゼーションします
+    * ''style.ini'' -- [[CSS#Style.ini]] 参照
+===== 関数 =====
+利用できる関数のリストは [[http://dev.splitbrain.org/reference/dokuwiki/nav.html?inc/template.php.html|API documentation]] でわかります。ここでは特異なものをいくつか示します。
+==== tpl_content() ====
+この関数はページの本文、言い換えれば [[ja:TOC]] を含むあなたの Wiki のページのコンテンツを出力します。
+この関数を呼ぶ際に引数として ''false'' を渡せば、TOC を出力させないようにできます：
+<code php>
+tpl_content(false);
+</code>
+これは、TOC をコンテンツから分離して画面のどこか違うところに置きたいときに、使うことができます。
+さらなる詳細は ''[[#tpl_toc()]]'' を参照してください。
+==== tpl_toc() ====
+デフォルトでは ''[[#tpl_content()]]'' 関数は [[ja:TOC|Table of Contents]] を実際のページコンテンツの直前に表示しますが、あなたのテンプレートがサイトバーや複雑なレイアウトを使っている場合は、TOC をページのコンテンツから独立させたいと思うかもしれません。これは ''tpl_toc()'' 関数が可能にします。
+これを使用するときは、''tpl_content()'' の引数を ''false'' とすることで TOC の自動配置を無効にしておくことが重要です。
+**例:**
+<code php>
+<div id="content">
+    <?php tpl_content(false)?>
+</div>
+<div id="sidebar">
+    <?php tpl_toc()?>
+</div>
+</code>
+''tpl_toc()'' 関数は TOC を以下の3箇所から生成します。グローバル変数 [[environment#$TOC]]、そのページの[[metadata|メタデータ]]、または [[admin plugins]] の ''getTOC()'' メソッドです。
+古いリビジョンやプレビューではメタデータが使えないので、これらの場合には ''tpl_toc()'' はグローバル変数 [[environment#$TOC]] しか使うことはできません。
+[[environment#$TOC]] 変数はページレンダラによって設定されるので、''tpl_toc()'' が ''tpl_content()'' の**後で**呼び出されたときにしか動作しません。
+もしあなたのテンプレートのレイアウトでこの順序で呼び出せない場合は、この問題を回避するために出力バッファリングを使うとよいでしょう。
+**例:**
+<code php>
+<?php
+    // あとで使うためにバッファー中にコンテンツを生成
+    ob_start();
+    tpl_content(false);
+    $buffer = ob_get_clean();
+?>
+<div id="sidebar">
+    <?php tpl_toc()?>
+</div>
+<div id="content">
+    <?php echo $buffer?>
+</div>
+</code>
+==== tpl_getConf() ====
+この関数はテンプレートの中から[[configuration|構成設定]]にアクセスするために使用されます。
+===== グローバル変数と定数 =====
+便利なグローバル変数と定数の完全なリストは[[environment|環境]]のページを参照してください。
+===== 自動管理 =====
+デフォルトテンプレートの [[devel:templates:main.php]] ファイルのほぼ最下部に ''tpl_indexerWebBug()'' への関数呼出しがあります。この関数は、''[[:indexer|lib/exe/indexer.php]]'' へのリクエストが行われるように、HTML　の ''%%<img>%%'' タグを生成します。この**不可欠な** DokuWiki のパーツは wiki をスムーズに動作させるために重要な管理を提供します。すべてのテンプレートはこの関数を含むべきで、これがなければ wiki は正しく動作しないかもしれません（たとえば[[ja:search|検索インデックス]]が作られないなど）。
+===== 挿入フック =====
+挿入フックは、独自の[[ja:Template|テンプレート]]を書かずに、あなたの [[ja:DokuWiki]] に静的なコンテンツを加える簡易な方法です。これを用いると、各ページに共通のヘッダや企業ロゴを加えたり、各ページの末尾に免責文を加えたりできます。
+DokuWiki のデフォルトのテンプレートは、ページを表示する際、''lib/tpl/default/'' ディレクトリ内の特別な名前のファイルを探し、適切な場所に単純に挿入します。これらのファイルには好きな HTML を追加できます。もちろんこれは//デフォルト//のテンプレートを使っている時のみ動作します。
+__PHP 開発者のためのヒント__： これらのファイルの中に PHP を含むことも可能です。
+==== 利用可能なフック ====
+これらのファイルはすべて ''lib/tpl/default/'' ディレクトリ内から検索されます。
+^ ファイル名        ^ 挿入される HTML の場所                                               ^
+| ''meta.html''       | HTML の <head> 内。追加のスタイルやメタヘッダーを追加するために使用 |
+| ''topheader.html''  | <body> タグ直後のページの先頭 |
+| ''header.html''     | 上部の青いバーよりも上で、ページ名と Wiki タイトルの下 |
+| ''pageheader.html'' | パンくずリストの下で、実際のコンテンツの上 |
+| ''pagefooter.html'' | 下部の青いバーの上で、最終更新日の下 |
+| ''footer.html''     | </body> タグ直前のページの末尾 |
+DokuWiki には、いくつかのボタンと、CC ライセンスの RDF 記述を含んだ ''footer.html'' の例が付属しています。