Custom Decorator Templates
About Decorators
Confluence is built on top of the Open Source SiteMesh library, a web-page layout system that provides a consistent look and feel across a site. SiteMesh works through "decorators" that define a page's layout and structure, and into which the specific content of the page is placed. If you are interested, you can read more in the SiteMesh documentation.
What this means for Confluence is that you can customize the look and feel of parts of your Confluence site through editing decorators, for example:
- The "Main" decorator defines the generic header and footer
- The "Page" decorator defines how a page is displayed
- The "Printable" decorator defines the look and feel of the printable versions of pages.
You can view and edit these decorators from within Confluence. Changes to the decorators will affect all spaces in that Confluence installation.
The decorator that is used to draw Confluence's administrative pages cannot be edited from within Confluence. This means that if you make a mistake that renders the rest of the site unuseable, the administrative pages should still be available for you to fix the template.
Browsing the Default Decorators
At any time, you can browse the default decorators that come packaged with Confluence by following the "View Default" links on the "Site Layouts" page. The template browser also allows you to view the "#parsed" templates that are included within the template when it is compiled. While you can't edit these included templates, you will probably have to copy some or all of them into your custom template as you do your customization.
Editing Custom Decorators
To edit Confluence decorators you will need a good knowledge of HTML, and some understanding of the Velocity templating language.
To edit a decorator:
- Go to Confluence Admin > Layouts.
- Choose Create Custom beside the decorator you wish to edit.
- Save your changes.
If you make a mistake or want to undo your changes, choose Reset Default beside the edited decorator.
Alternatively, the custom templates are stored in the DECORATOR table in the database. If you have somehow managed to render Confluence completely unuseable through editing your templates, delete the relevant entries from the DECORATOR table.
Macros
Some parts of the page are drawn using Velocity macros, including the navigation bar. The macros you should know about when editing decorators are described in Working With Decorator Macros.
For Advanced Users
The velocity directory is at the front of Confluence's velocity template search path. As such, you can override any of Confluence's velocity templates by placing an identically named file in the right place.
While we don't recommend you do this, it does give you complete control over the look of every aspect of Confluence. It also means that you can edit your templates in a text-editor if you wish, rather than through your browser.
There are, however, two important caveats:
- Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off velocity's caching temporarily in
WEB-INF/classes/velocity.properties, or restart the server to make your changes visible. - Changes may interact unpredictably with future versions of Confluence. When upgrading, you should always test your custom modifications thoroughly before deploying them on a live site.