Access Keys:
Skip to content (Access Key - 0)

Notation

Using Adaptavist Theme Builder

Contents

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.

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.

  1. 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.
  2. 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.
  3. Click Save in apply the new layout.

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).

Access the Layout Editor

  1. From any space, select Edit --> Administration --> Choose Layout
  2. Click the Layout Manager link that is in the second paragraph at the top.

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.

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.

  1. From the Layout Editor, click on the layout from the list of available layouts that you would like to edit.
  2. Click the Layout tab in the Layout Editor.
  3. Check or uncheck the boxes to add or remove the desired components.
  4. 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.

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.

  1. Access the layout editor.
  2. Select the Layout that you want to edit from the Available Layouts on the left.
  3. Click the Layout tab in the Layout Editor.
  4. 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.
  5. Make your desired changes and click OK.
  6. 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.

You are unable to edit the Content tab for the Content component for entire layout since the content for each page is unique. The content for the Content component is edited by clicking on the Edit this page... while viewing a page. You can however, change some minor style features.

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).

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.

  1. Access the layout editor.
  2. Select the Layout that you want to edit from the Available Layouts on the left.
  3. Click the Menus tab in the Layout Editor.
  4. Scroll down to the "Menu Shortcut Macros" section and click Edit...
  5. Make your desired changes following the Adaptavist syntax.
  6. Click OK.
  7. 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.

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.

  1. Access the layout editor.
  2. Select the Layout that you want to edit from the Available Layouts on the left.
  3. Click on the CSS tab.
  4. Click the Edit Custom CSS button.
  5. Change the CSS stylesheet appropriately following the syntax for CSS.
  6. Click OK.
  7. 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

You will need to know the HTML structure to edit the proper components of the layout: HTML Structure (Builder 4.x)

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.

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.

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.
Last edited by
Sarah Honacki (735 days ago)
Adaptavist Theme Builder Powered by Atlassian Confluence