Creating a Configurable Theme

A configurable theme is a theme where only a subset of the files - the configuration file(s) - can be edited after copying the configurable theme.

An example of a configurable theme is the The Help Center Theme, where after copying it, a user can only edit the theme-setting.properties file and add new files.

Creating a Configurable Theme

Only plugin themes can be used as configurable themes. A plugin theme can be created, for example, by downloading an existing theme as a plugin jar.

In the atlassian-plugin.xml file of the plugin theme the actual theme is defined in the scroll-viewport-theme tag:

<scroll-viewport-theme key="my-configurable-theme" name="My Configurable Theme">
	<resource name="css/app.css"    location="css/app.css"/>
	<resource name="js/app.js"		location="js/app.js"/>
	<resource name="config.txt"		location="config.txt"/>
</scroll-viewport-theme>

In this example we have a theme with three files.

To make the theme configurable, a param tag with the name "configurable" and value "true" needs to be added somewhere in the scroll-viewport-theme tag like this:

<scroll-viewport-theme key="my-configurable-theme" name="My Configurable Theme">

	<param name="configurable">true</param>

	<resource name="css/app.css"    location="css/app.css"/>
	<resource name="js/app.js"		location="js/app.js"/>
	<resource name="config.txt"		location="config.txt"/>
</scroll-viewport-theme>

Next, the configuration file(s) need to be marked as such by adding a config param to the file(s) like this:

<scroll-viewport-theme key="my-configurable-theme" name="My Configurable Theme">

	<param name="configurable">true</param>
	
	<resource name="css/app.css"    location="css/app.css"/>
	<resource name="js/app.js"		location="js/app.js"/>
	<resource name="config.txt"		location="config.txt">
		<param name="config">true</param>
	</resource>
</scroll-viewport-theme>

When the plugin theme is copied, only the file config.txt can be edited in the editor.

Fallback to Original Files

When copying a configurable theme, only the configuration files are actually copied. For all other files, the copy of the theme falls back to the configurable plugin theme.

This means that if a non-configuration file in the original theme is changed, all copies of that theme automatically use that updated file.