This page last changed on Nov 01, 2006 by mryall.

Confluence allows you to integrate your own stylesheets within the theme plugin so you can have greater control over the appearance of your site.

Step One: Defining the stylesheet in the atlassian-plugin.xml

To make a stylesheet available to a decorator, you will need to reference it as a resource from within the central configuration file - atlassian-plugin.xml.

Here is an example where a stylesheet is being used to define the 'leftnavigation' theme:

<layout key="main" name="Main Decorator" class="com.atlassian.confluence.themes.VelocityDecorator"
overrides="/decorators/main.vmd">
<resource type="velocity" name="decorator"
location="templates/leftnavigation/main.vmd"/>
<resource type="stylesheet" name="leftnav.css"
location="templates/leftnavigation/leftnav-css.vm">
</resource>
</layout>


The resource parameter takes three arguments:

  • Type: The type of resource-in this instance, 'stylesheet'.
  • Name: The name of the stylesheet.
  • Location: The location of the file represented in the jar archive you will use to bundle your theme.

Step Two: Using the stylesheet in the decorator

To reference the stylesheet in the decorator, you will need to use the #pluginStylesheet velocity macro.

For example, here's how you reference the leftnav.css file defined in the layout entry above:

#pluginStylesheet("com.atlassian.confluence.themes.leftnavigation:main" "leftnav.css")

The macro takes two arguments:

  • completePluginKey: The complete plugin key which is constructed from the pluginkey and the layout key like this: {pluginKey}:{layoutKey}
    In the above example, com.atlassian.confluence.themes.leftnavigation is the key of the plugin, and main is the key of the layout.
  • stylesheetName: the name of the stylesheet

If you place your stylesheet after the #standardHeader macro in the decorator, the contents of your custom stylesheet will override those in Confluence's default stylesheet.

If your stylesheet needs to reference the colour scheme, you need to use the space stylesheet macro instead:

#pluginSpaceStylesheet("com.atlassian.confluence.themes.leftnavigation:main" "leftnav.css" $spaceKey)

You can then use colour scheme references in your stylesheet, similar to Confluence's stylesheets, and they will be replaced with the appropriate global or space-specific colour scheme:

.navItemOver {
    color: $action.navSelectedTextColor;
}
RELATED TOPICS
Adding a theme icon (Confluence)
Applying a Theme (Confluence)
Creating a Theme (Confluence)
Including Cascading Stylesheets in Themes (Confluence)
Themes Overview (Confluence)

For some reason, after you upload a new theme as a plugin, you will have to restart Confluence (i.e. restart your app server) for any CSS changes to take effect. Other elements of the theme take effect immediately, but to see CSS changes you must restart (maybe because the template must be recompiled or remove from a server cache?).

Obviously this is can be extremely annoying when developing a new theme.

Posted by mattz at Sep 06, 2006 18:42

CSS stylesheets are processed by Velocity in Confluence in order to insert custom colours, styles, etc. Therefore, they are subject to the normal caching of Velocity files when they're first read.

To fix this, turn off Velocity caching during development.

Posted by mryall at Nov 01, 2006 18:00

This documentation is hard to understand, because it isn't clear which parts of the 'examples' are variable and which are fixed, and there are lots of parts of the example that are unexplained.

For example, must the 'class' name start with "com.atlassian.confluence.themes"?

Why would you not always use the Spacestylesheet?

Posted by masinter at Dec 22, 2006 23:37

Ideally you would package your classes in something like com.atlassian.confluence.themes.mytheme which is the convention confluence follows. Also, you may want to use your own stylesheet to have more control on the layout, style, appearance etc for the theme (essentially, which is what this document is for).

Posted by agnes@atlassian.com at Dec 28, 2006 23:25
Document generated by Confluence on Mar 22, 2007 20:54