Documentation

Theme

Themes change the appearance of screens in Confluence, like page content, the dashboard, and the search view. Themed screens look different but retain their Confluence URL, so existing links work as normal. To find out more about themes from a user’s perspective, check out the documentation on themes in our Confluence admin guide.

Key Concepts

Let’s define some key terms and concepts related to themes. We’ll use these names to refer to the concepts throughout this guide.
Name Description
Theme A theme is a module that allows the add-on to customize the view on a Confluence route. The theme is responsible for creating the entire user interface for that route.
Route A route is a URL that Confluence owns. For example, the "spaceview" route refers to the screen that displays the space home page. Themes override the rendering aspect of a route in order to display a customized view for that route. Routes are referred to by name, aren’t specific to a particular URL. The structure of a URL for a particular route isn't an API. Currently, the space view is the only route supported, and it takes a space key to identify the space.

Creating a theme

To create a theme for Confluence, you need to create a theme module descriptor (as described in this guide). You also need to create the HTML/CSS/Javascript for the theme – you can make use of the Confluence Web Components Library if you like – which will be served to the user via an iframe.

A theme module descriptor contains a set of routes to override. The URL belonging to the route definition property will be rendered as a full page iframe – similar to a general page module – without the Confluence header.

The URL supplied by the route property will be given a set of context parameters. These context parameters will contain information about the specific route, and can be used by your add-on to render appropriate content. For example, the spaceview route will have the context parameter space.key, which is the key of the space being rendered. The theme routes documentation details each context parameter and its meaning for each route.

The theme is expected to create an appropriate UI for the particular route being overridden. The spaceview route is expected to show the home page of a specific space. The JavaScript API is also available inside a theme iframe, so that the theme can perform client-side requests to Confluence or display dialogs.

Screenshot of a sample Theme showing a Confluence page

The theme can optionally provide custom space experiences, which can be applied to a particular space or globally (to all spaces). The look and feel settings in the descriptor will be saved into the colour scheme settings under a Theme setting.

Example

{
  "modules": {
    "confluenceThemes": [
      {
        "routes": {
          "spaceview": {
            "url": "/my-spaceview/{space.key}"
          }
        },
        "icon": {
          "width": 110,
          "height": 70,
          "url": "/my-theme-icon.png"
        },
        "description": {
          "value": "Some description"
        },
        "lookAndFeel": {
          "headings": {
            "color": "#333333"
          },
          "links": {
            "color": "#3572B0"
          },
          "menus": {
            "hoverOrFocus": {
              "backgroundColor": "#3873AE"
            },
            "color": "#000000"
          },
          "bordersAndDividers": {
            "color": "#0D0E0E"
          },
          "header": {
            "backgroundColor": "#661F2D",
            "button": {
              "backgroundColor": "#894E59",
              "color": "#FFFFFF"
            },
            "primaryNavigation": {
              "hoverOrFocus": {
                "backgroundColor": "#863647",
                "color": "#FFFFFF"
              },
              "color": "#FFFFFF"
            },
            "secondaryNavigation": {
              "hoverOrFocus": {
                "backgroundColor": "#863647",
                "color": "#FFFFFF"
              },
              "color": "#000000"
            },
            "search": {
              "backgroundColor": "#9A636B",
              "color": "#FFFFFF"
            }
          },
          "content": {
            "screen": {
              "layer": {
                "width": "100%",
                "height": "250px",
                "backgroundImage": "url('http://path/to/img/skyline.jpg')",
                "backgroundSize": "cover",
                "backgroundRepeat": "no-repeat"
              },
              "gutterTop": "20px",
              "gutterRight": "small",
              "gutterBottom": "10px",
              "gutterLeft": "small",
              "background": "linear-gradient(45deg, rgba(176,104,112,1) 0%, rgba(244,212,216,1) 100%)"
            },
            "container": {
              "padding": "0 20px",
              "borderRadius": "10px",
              "background": "#F4D4D8"
            },
            "header": {
              "padding": "20px 0 90px 20px",
              "borderRadius": "5px 5px 0 0",
              "backgroundColor": "rgba(0, 0, 0, 0.2)"
            },
            "body": {
              "padding": "10px",
              "borderRadius": "0 0 5px 5px",
              "background": "#FFFFFF"
            }
          }
        },
        "name": {
          "value": "My Addon Theme"
        },
        "key": "my-addon-theme"
      }
    ]
  }
}

Limitations

The following limitations apply to themes:

  • A theme can only override a pre-defined set of routes
  • A theme can’t override Confluence administration routes

Properties

key

Type
string
Required
Yes
Description

A key to identify this module.

This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

Keys must only contain alphanumeric characters and dashes.

The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on key and module key. For example, an add-on which looks like:

{
    "key": "my-addon",
    "modules": {
        "configurePage": {
            "key": "configure-me",
        }
    }
}

Will have a configuration page module with a URL of /plugins/servlet/ac/my-addon/configure-me.

name

Required
Yes
Description

A human readable name.

availableGlobally

Type
boolean
Description

A configuration to make the theme available to select in global administration. The default is false.

description

Description

A description for the Theme. This will appear next to the icon in the Theme selector in the Confluence admininstration screen.

icon

Type
Description

An icon to display in the Theme selector in the Confluence administration screen. The icon will be resized to 110px wide and 70px high to fit inside the Theme selector.

lookAndFeel

Description

The look and feel for the Theme

routeOverride

Type
boolean
Description

A configuration to enable or disable route override. The default is true.

routes

Description

Defines what routes to override for this Theme. See Theme Routes for a description of each route, as well as the appropriate context parameters available for each route.