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 on the SiteMesh website.

What this means for Confluence is that you can customise the look and feel of almost all of your Confluence site through editing three decorators:

  • The "Main" decorator defines the look and feel of most pages on the site
  • The "Popup" decorator defines the look and feel of the popup windows such as the "Insert Link" and "History" pages.
  • The "Printable" decorator defines the look and feel of the printable versions of pages (available through the icon on each page)

You can view and edit these decorators from within Confluence: they are available from the "Layouts" option on the site's Administration menu. Changes to the decorators will affect all spaces hosted on that Confluence installation.

The decorator that is used to draw Confluence's administrative pages can not be edited from within Confluence. This means that if you make some editing 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 customisation.

Editing Custom Decorators: Add a Logo

To edit Confluence decorators, you should have a good knowledge of HTML, and some understanding of the Velocity templating language.

The first thing you will see when you choose to create a custom "Main" decorator is... there's not much to edit. By default, most of the content of this decorator is included from other files:

<html>
<head>
     <title>$title - Confluence</title>

     #standardHeader()
</head>
<body onload="placeFocus()">

<div id="Content">
     <table border="0" cellpadding="0" cellspacing="0" width="100%">
         <tr>
             <td width="60%" rowspan=2 class="logocell">#pagetitle("spacenametitle")</td>

             <td width="40%" align="right" valign="top">#globalnavbar("table")</td>
         </tr>
         #if ($setup.isSetupComplete())
         <tr>
             <td align=right valign="bottom">
                 #usernavbar()
                 #printableicon()
                 #helpicon()
             </td>
         </tr>
         #end
     </table>

     #breadcrumbsAndSearch()

     <table border="0" cellpadding="5" cellspacing="0" width="100%"><tr><td>
<table border="0" cellpadding="0" cellspacing="0" width="100%"><tr>

     <td valign="top" class="pagebody">
## The "toolbar-style" page operations
## #if ($page.getProperty("page.operations"))
## <table align="right" class="toolbar"><tr><td>
## $page.getProperty("page.operations")
## </td></tr></table>
## #end

         #if ($page.getProperty("page.surtitle"))
             $page.getProperty("page.surtitle")
         #end

         #if (!$page.getProperty("page.no-page-header"))
             <div class="pageheader">
                 <span class="pagetitle">$title</span>
             </div>
         #end

         $body
     </td>

#parse ("/decorators/includes/complete_footer.vmd")

We can add our logo, changing the "logocell" table cell:

<td width="60%" rowspan=2 class="logocell">
<img align="right" 
src=http://www.atlassian.com/images/atlassian_logo.gif 
width="203" height="60">#pagetitle("spacenametitle")</td>

When you insert this into the right section of the template and hit save, visitors to the site will see the logo at the top of each page. Note, the administrative pages will be unaffected: you will have to go to the dashboard or to a space to see the changes you have made.

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.

If Something Goes Terribly Wrong

From the "Site Layouts" page in Confluence's administrative menu, you can delete your custom templates. When you do this, the default template will be restored, fixing anything that may have been broken.

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.

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 unless you know exactly what you're doing, 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 the web interface.

There are, however, two important caveats:

  1. 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.
  2. Because we only officially support the modification of the three global decorator files, other 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.