DokuWiki

It's better when it's simple

使用者工具

網站工具


zh-tw:devel

currently translating FIXME

DokuWiki 樣板開發

您可以藉着創建一個新樣板來製作 DokuWiki 的外觀。樣板是保存在 <dokuwiki>/lib/tpl/ 目錄下的一個目錄中的一些 PHP 和 CSS 文件。(實事上,樣板是由 HTML 所組成,其中的 PHP 用於插入內容。)

入門指南

創建一個新樣板的最簡單方法,是用一個已經存在的樣板為起點。使用「缺省樣板」是個聰明的主意,因為它相當簡潔,並且遵循 DokuWiki 的樣板標準。樣板名稱(目錄名)必須為小寫字母,不能用“.” 或者 “_”。

  1. 複製 lib/tpl/default 目錄到 lib/tpl/yourname
  2. 在設定管理員裏選擇這個新樣板
  3. 然後看一看樣板文件(參見 目錄佈局
  4. 查閱有關 DokuWiki 如何採用它的 CSS dispatcher 處理 CSS
  5. 設定選項的處理,與 附加元件 類似。 使用 tpl_getConf(<setting>) 來恢復自定義樣板的設置。

目錄佈局

樣板應該遵循以下的目錄結構(所有的路徑都是與樣板目錄的相對路徑)。CSS 文件在 style.ini 文件中指定,您至少應該嘗試提供用於屏幕演示的和用於印刷的 CSS 文件。

  • <dokuwiki>/lib/tpl/<template>/
    • <filename>.css
    • main.php – DokuWiki 的總體佈局
    • detail.php – 圖片描述頁面
    • mediamanager.php – 媒體選擇的彈出框
    • images/ – 樣板用到的所有圖片
    • conf/
    • lang/ – 語言文件
      • <lang code>/lang.php – 樣板用到的本地化字符串
      • <lang code>/settings.php – 設定管理器中用到的本地化字符串
    • style.ini – 參見 Style.ini

函數

您可以在 API 文檔 中找到一個可用的函數列表。這是列出了一些比較特殊的函數。

tpl_content()

這個函數輸出頁面主體,或者說是您的wiki頁面的內容,包括 TOC。您可以在調用它的時候傳遞 false 參數來防止它輸出 TOC:

tpl_content(false);

這樣可以將 TOC 從內容中分離出來放到屏幕的其他地方。更多的細節參見 tpl_toc()

tpl_toc()

預設情況下,tpl_content() 函數會自己處理 目錄 TOC 的顯示,把它渲染成實際的頁面內容。如果您的樣板使用一個側邊欄或者其他復雜的佈局,您可能想把 TOC 獨立於內容放置在頁面中。這可以通過 tpl_toc() 函數做到。調用它的時候,傳遞 false 參數給 tpl_content() 函數來禁用自動的 TOC 佈局很關鍵。

示範:

<div id="content">
    <?php tpl_content(false)?>
</div>
 
<div id="sidebar">
    <?php tpl_toc()?>
</div>

tpl_toc() 函數從三個不同的來源渲染 TOC:一個全局的 $TOC 變量,頁面的 元數據 或者 admin pluginsgetTOC() 方法。在舊的版本或者預覽版中沒有元數據變量可用的情況下,tpl_toc() 只能使用全局的 $TOC 變量。因為 $TOC 變量被頁面的渲染引擎填充,所以只有當 tpl_toc()tpl_content() 之後 被調用的時候它才起作用。如果這種情況在您的樣板佈局中不可能存在,您可以使用輸出緩存來繞過這個問題。

示範:

<?php
    // render the content into buffer for later use
    ob_start();
    tpl_content(false);
    $buffer = ob_get_clean();
?>
 
<div id="sidebar">
    <?php tpl_toc()?>
</div>
 
<div id="content">
    <?php echo $buffer?>
</div>

tpl_getConf()

此函數用於在樣板中訪問 設定選項

全局變量和常量

有用的全局變量和常量的完整列表,請查閱 environment 頁面

自動化內務處理

在預設樣板的 main.php 文件底部附近,您會發現一個叫 tpl_indexerWebBug() 的函數。此函數在表示 lib/exe/indexer.php 結果時生成一個 HTML 標簽 <img>。DokuWiki 提供的內務處理這個 重要 的部分來維持 wiki 平穩地運行。所有的樣板都應該包含這個函數,如果沒有它,wiki 可能不能正確地運行(例如 搜索索引 不能生成)。

包含 Hooks

包含 Hooks 是一種不用您親自編寫您自己的 樣板 就可以添加一些靜態內容到您的 DokuWiki 結構的簡單的方法。您可以利用它們來添加標準頭部或者公司 logo 到每個頁面,或者在每個頁面的底部添加一份聲明。

DokuWiki 的預設樣板會在 lib/tpl/default/ 目錄中根據特殊的名稱來查找文件,並且在顯示的時候會在正確的位置簡單地包含它們。您可以添加任何您喜歡的 HTML 代碼到這些文件中。當然,這只有在您使用 default 樣板是時候才會有效。

給 PHP 開發者的提示: 您可能會很高興聽到您甚至可以在這些文件中包含 PHP。

可用的 Hooks

所有這些文件都可在 lib/tpl/default/ 目錄中被找到。

文件名 被包含在 HTML 中的位置
meta.html 在 <head> 標簽中,用這個文件來增加額外的樣式或者元數據
topheader.html 在頁面的最頂端 <body> 標簽之後
header.html 在頁面上端的藍色欄之上,在頁面名稱和 wiki 標題之下
pageheader.html 在 breadcrumbs 之下,在實際的內容之上
pagefooter.html 在頁面下端的藍色欄之上,在最後更改日期之下
footer.html 在頁面的最下端 </body> 標簽之前

DokuWiki 提供了一個 footer.html 的示範,它包含了一些按鈕和一份公共創作許可證的 RDF 描述。

zh-tw/devel.txt · 上一次變更: 2014-02-27 17:22 由 Klap-in

若無特別註明,本 wiki 上的內容都是採用以下授權方式: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki