Panel Content

Panel content is one of the most important features of any theme layout, it allows you to define the navigation and other content that appears on all pages that use the layout.

Where do I go to edit panel content?

Go in to the Panel Editor for the desired panel and click the Content button that's shown near the bottom right:

Not all panels can have their content edited (see next section on this page) so sometimes this button won't be available.

The content for the panel will then be displayed in a window (shown below) - make any required changes and click "OK" to apply them or "Cancel" to keep using the existing content.

Note: Remember to always save the layout - otherwise changes you've applied won't get stored on the server.

Which panels can I put content in?

Content can be customised for the following panels:

While the panels have common uses, you can put pretty much anything in any of the panels. If you want to display the breadcrumb trail in the footer, delete the builder-breadcrumbs macro from the navigation panel and add it to the footer panel. Simple!

What sort of content can I put in panels?

By default, panels contain wiki notation - so just about anything you can put on a wiki page can be put in to a panel, including macros! However, there are a few other types of content that can be added to panels using the "Options" tab:

Wiki Markup

This is by far the most common render mode as it allows you to use wiki markup, including macros, to generate panel content. This is really useful because it makes adding things like navigation trivial. As well as being able to use all the Builder Macros, you can use almost any macro available in Confluence, including third party macros from any plugins you've installed.

There's a few things to be aware of though...

If you're using wiki notation that refers to attachments, you'll need to provide the full path and space key to the attachment (you can't guarantee that the user will be looking at the same page that the attachment is on. For example:

!someImage.jpg!

!SPACEKEY:Page Title^someImage.jpg!

Remember, also, that the user would need access privileges to the attachment - what happens if they can't access the page or space where it's stored? If you're using the layout at global level (so the "Login" screen will use your layout) then what happens if the user needs to be logged in to access the attachment? At Adaptavist, we tend to put a lot of our images in places that are accessible by anonymous users such as a page on our public website (or more recently a dedicated space for storing publicly accessible resources - makes things easier to manage). If your wiki doesn't allow anonymous access and you want to use an attachment, you'll have to find somewhere else to store it (eg. some general webspace that can be accessed by everyone).

You also need to test any macros that you use - many macros that come with Confluence, and many third party macros from plugins, will only work when viewing a wiki page. Because the layout can be applied to other areas of the wiki, such as login page, search results, space administration, etc., you'll have to check that the macros you're using don't break on those pages.

You can usually work around a lot of these problems by only showing content based on user permissions or the current location within the wiki - to do this use either the builder-show macro or the builder-hide macro. For example, to only show content when the user is viewing, but not editing a wiki page, you could use:

{builder-show:context=page|mode=view}
This will only be shown when viewing a normal wiki page.
It won't be shown in space admin, search results, etc.
It won't be shown if the user is editing a page or viewing page attachments, etc.
{builder-show}

It's really important that you don't use excessive amounts of wiki markup and macros in your theme layout because Confluence has to process all of the markup and macros on every single view of the page - that could make your wiki run really slow. Our tutorials on Performance Tuning provide some advice on how to avoid or work around such issues.

Another way to keep your wiki running quickly is to not use wiki markup...

Velocity then Raw HTML

This render mode allows you to use velocity templates and raw HTML in your panel content. It's the same approach used by the default Confluence theme so it's much faster than wiki markup rendering. The content is first Velocity parsed, and then the resulting HTML gets output in to the panel.

For more information on velocity templates, we recommend the following external links:

• Velocity Template Overview - although this documentation focuses on changing the velocity templates in the default Confluence theme, it will be a useful place to start and also shows how to call macros and render wiki markup from within velocity
• The Global Helper object ($helper in Velocity) is really useful
• Apache Velocity 1.5 user guide - the main user guide for Velocity syntax

As well as giving fast performance, this render mode still allows you to use macros, and even wiki markup if desired - but you'll probably need an experienced web developer to review the links above because it's quite a techie process.

Raw HTML only

This is by far the fastest possible way to output content in to a panel - simply put your static HTML (like you would use on a normal web page) in to the panel content and it will be output in to the panel with no further processing.

Tip: The footer panel will often have static content - like copyright statement and fixed links to privacy policy, etc. Start by using simple wiki notation to generate that panel content, then from your web browser view the page source (HTML). You can then copy the generated HTML in to the panel content, switch the render mode to Raw HTML and all your pages will load a little bit faster.

Velocity then Wiki Markup

Requires Theme Builder version 3.3 or above

You'd think that this would be the slowest way to render panel content because it's using slow (but easy to use) wiki markup in addition to Velocity rendering. However, if you've got panel content that changes depending on who's looking at the page or what they are looking at, etc., you can often implement that logic using Velocity (rather than macros such as builder-hide and builder-show). When you take this approach, you not only reduce the amount of macros Confluence has to process (by replacing them with Velocity commands) but you also reduce the total amount of wiki markup Confluence will need to parse.

Imagine you start with normal wiki notation like this:

{bulder-show:space=Website}
 {panel}Welcome to ACME!

 On this site you'll find stuff!{panel}
{builder-show}
{builder-hide:space=Website}
 {builder-show:space=@ersonal}
  *(!) This is a personal space!*

  Views and opinions expressed here are those of the
  user who owns this space, blah blah...
 {builder-show}
 {builder-show:space=@global}
  {recently-updated}

  Some other stuff.
 {builder-show}
{builder-hide}

This markup will:

• Show a "Welcome to ACME" panel on any pages in the space with the "Website" space key
• For pages outside the website space, do one of the following:
  • Show a " This is a personal space" warning on any personal spaces, or
  • Show a list of recently updated content in normal spaces

Using velocity, you could use:

#if ("Website".equalsIgnoreCase($helper.spaceKey))
 {panel}Welcome to ACME!

 On this site you'll find stuff!{panel}
#elseif ("personal".equalsCaseIgnore($helper.spaceType))
  *(!) This is a personal space!*

  Views and opinions expressed here are those of the
  user who owns this space, blah blah...
#else
  {recently-updated}

  Some other stuff.
#end

Confluence can parse the velocity commands much, much faster than it can parse macros so you get an instant performance boost from that. After the velocity parsing, all unwanted wiki markup will have been removed - for example, in the Website space Confluence will only see, and need to render, the following panel content:

 {panel}Welcome to ACME!

 On this site you'll find stuff!{panel}

It still won't be as fast as using Velocity then HTML, or Raw HTML only, but it's often easier to maintain in this hybrid format.

Deferred panel loading

On the Options tab within the content window, there's an option to defer panel loading:

If you select this option, the content of the panel will be output at the bottom of the web page in a hidden panel. When the web page finishes loading, the content will be moved back in to the visible panel. This option isn't available on all panels and it should only be used with great care.

Why would you want to do this? Well, there are two reasons:

• Search Engine Optimisation:
  You might have some content in the left sidebar (eg. a warning about personal spaces) that will be shown on lots of pages in your wiki. When a search engine like Google crawls your site, it would see this content before the main page content and might give it slightly higher importance than the actual content of your wiki pages. Deferring would make the sidebar content, as far as Google is concerned, appear right at the bottom of the web page. When a user views the web page, the sidebar may appear empty for a moment, but the content will soon appear once the page loads.
• Content with lots of images:
  Images take a while to load - and images in a theme panel are usually less important than images in your wiki page so it makes sense to trick the browser in to loading the wiki page images first, then the sidebar images.

Our advice is to only use this option if you really need it - under all normal circumstances it's better to display panel content normally. There's two key issues to be aware of if you plan to use this feature:

• If your panel contains JavaScript, don't defer it! Because of the way deferring works, the javascript in the panel would likely break.
• Deferred panel loading requires JavaScript - if the end-user doesn't have JavaScript enabled, they'll never get to see the panel content

Note: If you just want to output content at the bottom of the page, put the content in to the footer panel.

CSS Customisation

To customise the borders, background, fonts, etc., within a panel, either use the options provided by the Panel Editor (quick and easy, at the expense of flexibility) or the CSS Tab (a bit more complex, but far more flexible).

Hints and Tips

Start with wiki markup for your panel content - even if you plan to convert to HTML or something else later. The other render modes are more difficult to edit so make sure you're happy with your content before you start optimising. For smaller wikis you won't need to optimise at all - it's probably only worth optimising if pages are starting to take too long to load.

You can import entire wiki pages in to panels - either using the include macro or import macro. For more information, see our tutorial on Space-level Theme Settings (which contains loads of other useful tricks).