Skip to end of metadata
Go to start of metadata

中文标题【自定义 Decorator 模板】


关于 Decorators

Confluence 是使用开源的 SiteMesh 库构建的。一个 Web 页面的布局系统,这个布局系统能够在全站点中提供完整统一的界面和外观。SiteMesh 是通过 "decorators" 工作的,这个文件定义了页面的布局和结构,同时指定了页面特定的内容将会如何进行布局。如果你有兴趣的话,你可以阅读有关SiteMesh 的文档。

在你对 Confluence 的界面和外观进行编辑的时候将会意味着什么呢:

  • "Main" decorator 定义了页面的头部和页面的脚部
  • "Page" decorator 定义了页面是如何显示的
  • "Printable" decorator 定义了页面打印版本中的界面和外观。

你可以在 Confluence 中查看和编辑这些 decorator 文件。修改这些 decorator  文件将会对 Confluence 的所有空间产生影响,这个修改是全局的。

使用 decorator 来创建 Confluence 的管理员界面的是不能进行修改的。这样设置的原因是为了避免你对 decorator 文件可能的错误修改会导致整个 Confluence 站点不可用,管理员应该还需要有特定的界面可用将修改错误的 decorator 文件复原。

浏览默认的 Decorators

在任何时候,你都可以使用 "Site Layouts" 页面中的 "View Default" 来浏览默认的 decorator  文件。模板浏览器允许你查看使用 "#parsed" 包含在模板文件中的其他模板。当你不能对嵌入的模板进行编辑的时候,你可能需要拷贝部分或者全部的嵌入模板到你的自定义模板中。

编辑自定义 Decorators

希望对 Confluence 的 decorator 进行编辑的话,你需要具有良好的 HTML 知识和能够理解  Velocity 模板语言

希望编辑 decorator 文件:

  1. 进入  Confluence 管理(Confluence Admin > 布局(Layouts).
  2. 在你希望进行编辑的 decorator  文件边上选择 创建自定义(Create Custom)
  3. 保存你的修改。

如果你创建了错误的修改,你可以选择 decorator 编辑过的选项,选择 重置默认(Reset Default)来恢复默认配置。

可选的,自定义的模板文件应该存储在数据库中的 DECORATOR  表中。如果你有时候你的修改导致你的 Confluence 完全不可用了,你可以删除 DECORATOR  表中的相关记录。

页面的某些部分使用的是 Velocity  宏进行创建的,包括导航栏。有关宏的创建,你可以参考页面 Working With Decorator Macros 页面中的内容。

针对高级用户

velocity 目录是 Confluence 首先进行模板搜索的查找路径。你可以对 Confluence 的 velocity 的模板文件进行重载。前提是你需要将文件放置到正确的位置。

当然,我们并不建议你这样做,因为这样能够让你对 Confluence 的界面和外观有完全的操作,这个操作将会可能导致整个页面布局的损坏。你可以使用文本编辑器对这些模板文件进行编辑,你不能使用浏览器进行编辑。

对上面的模板文件进行编辑的时候,有下面 2 个注意事项:

  1. Velocity 被配置使用内存进行缓存。当你在 Confluence 中直接进行修改的时候,Confluence 将会指导从磁盘中重新载入修改的模板文件。如果你直接在磁盘上进行修改的话,Confluence 不知道如何载入并刷新缓存 WEB-INF/classes/velocity.properties 中定义的缓存或者重新启动 Confluence。
  2. 修改可能对后续的 Confluence 并不兼容。当你对 Confluence 的模板文件进行了修改后,你应该在后续 Confluence 的升级过程中对修改过的模板进行校验。否则有可能会导致页面损坏。


  • No labels