This page last changed on Mar 28, 2006 by mryall.

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 "Site Decorators" section of the site 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. 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.

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 Decorator Macros

If Something Goes Terribly Wrong

From the "Site Decorators" 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:

  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.

I'd like to add some links to pages in the spaces to the main,

is there a macro (#pagelink(space:page) to do this without pasting in the full link (http:.../confluence/.../)?

Posted by at Jan 30, 2004 01:15
## custom link into space decorator
#parse ("/decorators/includes/header.vmd")

<div id="Content">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
		<tr> <!-- adl navbar -->
			<td colspan="2">
 <table align="right" border=0 cellspacing=1 cellpadding=2 bgcolor="ffffff">
                <tr>
##macro(navitem $title $url $selected $tooltip $accessKey)
#navitem ("<u>A</u>DL WORK" "$req.contextPath/display/Brainstorm/Home" "/display/Brainstorm/Home" "Go to the ADL Workspace" "a")
#navitem ("<u>P</u>eople" "$req.contextPath/display/Brainstorm/People" "/display/Brainstorm/People" "Go to the ADL People" "a")
#navitem ("Pro<u>j</u>ects" "$req.contextPath/display/Brainstorm/ADL%2BProjects" "/display/Brainstorm/ADL%2BProjects" "Go to the ADL Projects" "j")
#navitem ("<u>M</u>eetings" "$req.contextPath/display/Meetings/Home" "/display/Meetings/Home" "Go to the ADL Meetings" "m")
#navitem ("<u>D</u>ocuments" "$req.contextPath/display/Brainstorm/Documentation%2BEfforts" "/display/Brainstorm/Documentation%2BEfforts" "Go to the ADL Dcouments" "d")
#navitem ("UCSB <u>L</u>ibrary Work" "$req.contextPath/display/LibraryWebsiteAdmin/Home" "/display/LibraryWebsiteAdmin/Home" "Go to the Library Web Admin" "l")
	#navitem ("ADL Project" "http://www.alexandria.ucsb.edu/" "Home" "Go to the ADL Project" "r")
#navitem ("UCSB Library" "http://www.library.ucsb.edu/" "Home" "Go to the Library Web" "u")

			</tr>
			</table>
		</td>

		</tr>
        <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>

    <div width="100%" class="breadcrumbs">
        <table width=100% cellspacing=0 cellpadding=0 border=0><tr>
            <td>
            &nbsp;#breadcrumbs()
            </td>
            #searchbox()
        </tr></table>
    </div>

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

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

        #if ($page.getProperty("page.surtitle"))
            <div class="surtitle">
                $page.getProperty("page.surtitle")
            </div>
        #end

        <div class="pageheader">
            <span class="pagetitle">$title</span>
        </div>

        $body
    </td>

#parse ("/decorators/includes/complete_footer.vmd")
Posted by valentinedwv at Feb 05, 2004 13:17

This page, I mean this URL: "http://confluence.atlassian.com/display/DOC/Custom+Decorator+Templates" is buggy.
For some reason it asks for my screen resolution and renders teh HTML in a super wide screen. (Page references and Hot REfferers are outside of my screen, 1024x1280)

The other pages on Confluence here worked fine.

Angelo

Posted by angelo.schneider@oomentor.de at Oct 27, 2004 18:52

The page is wide is because someone posed a extra wide comment with a code example.

Posted by at Mar 25, 2005 00:41

Is there a way to replace the confluence_logo.gif and the logo2.gif that you see at the top left of the pages with our companies logo? I understand how to add our logo, but that only adds it to the middle of the pages, next to the Confluence one. Thanks.

Posted by muddp@nationwide.com at May 03, 2005 09:18

I want to add a space-wide footer feature.

As far as I can see, in order to have it close to the other page content (i.e., user-submitted content), it has to be within the $body aggregation. That is, if you place anything anywhere else, it appears either well above the content, or well below it (after the comments widget etc.).

Is there a satisfactory way of editing how the $body content is rendered?

Posted by snike at May 16, 2005 23:08

We are looking at possibly buying Confluence with an unlimited user license and source code access. From poking around here, I understand you can customize the look and feel of confluence using SItemesh and Velocity and Velocity is a scripting language that access the methods of Java objects.

What I am wondering about is the ability to integrate with an outside system and customize behavoir not just appearance from within Confluence. Say if I had an article about something on one of my data driven web pages and I wanted to give the user the ability to create a wikie type article or post comments using confluence about that article. I would want the use to hit a button or link on my page, and provide them with a customized empty Confluence page with possibly a cutom title and header to write\upload their content. Will I be able customize or create Java objects within Confluence to handle this?

I know there will be issues regarding upgrading and service packs etc...

Posted by at Sep 09, 2005 09:38

Hi,

I'm not to 100% certain what you are trying to achieve, but it sounds like that the Remote API would do what you are looking for. The remote API will allow you to keep the interface to enter the data on your page and then create a page in Confluence on submission.

You could also modify the templates and link to Confluence directly. Writing themes you will be able to write your own java objects to handle certain tasks, but from what I understand, that would not be necessary.

If you have further questions please send us an email to:
confluence-support@atlassian.com

Cheers,
Jens

Posted by jens@atlassian.com at Sep 12, 2005 02:39

Hi,

I just want to change the color of the text of the usernavbar but I dont find how to do that. I tried to modify the main decorator by adding
<span style="color: red">
                        #usernavbar()
</span>

But that doesn't work...
How can I do that ?

Thanks

Barth

Posted by eco81 at Oct 25, 2005 07:41

The best way to change usernavbar colour is via the "Administration Console | Look and Feel | Colour Schemes". This allows you to configure the user nav bar among other things.

Alternatively, you would need to update the Confluence CSS file that is used to control the colours.

Regards,
-Daniel

Posted by daniel@atlassian.com at Oct 25, 2005 18:27
Document generated by Confluence on Mar 22, 2007 20:54