h1. Using Adaptavist Theme Builder
----
{cagridtoc:exclude=Using Adaptavist Theme Builder}

Adaptavist Theme Builder in a Confluence plugin that creates the layouts for cagrid.org. cagrid.org uses *Adaptavist Theme Builder Version 4.2.0*. There are several layouts for cagrid.org, although only a few are actually used. Each space is capable of having its own layout. Layouts cannot be applied to only one page.

For complete details on Adaptavist Theme Builer, view their [documentation|https://www.adaptavist.com/display/Builder/Documentation].


h2. Choosing a Layout for a Space
----

If a different layout needs to be chosen for a space (such as adding or removing the left hand navigation), follow the instructions below. The layouts names are self-describing "CAGRIDDOCSWITHNAV" is the layout for the Documentation space with left hand navigation. "CAGRIDDOCSWITHNONAV" is the layout for the Documentation space without navigation. There are similar layouts for project spaces, the home space, and knowledgebase.

# While viewing any page that is in the space that you would like to edit, select *Edit* --> *Administration* --> *Choose Layout*. You will be directed to the "Choose Layout" screen of Theme Builder in the Space Administration.
** The layout that is currently selected will be in *bold* at the top.
# From the list of layouts on the left, select the layout that you would like. As you click on each layout, the viewer will change so that you can preview the layout.
# Click *Save* in apply the new layout.


h2. Editing a Layout
----

Typically, changes don't have to be made to layouts. However, there are time when slight changes can be made. Be careful when editing a layout since any changes can effect multiple pages and spaces (depending on which spaces use the edited layout).

h3. {anchor:Access}Access the Layout Editor

# From any space, select *Edit* --> *Administration* --> *Choose Layout*
# Click the *Layout Manager* link that is in the second paragraph at the top.
{align:center}
{gallery:include=Choose layout.png,Layout Editor Overview.png}
{align}

*Layouts are in Hierarchies*
If you look at the list of available layouts on the left, you can notice that the layouts are organized similarly to parent and children pages in a space. In fact, this hierarchical organization is identical to parents and children. However, with layout, this hierarchy takes on a different meaning.

*Any changes made to a parent layout, will be reflected in all the children layouts*. For example, "CAGRIDHOME" is the parent layout for all of the layouts that are currently being used on cagrid.org. If a link is added to the "menu" (we'll get into what this is in a bit) of this parent layout, the same link will be added to the "menu" for all of the child layouts.

Children layouts inherit any changes made to parent layouts. And individual changes can be made to children layouts without affecting any other layouts.

h3. Add or Remove Components of a Layout

Each layout consists of components such as a header, menu, left sidebar, content, and footnote. These components can be added or removed for each layout.

# From the Layout Editor, click on the layout from the list of available layouts that you would like to edit.
# Click the *Layout* tab in the Layout Editor.
# Check or uncheck the boxes to add or remove the desired components.
# *Save* the layout by clicking on the floppy disk icon under the Available Layouts section.

* The *Header* is for the bar that contains the *Projects*, *Documentation*, *Downloads*, etc. buttons.
* The *Menu* is the bar for *breadcrumbs* feature and the *My cagrid.org*, *View*, *Edit*, etc. menus.
* *Left Sidebar* is the left hand navigation found in some spaces.
* *Footnotes* contains the information for when the page was last edited at the bottom of each page
* *Page* contains the "Adaptavist Theme Builder Powered by Atlassian Confluence" text at the bottom of each page.
* The *Content* component cannot be removed from a layout. This is the heart of each page and holds the content for each page. This is what is edited when you click *Edit this page* for each page. Thus, you cannot change the
The above components are the most commonly used in all of the layouts. As the layout of the site is now, these components shouldn't need to be added or removed. However, it's useful to know what each of them represents on a page.

h3. Edit the Components of a Layout

In rare instances, a layout may need to be edited. For example, a link may need to be added or removed to the "Menu" component. Follow the instructions below to edit the components of a layout.

# [Access the layout editor|#Access].
# Select the Layout that you want to edit from the Available Layouts on the left.
# Click the *Layout* tab in the Layout Editor.
# In the layout view (the preview for the layout), click on the name of the component that you wish to edit. A pop up box to edit the style and content of the layout component will appear.
# Make your desired changes and click *OK*.
# *Save* the layout by clicking on the floppy disk icon under the Available Layouts section.

The *Style* tab allows you to change the background color, position, and border, size, and text for the component.

The *Content* tab allows you to change what is actually displayed for the that component. The content for the *Header* bar contains a table to display the images and links for the "Projects", "Documentation", "Downloads", etc., buttons.

Likewise, the content for the *Menu* bar contains a table that holds macros for the breadcrumbs, menus, and links.
{align:center}
{gallery:include=menu content.PNG}
{align}

You can add links or items to the menus following the same syntax. However, to add or remove a link from the *Edit* or *View* menus, requires a different process (described below).

h3. Edit the *View* and *Edit* menus

Adaptavist provides convenient \{view} and \{edit} macro to use in it's Layout Editor. These macros can be used so that you don't have to write all of the links in the content tab of a component. To edit what links the menu macros contain, follow the instructions below.

# [Access the layout editor|#Access].
# Select the Layout that you want to edit from the Available Layouts on the left.
# Click the *Menus* tab in the Layout Editor.
# Scroll down to the "Menu Shortcut Macros" section and click *Edit...*
# Make your desired changes following the Adaptavist syntax.
# Click *OK*.
# *Save* the layout by clicking on the floppy disk icon under the Available Layouts section.


For complete details on editing the menus, see https://www.adaptavist.com/display/Builder/Menus+Tab.


h3. Edit Custom CSS

Each layout can also have its own custom CSS. All of the layouts have inherited the CSS from the parent layout "CAGRIDHOME". The CSS is responsible for such things as the blue margins either side of every page, the format and style of headers, the background color of popup menus, and so on.

CSS is pretty powerful in Adaptavist and lets you make all of the custom edits to make layouts looking their best. There is only so much that you can edit using the *Style* and *Content* tabs fo each component of a layout. Every Confluence wiki that uses Adaptavist that I have created has used custom CSS. If you don't use CSS stylesheets, you're stuck with using default menus and colors. To make site wide changes in the CSS, make sure you are changing the CSS for the "CAGRIDHOME" layout.

# [Access the layout editor|#Access].
# Select the Layout that you want to edit from the Available Layouts on the left.
# Click on the *CSS* tab.
# Click the *Edit Custom CSS* button.
# Change the CSS stylesheet appropriately following the syntax for CSS.
# Click *OK*.
# *Save* the layout by clicking on the floppy disk icon under the Available Layouts section.

For complete documentation on Adaptavist's use of CSS, see [CSS Tab|https://www.adaptavist.com/display/Builder/CSS+Tab]

You will need to know the HTML structure to edit the proper components of the layout: [HTML Structure (Builder 4.x)|https://www.adaptavist.com/display/Builder/HTML+Structure+%28Builder+4.x%29]

Here's a walkthrough tutorial of how to create CSS stylesheets for Adaptavist: https://www.adaptavist.com/display/Builder/4+-+CSS

Also, a great independent tutorial on how to use CSS: [CSS Tutorial|http://www.w3schools.com/css/].


h2. Other Options
----

The Layout editor offers a variety of other options for each layout. These are found in the *Options*, *HTML*, and *Permissions* tabs of the Layout Editor. More information on all of the customizations for layouts is available in Adaptavist's [documentation|https://www.adaptavist.com/display/Builder/Documentation].

Additionally, control over the Theme Builder for the entire site can be administered through the Confluence *Site Administration*. You can create and restore backups of the layouts, see the theme and layout that each space is using, and change global permissions for layouts among other functions.

To access these functions, from any page, select *Edit* --> *Administration* --> *Site Administration*. Scroll down to the *Theme Builder* section of the left hand panel and click on the appropriate links.

For complete documentation, see Adaptavist's [Theme Administration|https://www.adaptavist.com/display/Builder/Theme+Administration].