This server will be upgraded at 3pm Sydney time on December 3rd (December 2nd, 8pm PST) and will be down for up to 30 minutes.
This documentation relates to the latest version of Confluence.
If you are using an earlier version, please go to the documentation home page and select the relevant version.

Creating a Theme Plugin

Added by Jonathan Nolen, last edited by David Peterson [CustomWare] on Jul 10, 2008  (view change) show comment
All Versions
Click for all versions
Confluence 2.10 Documentation

Index

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 ("/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.

Using Stylesheets

Stylesheets can be defined for a theme and they will automatically be included by Confluence when pages are displayed with your theme. You simply need to add a resource of type download to your theme module. Please note that the resource name must end with .css for it to be automatically included by Confluence.

<theme key="mytheme" .... >
   ...
   <resource type="download" name="my-theme.css" location="styles/my-theme.css"/>
   ...
</theme>

Now, in the HTML header of any page using your theme, a link tag to your theme stylesheets will be created by Confluence. If you have a look at the source of combined.css, it will contain imports to all your theme stylesheets. 

<html>
<head>
   ...
   <link type="text/css" href="/confluence/s/.../_/styles/combined.css?spaceKey=FOO" rel="stylesheet">
</head>

...

</html>

Theme stylesheets are included after all the default Confluence styles and colour schemes. This is to ensure that your theme styles can override and take precedence over the base styles provided by Confluence.

Using Colour Schemes

Users can customise their own colour scheme (regardless of the theme selected) for a particular space under Space Administration.

You may choose to respect these user configured colour schemes in your theme or ignore them completely by overriding them in your theme stylesheets. If you would like to respect the configured colour schemes for your new UI elements, you should specify a velocity stylesheet resource in your theme module. 

<theme key="mytheme" .... >
   ...
   <resource type="download" name="my-theme-colors.vm" location="templates/clickr/my-theme-colors.vm"/>
   ...
</theme>

Please note that the resource name must end with .vm for it to be automatically rendered as a velocity template by Confluence. This velocity stylesheet will essentially contain css for colours with references to the colour scheme bean (which is available to you via the action). For example:

\#breadcrumbs a {
    color: $action.colorScheme.linkColor;
}
#myNewElement {
    color: $action.colorScheme.headingTextColor;
}
.myNewElementClass {
    border-color: $action.colorScheme.borderColor;
}
...
As the velocity stylesheet is rendered as a velocity template, you will need to escape any #ids (e.g. breadcrumbs) that match velocity macro names.

Additionally, you may choose to provide your theme with a pre-defined colour scheme (which users will be able to select under Space Administration). This pre-defined colour scheme will take precedence if no custom user one is defined for the space. To define a theme's colour scheme, you need to add a colour scheme module and link to it in the theme module. For example:

<theme key="mytheme" .... >
   ...
   <colour-scheme key="com.atlassian.confluence.themes.mytheme:earth-colours"/>
   ... 
</theme>

...

<colour-scheme key="earth-colours" name="Brown and Red Earth Colours" class="com.atlassian.confluence.themes.BaseColourScheme">
     <colour key="property.style.topbarcolour" value="#440000"/>
     <colour key="property.style.spacenamecolour" value="#999999"/>
     <colour key="property.style.headingtextcolour" value="#663300"/>
     <colour key="property.style.linkcolour" value="#663300"/>
     <colour key="property.style.bordercolour" value="#440000"/>
     <colour key="property.style.navbgcolour" value="#663300"/>
     <colour key="property.style.navtextcolour" value="#ffffff"/>
     <colour key="property.style.navselectedbgcolour" value="#440000"/>
     <colour key="property.style.navselectedtextcolour" 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 under Space Administration > Colour Scheme:

Key Description Default value
property.style.topbarcolour The strip across the top of the page #003366
property.style.breadcrumbstextcolour The breadcrumbs text in the top bar of the page #ffffff
property.style.spacenamecolour The text of the current space name, or Confluence in the top left #999999
property.style.headingtextcolour All heading tags throughout the site #003366
property.style.linkcolour All links throughout the site #003366
property.style.bordercolour Table borders and dividing lines #3c78b5
property.style.navbgcolour Background of tab navigation buttons #3c78b5
property.style.navtextcolour Text of tab navigational buttons #ffffff
property.style.navselectedbgcolour Background of tab navigation buttons when selected or hovered #003366
property.style.navselectedtextcolour Text of tab navigation buttons when selected or hovered #ffffff
property.style.topbarmenuselectedbgcolour Background of top bar menu when selected or hovered #336699
property.style.topbarmenuitemtextcolour Text of menu items in the top bar menu #003366
property.style.menuselectedbgcolour Background of page menu when selected or hovered #6699cc
property.style.menuitemtextcolour Text of menu items in the page menu #535353
property.style.menuitemselectedbgcolour Background of menu items when selected or hovered #6699cc
property.style.menuitemselectedtextcolour Text of menu items when selected or hovered #ffffff

Labels

customising-looknfeel customising-looknfeel Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (7)

 

  1. Feb 20, 2007

    Chris Cohen says:

    There seems to be an element missing between "topbar" and "spacename"... the col...

    There seems to be an element missing between "topbar" and "spacename"... the colour of the breadcrumbs text. This can be chosen in the custom colour interface, in the Space Admin section, but it apparently can't be set in the <colour-scheme> element in the XML. Since your screenshot doesn't have the "Breadcrumbs Text" colour selector, I assume that this documentation is out of date. Please let me know how I can change the colour of the breadcrumbs text in the XML. Thanks.

    1. Mar 30, 2008

      Ed Letifov says:

      I am not sure if this is still relevant, but this is what I had to do in my them...

      I am not sure if this is still relevant, but this is what I had to do in my theme:

          <colour-scheme key="techtime-colours" name="TechTime Colours"
                   class="com.atlassian.confluence.themes.BaseColourScheme">
        <colour key="property.style.topbarcolour" value="#336699"/>
        <colour key="property.style.breadcrumbstextcolour" value="#FFFFFF"/>
        <colour key="property.style.spacenamecolour" value="#ffcc00"/>
        <colour key="property.style.headingtextcolour" value="#000000"/>
        <colour key="property.style.linkcolour" value="#000000"/>
        <colour key="property.style.bordercolour" value="#336699"/>
        <colour key="property.style.navbgcolour" value="#ff9922"/>
        <colour key="property.style.navtextcolour" value="#000000"/>
        <colour key="property.style.navselectedbgcolour" value="#ff6600"/>
        <colour key="property.style.navselectedtextcolour" value="#000000"/>
        <colour key="property.style.customcolour1" value="#ff6600"/>
        <colour key="property.style.customcolour2" value="#ff9922"/>
        <colour key="property.style.customcolour3" value="#ffcc00"/>
        <colour key="property.style.customcolour4" value="#ffffff"/>
        <colour key="property.style.customcolour5" value="#000000"/>
    </colour-scheme>

  2. May 08, 2008

    Stefano Linguerri says:

    I started my own theme from "clickr" bundled with confluence. I'm modifing the&...

    I started my own theme from "clickr" bundled with confluence.

    I'm modifing the  main.vmd, from this template I can't access the $helper.spaceKey() and simply print out "$helper.spaceKey()".

    #set ($username = $sitemeshPage.getProperty("page.username")) also this doesn't work.

    1. Jul 02

      Chris Worth says:

      I ran into the same problem. I was able to retrieve the spaceKey by using - $...

      I ran into the same problem. I was able to retrieve the spaceKey by using -

      $helper.page.spaceKey

  3. Nov 18

    Peter R. says:

    Ok, maybe I'm missing it (probably am) but can someone tell me how to do this: ...

    Ok, maybe I'm missing it (probably am) but can someone tell me how to do this:

    • Pull out the files uses to create the default v2.9.2 theme
    • Edit the files to do two things:
      • Rename the theme to a different name
      • Change the text of the footer
    • Package it (or whatever) so that it can be put into Confluence as an additional theme, not as a replacement to the existing v2.9.2 default theme

    It seems like it'd be straightforward but I'm stumbling around like a blind man on a roller coaster at the moment.

    Problem Statement - create three themes, all based on v2.9.2 but each having a different footer to meet compliance requirements. Have all three available in the system. (and it would be nice if I could somehow disable the ability of the Space Admins to change said themes!)

    Thank you.

    Peter

    1. Nov 20

      Peter R. says:

      Anyone?

      Anyone?

    2. about 10 hours ago

      Arie Murdianto says:

      Hi, If you want to create a theme plugin, you may want to use the existing them...

      Hi,

      If you want to create a theme plugin, you may want to use the existing theme plugins (left navigation, Clickr) as a template. Extract the jar file and then customize the vmd files as you wish. The vmd files that you have just edited will override the existing/default vmd files in Confluence if you select your own theme in your Confluence instance.

      I would suggest you learn/explore more on left navigation theme plugin ( As Confluence is using sitemesh and velocity to render a page, you need to have a knowledge about them). The following links should be helpful for you:

      I hope, it is helpful.

      Cheers,

Add Comment