Page History

h1. Installing Builder

*{excerpt}Installing and upgrading the Builder theme...{excerpt}*

h2. Requirements

* You must have system administration privileges to install the theme
* You must have correctly set the *Base URL* in Confluence's [General Configuration|USERGUIDE:General Configuration] settings.

(on) Should you encounter any problems, please see our [Troubleshooting Guide|Builder Troubleshooting] which lists all common problems and how to fix them.

h3. Plugin Requirements Overview

||Confluence Version||Plugin Repository||Theme Builder||Content Formatting Macros||Page Information Tools||
||1.4.x|n/a|1.4|n/a|n/a|
||2.0.x -- 2.1.x|[1.2|http://svn.atlassian.com/svn/public/contrib/plugin-repository/client/trunk/dist/plugin-repository-client-plugin-1.2.jar]|2.0.3|[1.6.3|http://svn.atlassian.com/svn/public/contrib/confluence/contentFormattingMacros-plugin/trunk/dist/adaptavist-plugin-contentFormattingMacros-1.6.3.jar]|[1.2.2|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/adaptavist-plugin-pageInfo-1.2.2.jar]|
||2.2.x|1.2|2.0.3-conf22|[1.6.3|http://svn.atlassian.com/svn/public/contrib/confluence/contentFormattingMacros-plugin/trunk/dist/adaptavist-plugin-contentFormattingMacros-1.6.3.jar]|[1.2.2|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/adaptavist-plugin-pageInfo-1.2.2.jar]|
||2.3.x - 2.4.x|Pre-installed|2.0.4|[Latest|http://svn.atlassian.com/svn/public/contrib/confluence/contentFormattingMacros-plugin/trunk/dist/]|[1.2.5|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/adaptavist-plugin-pageInfo-1.2.5.jar]|
||2.5.x|Pre-installed|2.0.9 or above|[Latest|http://svn.atlassian.com/svn/public/contrib/confluence/contentFormattingMacros-plugin/trunk/dist/]|[1.2.5|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/adaptavist-plugin-pageInfo-1.2.5.jar]|
||2.6.x|Pre-installed|2.0.9 or above, 3.x for best results|[Latest|http://svn.atlassian.com/svn/public/contrib/confluence/contentFormattingMacros-plugin/trunk/dist/]|[1.2.8|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/adaptavist-plugin-pageInfo-1.2.8.jar] or [above|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/]|
||2.7.x|Pre-installed|3.01.4 beta 23or above|[Latest|http://svn.atlassian.com/svn/public/contrib/confluence/contentFormattingMacros-plugin/trunk/dist/]|[1.2.8|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/adaptavist-plugin-pageInfo-1.2.8.jar] or [above|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/]|
||2.8.x|Pre-installed|3.1.4 or above|[Latest|http://svn.atlassian.com/svn/public/contrib/confluence/contentFormattingMacros-plugin/trunk/dist/]|[1.2.8|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/adaptavist-plugin-pageInfo-1.2.8.jar] or [above|http://svn.atlassian.com/svn/public/contrib/confluence/pageInfo-plugin/trunk/dist/]|

(i) Confluence 1.4.x is no longer supported - you can try Builder 1.4 or 1.5 if desired. The Content Formatting and Page Information Tools plugins were not required for Builder 1.x.

h2. Installing the Builder Plugin

If you are upgrading from an earlier version of Builder, please see the important notes on [upgrading Builder|#Upgrading Builder] later in this tutorial.

(!) When manually downloading plugins using Internet Explorer, make sure the file extension isn't changed to ".zip" - if it is, change it back to ".jar" before installing the plugin.

h3. 1. Install Dependant Plugins

Theme Builder requires two open source plugins, both developed by Adaptavist, to be installed:
* [Page Information Tools Plugin|USERGUIDE:Page Information Tools Plugin] ([CONFEXT|http://confluence.atlassian.com/display/CONFEXT/Page+Information+Plugin])
* [Content Formatting Macros|USERGUIDE:Content Formatting Macros] ([CONFEXT|http://confluence.atlassian.com/display/CONFEXT/Content+Formatting+Macros])

The easiest way to install these plugins is via the Plugin Repository. Alternatively you can download these plugins manually and install via the Plugin Manager or "Uploads" tab on the Plugin Repository.

Note: These plugins are only required for the navigation and title panels default settings - if you don't want to use tables or display page information in your customised theme design, you will not require these plugins.

h3. 2. Disable "Compatibility Macros" plugin

...or "incompatibility nightmares" as Adaptavist lovingly refer to them!

In the Plugin Manager, you'll see a plugin called "Compatibility Macros" - it's developed by Atlassian and is bundled with Confluence. It's enabled by default and sometimes also gets enabled after doing a Confluence upgrade in some circumstances, even if you've previously disabled or uninstalled it.

Unfortunately, the macros in this plugin break stuff - especially the table macro. Very few wikis actually need the plugin so generally we recommend disabling it completely. The main culprit is the table macro which can be disabled in isolation if desired.

If you have one of the very rare wikis that need the plugin, specifically the table macro, then you won't be able to use the macro of the same name from Adaptavist's free Content Formatting Macros plugin. The table macro is used primarily in the Header, Navigation and Title panels of the DEFAULT layout so you'd have to find some alternate way of arranging the content in those panels if you're unable to disable Atlassian's bundled Compatibility Macros plugin.

h3. 3. Install Theme Builder

Take a full backup of Confluence then follow the instructions applicable to the [version of the Builder theme|Builder Release Notes] you are using as shown below:

{expand:Theme Builder 1.x}{quote}
# Manually download the plugin from the URL in your license email.
# Install the plugin using the Confluence Plugin Manager (in Administration Console)
# Restart Confluence to complete the installation
{quote}{expand}

{expand:Theme Builder 2.x}{quote}
# Manually download the plugin from the URL in your license email.
# Install the plugin using the Confluence Plugin Manager (in Administration Console)
{quote}{expand}

{expand:Theme Builder 3.x}{quote}
# Install the plugin using the Plugin Repository
# Click the "config" link that appears next to the plugin and enter your license key
{quote}{expand}

h3. 4. Applying the Theme

Once the theme is installed, you need to apply it to spaces (or globally) for it to take effect. For more information, please see: [Enabling the Theme].

Before your first use of the theme, you will have to accept the End User License Agreement - if you do not, most of the themes features will be disabled.

To customise the theme to your requirements, please see [Theme Configuration].

h2. Upgrading Theme Builder

Take a full backup of Confluence before upgrading Theme Builder or Confluence.

*Before installing a new version of Theme Builder, the old version must first be uninstalled:*

* If using the Plugin Repository to install the new version (including using the "Upload" tab), the old version will be automatically uninstalled
* If you uploaded via the [Plugin Manager|USERGUIDE:Plugin Manager], first select the existing version of the plugin (by clicking the link in [Plugin Manager|USERGUIDE:Plugin Manager]) and click the "Uninstall Plugin" link to remove it
* If you manually installed the plugin to the WEB-INF/lib folder (not a good idea), you must manually delete that file from disk

{display-footnotes}

Specific notes for various upgrade scenarios are shown below - *click all that apply*:

{expand:Uninstalling Theme Builder on Confluence 1.4 - 2.2}{quote}
On some occasions, you may get an error message stating that the plugin could not be uninstalled. Should this happen, restart Confluence and try again.
{quote}{expand}

{expand:Upgrading to Confluence 2.3 or above when using Theme Builder 2.x or earlier}{quote}
Make sure to copy the {{/config}} folder to the new Confluence installation.

Also, be sure to install the correct versions of Theme Builder and dependant plugins as per the table at the top of this page.
{quote}{expand}

{expand:Upgrading to Confluence 2.5 or above}{quote}
Remember to upgrade Page Information Pluign and Theme Builder to the versions stated in the table at the top of this page.
{quote}{expand}

{expand:Upgrading to Confluence 2.6 or above}{quote}
If possible, upgrade to Theme Builder 3.0 or above which is more heavily tested on Confluence 2.6 and above.

If you are unable to upgrade to Theme Builder 3.0 or above, upgrade to at least version 2.0.9.

Upgrade to the latest version of Page Information Tools plugin.
{quote}{expand}

{expand:Upgrading to Confluence 2.7 or above}{quote}
You will need Theme Builder 3.0 (at least beta 23 or above) for Confluence 2.7 compatibility.
{quote}{expand}

{expand:Upgrading Theme Builder 1.x to 2.x or later}{quote}
See: [Migrating from 1.x]
{quote}{expand}

{expand:Upgrading Theme Builder 1.x or 2.x to 3.x}{quote}
See [Migrating from 1.x and 2.x]
{quote}{expand}

All currently known issues relating to upgrades of Theme Builder or Confluence are covered by our [Builder Troubleshooting Guide|Builder Troubleshooting].

h2. Bug Reports and Feature Requests

Before reporting a bug, please check our [Builder Troubleshooting Guide|Builder Troubleshooting] and [Builder Release Notes] - it's possible a solution already exists or a recent version of the theme already resolves the issue you have.

Our tutorial on [Reporting Bugs|USERGUIDE:Reporting Bugs] explains the process for informing us of bugs or ideas for new features for Theme Builder.