The Theme Plugin Module
The theme module defines the theme itself. When someone in Confluence selects a theme either globally or within a space, they are selecting from the available theme modules.
The class of a theme must implement com.atlassian.confluence.themes.Theme. The com.atlassian.confluence.themes.BasicTheme class provided with Confluence gathers together all the resources listed within the module definition into a theme.
A theme can contain an optional colour-scheme element that defines which colour-scheme module this theme will use, and any number of layout elements that define which layouts should be applied in this theme. Refer to these modules by their module complete key.
It is possible for a theme to use modules that aren't in the same plugin as the theme. Just keep in mind that your theme will be messed up if some plugin that the theme depends on is removed.
Installing the Theme
Themes are installed as 'plugin modules'. The plugin module is a collection of files, usually zipped up in a jar archive, which tells Confluence how to find the decorators and colour-scheme of your theme.
Plugins are a general topic in Confluence and have other uses than themes. In every case, the central configuration file, which describes the plugin to Confluence, is named atlassian-plugin.xml .
There are two steps to creating the plugin module.
- Create the central configuration file for the theme: atlassian-plugin.xml
- Create the jar archive for your theme: bundling your theme
Writing the atlassian-plugin.xml file for your theme.
The structure of an atlassian-plugin.xml file is fairly self-explanatory. In the code segment below you will find a full example of an atlassian-plugin.xml, which lists
- each of the decorators you have defined to customize Confluence
- your colour scheme
in a way which Confluence can use to override the default theme. In other words, this XML tells Confluence to look in certain locations for replacement decorators when processing a request.
The class which each decorator, or layout, is mapped to must implement com.atlassian.confluence.themes.VelocityDecorator.
The layout entry must provide an overrides attribute which defines which decorator within Confluence is being overrridden by the theme.
Importantly, when telling Confluence to override a particular decorator with another one, the location of the custom decorator is specified; for example:
The location attribute needs to be represented in the jar archive you will use to bundle your theme.
Bundling the Theme
Your decorators should be placed in a directory hierarchy which makes sense to you. The atlassian-plugin.xml file should be placed at the top level of the directory structure, afterwards the decorators should be placed in directories which make a meaningful division of what they do. It is your choice as to how the structure is laid out, each decorator could even be placed alongside atlassian-plugin.xml . The essential thing is for the location attribute of each decorator to accurately tell Confluence how to load it.
Thus, a recursive directory listing of the example theme above gives:
Labels
