1 - Space Level Panel Content

Embedding Pages

By far the most common way to customise panel content at space-level is to embed the content of a page from within your wiki.

Including a page

The most basic approach is to include a page from the current space using the include macro, for example if you wanted to display the contents of a page called "Sidebar Text" in one of your sidebars, simply add the following to the sidebar panel content:

{include:Sidebar Text}

For every page viewed in the space, the contents of the "Sidebar Text" page would be displayed in your sidebar.

If you view the actual "Sidebar Text" page, you'll see the same content twice - once on the page itself and once in the sidebar, or possibly an error message about recursion. To prevent this, use the builder-hide macro:

{builder-hide:title=Sidebar Text}
 {include:Sidebar Text}
{builder-hide}

This basically says If the title of the currently viewed page is "Sidebar Text", don't include the page.

So far, we have assumed that the included page always exists within the space - if it doesn't an error message will be displayed stating that the include macro can't find it. To avoid this problem you can wrap the include macro in the builder-show macro as follows:

{builder-show:page=Sidebar Text}
 {builder-hide:title=Sidebar Text}
  {include:Sidebar Text}
 {builder-hide}
{builder-show}

The page parameter checks for the existence of a page within the space - in this case, if the "Sidebar Text" page does not exist within the space it will not be included within the panel.

Importing a page

When you use the include macro, as shown above, the page content is rendered in the context of itself as if you were looking at the actual page.

However, if you need the content to be rendered in the context of the page being viewed (rather than the source page) you'll need to use the import macro, for example:

{import:Sidebar Text}

As with the include macro, you should check that the page exists before importing it and avoid importing it if you're looking at that page:

{builder-show:page=Sidebar Text}
 {builder-hide:title=Sidebar Text}
  {import:Sidebar Text}
 {builder-hide}
{builder-show}

There are, however, a number of things to take in to consideration when importing pages. Any links or images need to be fully specified. For example, this image won't work:

!some-graphic.jpg!

When you import page content, it's rendered in the context where it's viewed, not in the context of the source page. As such, unless every page in your site had an attachment called "some-graphic.jpg" you'd see a broken image or error message.

To fix this, use the following syntax:

!KEY:Page^some-graphic.jpg!

Where:

• Page is the title of the page that the image is attached to
• KEY is the space key where Page is located

Similarly, links should use similar syntax:

[On screen text|KEY:Page]

Macros

There are a wide variety of macros, the most useful of which are navigation macros, that can be embedded within panels using exactly the same notation as you'd use if you were placing them on a wiki page.

For example, if you wanted to display a table of contents in the sidebar you could use the toc macro (requires third party plugin):

{toc}

By using such macros, you can easily create navigation that automatically reflects the page or space being viewed.

However, some macros are only designed to be used within pages and might generate errors when used in other locations. To get round this problem you can use the builder-show macro to only display them on pages or blog posts, for example:

{builder-show:context=page,blogpost|mode=view}
 {toc}
{builder-show}

The notation above will only render the toc macro when you are viewing (not editing, etc) either a page or a blogpost.

Tip: You can also use "user macros" in panels.

Portals

If you have the  Community Bubbles plugin installed, you can embed portals within a panel, for example:

{portal:CUSTOM-SIDEBAR}

The portal macro is configurable so it allows the space administrator to choose which widgets are shown, and in which order, using a simple point-and-click interface.

We've used a portal in the sidebar to the right, showing widgets such as "Navigator" and "Related Communities".

Scriptix

The free Scriptix Plugin allows custom macros to be created within Confluence using a wide variety of programming languages such as PHP, JavaScript and JRuby.