This page last changed on Aug 01, 2007 by mjensen.

Using Decorators

A decorator defines Confluence page layout. By modifying a decorator file, you can move "Attachments' tab from the left of the screen to the right or remove it completely. Decorator files are written in the Velocity templating language and have the VMD extension. You can familiarise yourself with Velocity at the Velocity Template Overview and decorators in general at the Sitemesh homepage.

Decorators, Contexts and Modes

Confluence comes bundled with a set of decorator files that you can customize. Instead of having one decorator file for each screen, we've grouped together similar screens (example: view and edit page screens) to simplfy editing layouts.

There is some terminology that we use when talking about decorators that should be defined. We've grouped all the screens in Confluence into major categories which we call contexts. Within each context are various modes (ways of viewing that particular layout).

The following table summarises how decorators use contexts and modes:

Decorator Context Mode Comment
page.vmd page 'view', 'edit', 'edit-preview', 'view-information', and 'view-attachments'  
blogpost.vmd blogpost (news) 'view', 'edit', 'edit-preview', and 'remove' We prefer to use 'news' as an end-user term; all templates and classes use 'blogpost' to indicate RSS related content
mail.vmd mail 'view', 'view-thread' and 'remove'  
global.vmd global 'dashboard', 'view-profile', 'edit-profile', 'change-password-profile', 'edit-notifications-profile'  
main.vmd n/a (header and footer formatting)   main.vmd is used to control the header and footer of each page, not the page specific presentation logic
space.vmd space-pages list-alphabetically, list-recently-updated, list-content-tree, create-page space.vmd handles a wide range of options, this context is accessed by clicking on 'browse space' in the default theme of Confluence (tabbed theme)
  space-mails view-mail-archive  
  space-blogposts view-blogposts, create-blogpost  
  space-templates view-templates  
  space-operations view-space-operations"  
  space-administration view-space-administration, list-permission-pages  

Example

As an example on how to use the table above, say we found the 'Attachments' tab on the view page screen annoying and wanted to remove it. We could make this layout change in the page.vmd file - where the 'view' mode is handled (as shown below).

#*
     Display page based on mode: currently 'view', 'edit', 'preview-edit', 'info' and 'attachments.
     See the individual page templates (viewpage.vm, editpage.vm, etc.) for the setting of the mode parameter.
   *#
   ## VIEW
   #if ($mode == "view")
                      
       <make layout modifications here>

   #elseif ...
When creating your own decorators, it is critical that you preserve the lines #parse ("/pages/page-breadcrumbs.vm") or #parse ("/pages/space-breadcrumbs.vm"). These include files pass important information about the space to other space decorators and hence must be included.

The Theme Helper Object

When editing decorator files you will come across a variable called $helper - this is the theme helper object.

The following table summarises what this object can do:

Behaviour Explanation
$helper.domainName displays the base URL of your Confluence instance on your page. This is useful for constructing links to your own Confluence pages.
$helper.spaceKey() returns the current space key or null if in a global context.
$helper.spaceName returns the name of the current space
$helper.renderConfluenceMacro("{create-space-button}") renders a call to a [Confluence Macro] for the velocity context
$helper.getText("key.key1") looks up a key in a properties file matching key.key1=A piece of text and returns the matching value ("A piece of text")
$helper.action returns the XWork action which processed the request for the current page.

If you are on a page or space screen you also have access to the actual page and space object by using $helper.page and $helper.space respectively.

If you want to delve more into what other methods are available in this object, please see our API's for ThemeHelper.

Velocity macros

Finally, the last thing you need to decipher decorator files is an understanding of macros. A velocity macro looks like this:

#myVelocityMacro()

In essence, each macro embodies a block of code. We've used these macros to simplify decorator files and make them easier to modify.

For example, the #editPageLink() macro will render the edit page link you see on the 'View Page Screen'. All the logic which checks whether a certain user has permissions to edit pages and hence see the link are hidden in this macro. As the theme writer, you need only care about calling it.

The easiest way to acquaint yourself with the macros is to browse through your macros.vm file, located in /template/includes/macros.vm (under the base Confluence installation).

Writing your own Velocity Macros

Velocity macros are very useful for abstracting out common presentation logic into a function call and for keeping decorators clean. If you wish to use them for your theme you can either:

Write your own Macros file

Write your own Velocity macros library file, as we've done with macros.vm. If you elect to do this you must locate the velocity.properties file beneath WEB-INF/classes and tell the Velocity engine where your library file can be located, relative to the base installation of Confluence.

velocimacro.library = template/includes/macros.vm
Use Inline Velcoty Macros.

Inline velocity macros, when loaded once, can be called from anywhere. See decorators/mail.vmd for examples of inline decorators.

The Colour Scheme Module

Colour schemes can be pre-configured for your theme. It is possible to configure them dynamically, in Space Administration, within an existing space.

To transport them within a theme, however, they need to be expressed in an XML document. Here the structure of the colour-scheme element which you will use to arrange your palette of colours.

<colour-scheme key="earth-colours" name="Brown and Red Earth Colours"
                class="com.atlassian.confluence.themes.BaseColourScheme">
     <colour key="topbar" value="#440000"/>
     <colour key="spacename" value="#999999"/>
     <colour key="headingtext" value="#663300"/>
     <colour key="link" value="#663300"/>
     <colour key="border" value="#440000"/>
     <colour key="navbg" value="#663300"/>
     <colour key="navtext" value="#ffffff"/>
     <colour key="navselectedbg" value="#440000"/>
     <colour key="navselectedtext" value="#ffffff"/>
</colour-scheme>

The class of a colour scheme must implement com.atlassian.confluence.themes.ColourScheme. The com.atlassian.confluence.themes.BaseColourScheme class provided with Confluence sets the colours based on the module's configuration.

The available colours correspond to those that you would configure in the online colour-scheme editing, and are:

Key Description
topbar The strip across the top of the page
spacename The text of the current space name, or Confluence in the top left
headingtext All heading tags throughout the site
link All links throughout the site
border Table borders and dividing lines
navbg Background of top navigational buttons
navtext Text of top navigational buttons
navselectedbg Background of navigational buttons when selected or hovered
navselectedtext Text of navigational buttons when selected or hovered

Document generated by Confluence on Dec 20, 2007 19:02