您的足迹:
差别
这里会显示出您选择的修订版和当前版本之间的差别。
devel:templates [2018/05/20 17:44] eureka 创建 |
devel:templates [2018/05/20 19:05] (当前版本) eureka 根据最新内容重新翻译 |
||
---|---|---|---|
行 1: | 行 1: | ||
====== DokuWiki 模板开发 ====== | ====== DokuWiki 模板开发 ====== | ||
- | 您可以通过创建一个新的模板来定制 [[:DokuWiki]] 的外观。模板是保存在 ''<dokuwiki>/lib/tpl/'' 目录下的一个目录中的一些 PHP 和 CSS 文件。(事实上,模板由 HTML 组成,使用 PHP 插入内容。) | + | 您可以通过创建一个新的模板来定制 [[:DokuWiki]] 的外观。模板是保存在 ''<dokuwiki>/lib/tpl/'' 目录下面模板目录中的一些 PHP 和 CSS 文件。 |
===== 入门指南 ===== | ===== 入门指南 ===== | ||
- | 创建一个新模板的最简单的方法是用一个已经存在的模板为起点。使用缺省模板是一个不错的主意,因为它相当简洁并且遵循 DokuWiki 的模板标准。模板名称(目录名)必须为小写字母,不能用"." 或者 "_"。 | + | 创建一个新模板的最简单的方法是用一个已经存在的模板为起点。使用缺省模板是一个不错的主意,因为它相当简洁并且遵循 DokuWiki 的模板标准。 |
- 安装 [[template:starter]] 模版 (可选,该“最小”分支是个更干净的起点。 | - 安装 [[template:starter]] 模版 (可选,该“最小”分支是个更干净的起点。 | ||
行 11: | 行 11: | ||
- 根据你心中所想改变模板;要理解Dokuwiki模板怎么建,可以查看 [[#目录布局]]以及怎样处理 [[CSS]] 。 | - 根据你心中所想改变模板;要理解Dokuwiki模板怎么建,可以查看 [[#目录布局]]以及怎样处理 [[CSS]] 。 | ||
- 当你的模板准备好后,考虑将它发布到dokuwiki的模版页上。 | - 当你的模板准备好后,考虑将它发布到dokuwiki的模版页上。 | ||
+ | |||
+ | === 模板命名约定 === | ||
+ | |||
+ | 一个有效的名称(目录): | ||
+ | * 应该只包含a-z和0-9。 | ||
+ | * 点 ''.'', 划线 ''-'' 和下划线 ''_'' 是 **不** 允许的,作为: | ||
+ | * DokuWiki的架构不再支持。 | ||
+ | * 使用下划线还会给一个[[:popularity|流行度]] 为零。 | ||
+ | * 如果两个不同的模板使用了相同的名字 | ||
+ | * 他们会互相排除并且天生不相容, | ||
+ | * 此外,只有一个可以在dokuwiki.org上有模板主页。 | ||
+ | |||
===== 目录布局 ===== | ===== 目录布局 ===== | ||
- | 模板应该遵循以下的目录结构(所有的路径都是与模板目录的相对路径)。CSS 文件在 ''[[CSS#style.ini]]'' 文件中指定,您应尝试提供‘用于屏幕演示’和‘用于印刷’ 的两组 CSS 文件。 | + | 模板应该遵循以下的目录结构(所有的路径都是与模板目录的相对路径)。 |
+ | |||
+ | CSS 文件在 ''[[CSS#style.ini]]'' 文件中指定,您应尝试提供‘用于屏幕演示’和‘用于印刷’ 的两组 CSS 文件。 | ||
* ''<dokuwiki>/lib/tpl/<template>/'' | * ''<dokuwiki>/lib/tpl/<template>/'' | ||
- | * ''<filename>.css'' | + | * ''<filename>.css'' -- [[devel:css#templates_styles|template's stylesheets]] (如果有多个文件,应该把它们归组到 ''css/'' 子目录) |
+ | * ''script.js'' -- 可选,如果模板需要 [[devel:JavaScript]] | ||
* ''[[devel:templates:main.php]]'' -- DokuWiki 的总体布局 | * ''[[devel:templates:main.php]]'' -- DokuWiki 的总体布局 | ||
* ''[[devel:templates:detail.php]]'' -- 图片描述页面 | * ''[[devel:templates:detail.php]]'' -- 图片描述页面 | ||
* ''[[devel:templates:mediamanager.php]]'' -- 媒体选择的弹出框 | * ''[[devel:templates:mediamanager.php]]'' -- 媒体选择的弹出框 | ||
- | * ''images/'' -- 模板用到的所有图片 | + | * ''images/'' -- 模板用到的所有图片(如果有的话) |
- | * ''conf/'' | + | * ''conf/'' --配置文件(可选,如是使用配置) |
- | * ''default.php'' -- [[configuration#默认设置]] (参见 ''[[#tpl_getConf]]'') | + | * ''default.php'' -- [[configuration#默认设置]]中的[[devel:configuration#模板设置]] |
- | * ''metadata.php'' -- [[configuration#配置元数据]] (参见 ''[[#tpl_getConf()]]'') | + | * ''metadata.php'' -- [[configuration#configuration 元数据]] 描述配置管理器中的设置属性。 |
* ''lang/'' -- 语言文件 | * ''lang/'' -- 语言文件 | ||
- | * ''<lang code>/lang.php'' -- 模板用到的本地化字符串 | + | * ''<lang code>/lang.php'' -- [[[[devel:localization#template_localization|本地化字符串]] 用在模板中。(可选,需要时使用) |
- | * ''<lang code>/settings.php'' -- 配置管理器中用到的本地化字符串 | + | * ''<lang code>/settings.php'' -- 本地化字符串用于配置管理器 (如果使用了配置) |
- | * ''style.ini'' -- 参见 [[CSS#Style.ini]] | + | * ''style.ini'' -- 参见 [[devel:style.ini]] |
- | * ''favicon.ico'' -- 如果没有设置将会启用此项 (查看 [[xref>tpl_getFavicon()|tpl_getFavicon()]]) | + | * ''favicon.ico'' -- favicon (通过上传另一个到根目录或者wiki命名空间当使用了[[xref>tpl_favicon()|tpl_favicon()]] )时被覆盖。 |
+ | * ''template.info.txt'' -- 带有 [[devel:template info|模板信息]]的文本文件 **必须!** | ||
+ | 处理配置设置同 [[common_plugin_functions|插件]]类似。 使用 ''%%tpl_getConf(<setting>)%%'' 获取定制模板设置。保存本地设置存储在DokuWiki的全局 ''conf/local.php''中。 | ||
- | ===== 函数 ===== | + | ===== 内部工作原理 ===== |
- | 您可以在 [[http://dev.splitbrain.org/reference/dokuwiki/nav.html?inc/template.php.html|API 文档]] 中找到一个可用的函数列表。这是列出了一些比较特殊的函数。 | + | ===== 函数 ===== |
- | ==== tpl_content() ==== | + | |
- | 这个函数输出页面主体,或者说是您的wiki页面的内容,包括 [[:TOC]]。您可以在调用它的时候传递 ''false'' 参数来防止它输出 TOC: | + | |
+ | 您可以在 [[xref>inc/template.php|API documentation]] 中找到一个可用的函数列表。这里列出了一些比较特殊的函数。 | ||
+ | |||
+ | * **''[[xref>tpl_content()]]''** \\ 该函数输出页的body,换句话说就是你的wiki页的内容。包括 [[:TOC]]。你可以调用时通过TOC传入''false''阻止TOC的输出: | ||
<code php> | <code php> | ||
tpl_content(false); | tpl_content(false); | ||
- | </code> | + | </code>这可以用来将TOC从内容中分开并把它放到屏幕的其它地方。更多信息参见下面的 ''tpl_toc()'' 。 |
- | 这样可以将 TOC 从内容中分离出来放到屏幕的其它地方。更多的细节参见 ''[[#tpl_toc()]]'' 。 | + | * **''[[xref>tpl_toc()]]''** \\ 缺省情况下,''tpl_content()'' 函数会处理好自身显示一个 [[:TOC|内容目录]] , 预先将它放到实际页内容中。如果模板使用边栏或其它更复杂的布局,你想把TOC放在内页内容之外。可以通过 ''tpl_toc()'' 函数。当使用时,重要的是要禁止自动放置TOC,通过传递参数 ''false'' 到 ''tpl_content()'' 函数。\\ \\ **例如:** \\ <code php> |
- | + | ||
- | ==== tpl_toc() ==== | + | |
- | + | ||
- | 默认情况下,''[[#tpl_content()]]'' 函数会自己处理 [[:TOC|目录 TOC]] 的显示,把它渲染成实际的页面内容。如果您的模板使用一个侧边栏或者其它复杂的布局,您可能想把 TOC 独立于内容放置在页面中。这可以通过 ''tpl_toc()'' 函数做到。调用它的时候,传递 ''false'' 参数给 ''tpl_content()'' 函数来禁用自动的 TOC 布局很关键。 | + | |
- | + | ||
- | **样例:** | + | |
- | + | ||
- | <code php> | + | |
<div id="content"> | <div id="content"> | ||
<?php tpl_content(false)?> | <?php tpl_content(false)?> | ||
行 57: | 行 67: | ||
<?php tpl_toc()?> | <?php tpl_toc()?> | ||
</div> | </div> | ||
- | </code> | + | </code> ''tpl_toc()'' 函数从三个不同的源生成 TOC : 一个全局 [[environment#$TOC]] 变量, 页面 [[metadata]] 或者 [[admin plugins]] 的 ''getTOC()'' 方法. 因为在老的修订版中没有元数据变量或者预览 ''tpl_toc()'' 只能用在全局 [[environment#$TOC]] 变量中。因为[[environment#$TOC]] 变量由页面渲染填充,仅在 ''tpl_toc()'' 在 ''tpl_content()'' **之后**调用才起作用。 如果在你的模板中不可能做到的话,你可以使用输出缓冲来解决这个问题。 \\ \\ **例如:**\\ <code php> |
- | + | ||
- | ''tpl_toc()'' 函数从三个不同的来源渲染 TOC:一个全局的 [[environment#$TOC]] 变量,页面的 [[metadata|元数据]] 或者 [[admin plugins]] 的 ''getTOC()'' 方法。在旧的版本或者预览版中没有元数据变量可用的情况下,''tpl_toc()'' 只能使用全局的 [[environment#$TOC]] 变量。因为 [[environment#$TOC]] 变量被页面的渲染引擎填充,所以只有当 ''tpl_toc()'' 在 ''tpl_content()'' **之后** 被调用的时候它才起作用。如果这种情况在您的模板布局中不可能存在,您可以使用输出缓存来绕过这个问题。 | + | |
- | + | ||
- | **样例:** | + | |
- | + | ||
- | <code php> | + | |
<?php | <?php | ||
- | // render the content into buffer for later use | + | // 将内容生成到缓冲中供以后使用 |
ob_start(); | ob_start(); | ||
tpl_content(false); | tpl_content(false); | ||
行 80: | 行 84: | ||
</code> | </code> | ||
- | ==== tpl_getConf() ==== | + | * **''[[xref>tpl_getConf()|tpl_getConf('key')]]''** \\ 该函数用用在模板中访问 [[configuration|配置设置]] 。 |
- | 此函数用于在模板中访问 [[configuration|配置设置]] 。 | + | |
+ | * **''[[xref>tpl_getLang()|tpl_getLang('key')]]''** \\ 该函数用来访问模板中的本地化字符串。更多信息参见 [[devel:localization]] 开发文档。 | ||
+ | |||
+ | * 还有更多其经有用的模板函数,请查看 [[xref>inc/template.php|API 文档]] | ||
===== 全局变量和常量 ===== | ===== 全局变量和常量 ===== | ||
行 88: | 行 96: | ||
===== 自动化内务处理 ===== | ===== 自动化内务处理 ===== | ||
- | 在默认模板的 [[devel:templates:main.php]] 文件底部附近,您会发现一个叫 ''tpl_indexerWebBug()'' 的函数。此函数在表示 ''[[:index|lib/exe/indexer.php]]'' 结果时生成一个 HTML 标签 ''%%<img>%%''。DokuWiki 提供的内务处理这个 **重要** 的部分来维持 wiki 平稳地运行。所有的模板都应该包含这个函数,如果没有它,wiki 可能不能正确地运行(例如 [[:search|搜索索引]] 不能生成)。 | + | 在默认模板的 [[devel:templates:main.php]] 文件底部附近,您会发现一个叫 ''[[xref>tpl_indexerWebBug()]]'' 的函数。该函数生成一个 HTML 标签 ''%%<img>%%'' 最终请求到''[[:indexer|lib/exe/indexer.php]]''。DokuWiki 提供的内务处理这个 **重要** 的部分来维持 wiki 平稳地运行。所有的模板都应该包含这个函数,如果没有它,wiki 可能不能正确地运行(例如 [[:search|搜索索引]] 不能生成)。 |
+ | |||
+ | ==== 'dokuwiki' 类 ==== | ||
+ | |||
+ | 一个叫做 ''dokuwiki'' 的类应该加到一些包含元素的内容中。 (可以围着任何东西或至少围着 ''tpl_content()'') 在每个模板的 [[devel:templates:main.php]], [[devel:templates:detail.php]] 和 [[devel:templates:mediamanager.php]]中。这是确保DokuWiki的样式没有干扰其它样式,如果集成到现存网站中会有潜在的CSS冲突。 | ||
===== 包含 Hooks ===== | ===== 包含 Hooks ===== | ||
行 94: | 行 106: | ||
包含 Hooks 是一种不用您亲自编写您自己的 [[:Template|模板]] 就可以添加一些静态内容到您的 [[:DokuWiki]] 结构的简单的方法。您可以利用它们来添加标准头部或者公司 logo 到每个页面,或者在每个页面的底部添加一份声明。 | 包含 Hooks 是一种不用您亲自编写您自己的 [[:Template|模板]] 就可以添加一些静态内容到您的 [[:DokuWiki]] 结构的简单的方法。您可以利用它们来添加标准头部或者公司 logo 到每个页面,或者在每个页面的底部添加一份声明。 | ||
- | DokuWiki 的默认模板会在 ''lib/tpl/default/'' 目录中根据特殊的名称来查找文件,并且在显示的时候会在正确的位置简单地包含它们。您可以添加任何您喜欢的 HTML 代码到这些文件中。当然,这只有在您使用 //default// 模板是时候才会有效。 | + | DokuWiki 的默认模板会在模板目录中根据特殊的名称来查找文件,并且在显示的时候会在正确的位置简单地包含它们。您可以添加任何您喜欢的 HTML 代码到这些文件中。当然,这只有在您使用 //default// 模板是时候才会有效。 |
+ | |||
+ | ===== 转换现存的模板 ===== | ||
+ | |||
+ | 如果你缺少设计技巧,你可以转换现存的模板。存在有很多的自由选项。如果你喜欢发布它们,请确保遵循协议 [[https://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses|GPL2-compatible]]. | ||
+ | |||
+ | * [[WP_to_DW_template|怎样将WordPress主题转换为 DokuWiki 模板。]] | ||
+ | |||
+ | =====避免问题===== | ||
+ | |||
+ | 以下是模板开发人员遇到的一些问题以及如何避免它们: | ||
+ | |||
+ | ===不要将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''页面。 | ||
- | __给 PHP 开发者的提示:__ 您可能会很高兴听到您甚至可以在这些文件中包含 PHP。 | + | 该页面应包含有关如何安装和使用模板的所有必需文档,添加屏幕截图也可能是一个好主意。 |
- | ==== 可用的 Hooks ==== | + | 在模板页面的顶部必须填入一些元数据字段。每个字段的说明可以在[[plugin:repository#template_entry|Repository Plugin]]页面找到。 |
- | 所有这些文件都可在 ''lib/tpl/default/'' 目录中被找到。 | + | 从Ponder Stibbon版本开始可以有自动更新信号。为使更新过程正常工作,模板wiki页面上的“上次更新日期”的日期必须等于源tarball /zip文件中的[[devel:template_info|template.info.txt]]文件中的日期。如果情况并非如此,更新将不会发生或会有持续的“更新”信号。 |
- | ^ 文件名 ^ 被包含在 HTML 中的位置 ^ | + | dokuwiki.org上不允许上传,因此您需要在其他地方托管您的模板文件。我们建议使用[[git]]等版本控制系统来管理您的源代码。如果你这样做,最简单的方法就是使用[[https://github.com | GitHub]]这样的公共库,它还会为你的仓库提供了一个bug跟踪器。 |
- | | ''meta.html'' | 在 <head> 标签中,用这个文件来增加额外的样式或者元数据 | | + | |
- | | ''topheader.html'' | 在页面的最顶端 <body> 标签之后 | | + | |
- | | ''header.html'' | 在页面上端的蓝色栏之上,在页面名称和 wiki 标题之下 | | + | |
- | | ''pageheader.html'' | 在 breadcrumbs 之下,在实际的内容之上 | | + | |
- | | ''pagefooter.html'' | 在页面下端的蓝色栏之上,在最后更改日期之下 | | + | |
- | | ''footer.html'' | 在页面的最下端 </body> 标签之前 | | + | |
- | DokuWiki 给出了一个 ''footer.html'' 的样例,包含了一些按钮和一份公共创作的许可证的 RDF 描述。 |