DokuWiki

It's better when it's simple

用户工具

站点工具


侧边栏

本页面的其他翻译?:

了解DokuWiki

进阶使用

商用

我们的社区


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

zh:devel:templates

DokuWiki 模板开发

您可以通过创建一个新的模板来定制 DokuWiki 的外观。模板是保存在 <dokuwiki>/lib/tpl/ 目录下面模板目录中的一些 PHP 和 CSS 文件。

入门指南

创建一个新模板的最简单的方法是用一个已经存在的模板为起点。使用缺省模板是一个不错的主意,因为它相当简洁并且遵循 DokuWiki 的模板标准。

  1. 安装 starter 模版 (可选,该“最小”分支是个更干净的起点。
  2. 复制 lib/tpl/default 目录到 lib/tpl/yourname
  3. 在配置设置中选择这个新的模板
  4. 根据你心中所想改变模板;要理解Dokuwiki模板怎么建,可以查看 目录布局以及怎样处理 CSS
  5. 当你的模板准备好后,考虑将它发布到dokuwiki的模版页上。

模板命名约定

一个有效的名称(目录):

  • 应该只包含a-z和0-9。
  • ., 划线 - 和下划线 _ 允许的,作为:
    • DokuWiki的架构不再支持。
    • 使用下划线还会给一个流行度 为零。
  • 如果两个不同的模板使用了相同的名字
    • 他们会互相排除并且天生不相容,
    • 此外,只有一个可以在dokuwiki.org上有模板主页。

目录布局

模板应该遵循以下的目录结构(所有的路径都是与模板目录的相对路径)。

CSS 文件在 style.ini 文件中指定,您应尝试提供‘用于屏幕演示’和‘用于印刷’ 的两组 CSS 文件。

  • <dokuwiki>/lib/tpl/<template>/
    • <filename>.csstemplate's stylesheets (如果有多个文件,应该把它们归组到 css/ 子目录)
    • script.js – 可选,如果模板需要 JavaScript
    • main.php – DokuWiki 的总体布局
    • detail.php – 图片描述页面
    • mediamanager.php – 媒体选择的弹出框
    • images/ – 模板用到的所有图片(如果有的话)
    • conf/ –配置文件(可选,如是使用配置)
    • lang/ – 语言文件
      • <lang code>/lang.php本地化字符串 用在模板中。(可选,需要时使用)
      • <lang code>/settings.php – 本地化字符串用于配置管理器 (如果使用了配置)
    • style.ini – 参见 style.ini
    • favicon.ico – favicon (通过上传另一个到根目录或者wiki命名空间当使用了tpl_favicon() )时被覆盖。
    • template.info.txt – 带有 模板信息的文本文件 必须!

处理配置设置同 插件类似。 使用 tpl_getConf(<setting>) 获取定制模板设置。保存本地设置存储在DokuWiki的全局 conf/local.php中。

内部工作原理

函数

您可以在 API documentation 中找到一个可用的函数列表。这里列出了一些比较特殊的函数。

  • tpl_content()
    该函数输出页的body,换句话说就是你的wiki页的内容。包括 TOC。你可以调用时通过TOC传入false阻止TOC的输出:
tpl_content(false);

这可以用来将TOC从内容中分开并把它放到屏幕的其它地方。更多信息参见下面的 tpl_toc()

  • tpl_toc()
    缺省情况下,tpl_content() 函数会处理好自身显示一个 内容目录 , 预先将它放到实际页内容中。如果模板使用边栏或其它更复杂的布局,你想把TOC放在内页内容之外。可以通过 tpl_toc() 函数。当使用时,重要的是要禁止自动放置TOC,通过传递参数 falsetpl_content() 函数。

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

    tpl_toc() 函数从三个不同的源生成 TOC : 一个全局 $TOC 变量, 页面 metadata 或者 admin pluginsgetTOC() 方法. 因为在老的修订版中没有元数据变量或者预览 tpl_toc() 只能用在全局 $TOC 变量中。因为$TOC 变量由页面渲染填充,仅在 tpl_toc()tpl_content() 之后调用才起作用。 如果在你的模板中不可能做到的话,你可以使用输出缓冲来解决这个问题。

    例如:

    <?php
        // 将内容生成到缓冲中供以后使用
        ob_start();
        tpl_content(false);
        $buffer = ob_get_clean();
    ?>
     
    <div id="sidebar">
        <?php tpl_toc()?>
    </div>
     
    <div id="content">
        <?php echo $buffer?>
    </div>
  • 还有更多其经有用的模板函数,请查看 API 文档

全局变量和常量

有用的全局变量和常量的完整列表,请查阅 environment 页面

自动化内务处理

在默认模板的 main.php 文件底部附近,您会发现一个叫 tpl_indexerWebBug() 的函数。该函数生成一个 HTML 标签 <img> 最终请求到lib/exe/indexer.php。DokuWiki 提供的内务处理这个 重要 的部分来维持 wiki 平稳地运行。所有的模板都应该包含这个函数,如果没有它,wiki 可能不能正确地运行(例如 搜索索引 不能生成)。

'dokuwiki' 类

一个叫做 dokuwiki 的类应该加到一些包含元素的内容中。 (可以围着任何东西或至少围着 tpl_content()) 在每个模板的 main.php, detail.phpmediamanager.php中。这是确保DokuWiki的样式没有干扰其它样式,如果集成到现存网站中会有潜在的CSS冲突。

包含 Hooks

包含 Hooks 是一种不用您亲自编写您自己的 模板 就可以添加一些静态内容到您的 DokuWiki 结构的简单的方法。您可以利用它们来添加标准头部或者公司 logo 到每个页面,或者在每个页面的底部添加一份声明。

DokuWiki 的默认模板会在模板目录中根据特殊的名称来查找文件,并且在显示的时候会在正确的位置简单地包含它们。您可以添加任何您喜欢的 HTML 代码到这些文件中。当然,这只有在您使用 default 模板是时候才会有效。

转换现存的模板

如果你缺少设计技巧,你可以转换现存的模板。存在有很多的自由选项。如果你喜欢发布它们,请确保遵循协议 GPL2-compatible.

避免问题

以下是模板开发人员遇到的一些问题以及如何避免它们:

不要将JavaScript命令放在页面的<body>标记中

这包括onLoad等。尽管违反此规则根本不会影响FireFox,但由于页面编辑需要JavaScript,因此Internet Explorer(甚至IE 7)将出现JavaScript错误,并且这可能会导致页面无法正确显示,您会发现编辑栏将在您需要时丢失。

在开发模板时关闭“压缩CSS和JavaScript文件”

由于此选项处于打开状态,因此某些模板开发人员在使用DokuWiki缓存CSS和JS文件时遇到问题,但这很难查明。为了安全起见,暂时关闭此功能。

在对CSS文件进行更改后,使用“强制刷新”

您可以通过按Ctrl + F5或按住shift-control-alt并在浏览器中按下刷新按钮来完成此操作。

这不是由于DokuWiki的工作原理,而是当前浏览器如何缓存文件。即使新版本可用,浏览器也会缓存样式表,因此您需要执行此操作。

在dokuwiki.org上发布模板

如果您创建了模板,请与社区分享。只需在template命名空间中创建一个以您的模板命名的页面。例如,如果你的模板文件夹被命名为'sample,则在wiki中创建一个template:sample''页面。

该页面应包含有关如何安装和使用模板的所有必需文档,添加屏幕截图也可能是一个好主意。

在模板页面的顶部必须填入一些元数据字段。每个字段的说明可以在Repository Plugin页面找到。

从Ponder Stibbon版本开始可以有自动更新信号。为使更新过程正常工作,模板wiki页面上的“上次更新日期”的日期必须等于源tarball /zip文件中的template.info.txt文件中的日期。如果情况并非如此,更新将不会发生或会有持续的“更新”信号。

dokuwiki.org上不允许上传,因此您需要在其他地方托管您的模板文件。我们建议使用git等版本控制系统来管理您的源代码。如果你这样做,最简单的方法就是使用 GitHub这样的公共库,它还会为你的仓库提供了一个bug跟踪器。

zh/devel/templates.txt · 最后更改: 2018-05-20 13:06 由 eureka