DokuWiki

It's better when it's simple

用户工具

站点工具


侧边栏

本页面的其他翻译?:

了解DokuWiki

进阶使用

商用

我们的社区


Facebook, Twitter 或其他社交网络上关注我们.

zh:devel:templates

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
    • favicon.ico – 如果没有设置将会启用此项 (查看 tpl_getFavicon())

函数

您可以在 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/devel/templates.txt · 最后更改: 2017-03-03 09:24 由 113.67.227.220