Confluence Docs 3.0 : Custom Decorator Templates This page last changed on Jun 30, 2009 by ggaskell. ### 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 Cannot resolve external resource into attachment. 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 inside the `confluence.home` directory you defined in `confluence-init.properties` when installing Confluence. If you have somehow managed to render Confluence completely unuseable through editing your templates, simply delete the `confluence.home/velocity` directory, and restart Confluence. The default templates will be restored. WARNING: Only delete the `velocity` directory! Changing anything else inside your `confluence.home` is dangerous, and you could lose important data! ### 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: 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. 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.

Document generated by Confluence on Nov 05, 2009 23:27