Page History

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.

...

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}

...

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}

...

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!

...

Similarly, links should use similar syntax:

[On screen text|KEY: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}

...

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 pluginPlugin allows custom macros to be created within Confluence using a wide variety of programming languages such as PHP, JavaScript and JRuby.