Confluence Docs 3.0 : Modifying Look and Feel (for themes) This page last changed on May 15, 2008 by edawson. Here's how you can define a new look and feel for Confluence in your theme: Layout : Edit Confluence's layout by modifying the decorator files that are used to define it. Working with Decorators Velocity Template Overview Configuring the atlassian.plugin.xml file to reference the decorators Colour schemes : Configure a new colour scheme for your theme. Optional Configuring a new colour scheme Configuring the atlassian.plugin.xml file to include the new colour scheme Stylesheet : Include a stylesheet to define your theme. Optional Note that for every component you edit, you will need to configure the `atlassian-plugin.xml` which is the central configuration file for the plugin to override the default files with the new files you've created. ## Layout: Working with decorators What are decorators? Confluence is built on top of the Open Source SiteMesh library, a web-page layout system. To edit the layout of Confluence, you will need to modify these decorator files. A decorator file is a '.vmd' file and is written in a very simple programming language called Velocity. Learn more about Velocity. Confluence comes bundled with a set of decorator or VMD files that you can customize. Broadly these are categorised into Site, Content and Export decorators. These are further grouped into categories called contexts and under each context has various modes (ways of viewing the context). To make editing easier, layout for similar screens (example: view and edit page screens) is configured through the same VMD file. So, if you want to customize how the Confluence View Page Screen or Edit Page Screen looks, you can make both of these changes inside one decorator file: page.vmd.
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' |
space.vmd | space-pages, space-mails, space-blogposts, space-templates, space-operations, space-administration | CONTEXT: "space-pages". MODES: "list-alphabetically", "list-recently-updated", "list-content-tree", "create-page". CONTEXT: "space-mail". MODES: "view-mail-archive". CONTEXT: "space-blogposts". MODES: "view-blogposts", "create-blogpost". CONTEXT: "space-templates". MODES: "view-templates". CONTEXT: "space-operations". MODES: "view-space-operations". CONTEXT: "space-administration". MODES: "view-space-administration", "list-permission-pages". | 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)
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
For example, if you wanted to remove the 'Attachments' tab on the view page screen, you would 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 ...
### Step One: Copying the decorators The easiest way to begin configuring a new layout is by copying the default decorator files and editing them to suit your theme. Go to the Confluence 'Administration Console'. To do this: Open the 'Browse' menu and select 'Confluence Admin'. The 'Administration Console' view will open. Select Layouts in the left panel. This will display options to view and edit the default decorators. Copy the files that you intend to modify and place them in a directory structure that makes sense to you. See example below. ### Step Two: Creating a directory structure for the decorators: You should place your decorators in a directory hierarchy which makes sense to you. We recommend that you place the atlassian-plugin.xml file at the top level of the directory structure, and then place the decorators in directories which make a meaningful division of what they do. Here is an example:
    atlassian-plugin.xml
    com/atlassian/confluence/themes/mytheme/
    com/atlassian/confluence/themes/mytheme/global.vmd
    com/atlassian/confluence/themes/mytheme/space.vmd
    com/atlassian/confluence/themes/mytheme/mail.vmd
    com/atlassian/confluence/themes/mytheme/blogpost.vmd
    com/atlassian/confluence/themes/mytheme/main.vmd
    com/atlassian/confluence/themes/mytheme/page.vmd
### Step Three: Editing the decorators To edit the decorators, you will require knowledge of a very simple programming language called Velocity. Learn more about Velocity. Decorator Macros When editing the decorators, you will need to use Decorator Macros to draw complex or variable parts of the page such as menus and breadcrumbs. See Working With Decorator Macros Theme Helper Object When editing decorator files you will also 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 deliver more into what other methods are available in this object, please see our API's for ThemeHelper. ### Step Four: Configuring the central configuration file to reference the new decorators How to do this is explained in Configuring the theme plugin ## Working with colour schemes for themes ### Configuring the colour scheme The easiest way to configure a colour scheme is to do it dynamically from the Administration Console (as you would normally when you want to change the site's colour scheme online), and then express it as an xml file. This method makes it possible for you to experiment with different colours and test them out before including the colour scheme in your theme. Go to the Confluence 'Administration Console'. To do this: Open the 'Browse' menu and select 'Confluence Admin'. The 'Administration Console' view will open. Select 'Colour scheme' in the left panel. Use the colour picker to define the colours for the following UI elements: Top Bar - the bar across the top of the page that contains the breadcrumbs. Space Name Text - the text of the current space name located above the page title. Heading Text - all heading tags throughout the space. Links - all links throughout the space. Borders and Dividers - table borders and dividing lines. Menu Bar Background - background of top navigational buttons Menu Bar Text - text that appears on the menu bar Menu Bar Background Highlight - background colour of menu bar when highlighted. Menu Bar Text Highlight - menu bar text when highlighted More information on customising colour schemes ### Expressing the colour scheme as XML Once, you have decided on the colours for the different UI elements, you will need to configure the atlassian.plugin.xml to include the new colour scheme. How to do this is explained in detail in Configuring the theme plugin. ##### RELATED TOPICS
Adding a theme icon
Including Cascading Stylesheets in Themes
Applying A Theme To A Space
Themes Overview
Applying a Theme To A Site
Creating a Theme

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