Modifying Look and Feel (for themes)

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.
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 'Administrator Access' login screen will be displayed.
- Enter your password and click 'Confirm'. You will be temporarily logged into a secure session to access the 'Administration Console'.
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 'Administrator Access' login screen will be displayed.
- Enter your password and click 'Confirm'. You will be temporarily logged into a secure session to access the 'Administration Console'.
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.

Page tree