Provides placeholders to put content located left or right of the page's content

Description

What's a Panel?

A Panel is a rectangular zone that is usually displayed in a column on the left or right of the UI.
Here is an example of a page containing five panels. Each panel has been highlighted with an orange border.

A panel can contain anything: navigation, searches, page creation, statistics display, etc. Panels often contain clickable links. These links are written manually or automatically generated by scripts. Panels always come with their own title.

Panel columns surround the content. In the screenshot below, the left panel column is highlighted in orange, and the right is highlighted in green.

A full set of Panels is available by default, covering a lot of standard use cases for panels. Furthermore, it is possible to create new Panels for specific needs. The Panel Application offers an Administration UI to configure how to display Panels and choose which Panels to display. This means that in order to create, modify or set Panels, you need to have administration rights.

Access to the Panels list

Where to find them

There are several possibilities to access the Panels Application:

• By navigating directly to the URL: http://<server>/xwiki/bin/view/Panels/.
• By accessing it through the Applications Index:

  

• By typing "Panels" in the search engine.
• By accessing "Administration" - "Look & Feel" - "Panel Wizard" section, by clicking on the "Go to Panels home page" button.
• By using the Dashboard and clicking on the Panels page (provided if you are an Advanced user , since otherwise we're hiding that technical page for simple users).
• Between version 6.0 and 8.2, access was possible from the Applications Panel:

  

Panels's home page

This home page shows a list of the available Panels, containing:

• a description
• a visualization link (clicking the Panel's name displays its location page)
• an edition link ("Edit": the Panel opens in form edition mode, giving you access to the settings fields)
• a deletion link ("Delete": deletes the Panel's page)

Existing Panels

This Panels Application provides several existing Panels that you can use directly in your wiki. Here's a description of some of these Panels:

• Navigation Panel
• Children Panel
• Siblings Panel
• SpaceDocs Panel
• Spaces Panel
• Application Panel
• Create Page Panel

Navigation Panel

The Navigation Panel displays the page hierarchy, allowing you to navigate through your wiki (it uses the Document Tree Macro under the hood). If the current page is available in the tree, it is expanded automatically to show its location when the page is loaded.

The top level application pages are excluded from the tree by default (provided that the top level page is of a type that denies being modified by users), in order to let you focus on your own content and because the applications are also accessible from the Applications Panel. However, you can disable this filter (if you want to view all pages) or configure other page exclusions from the Wiki Administration.

The Navigation Panel administration section allows you to drag & drop pages from left to right and right to left to build how the Navigation Panel should look visually.

XWiki 16.4.0+ You can also reorder the top level pages using drag & drop or with the Alt + Shift + Up/Down Arrow keys. When a top level page is moved to a different position, it becomes "pinned" along with all its previous sibling pages (in other words, you turn manual ordering on from the new position upwards). See the Index Application to understand how pinned pages work. In short, they are displayed before the rest of the child pages, allowing you to achieve a mixed manual and automatic order. You can pin or unpin a top level page by hovering or focusing the corresponding tree node and using the dedicated button. For pinned pages, there is a pin icon displayed on the far right side. Note that when you unpin a page, all the following sibling pages are also unpinned (in other words, you turn automatic ordering on from that position downwards).

Children Panel

Displays Child pages of the current page:

Siblings Panel

Displays Sibling pages of the current page:

SpaceDocs Panel

Spaces Panel

Application Panel

The application panel displays the list of all existing applications in the wiki. It adapts itself to the width of the panel columns, so you can see it with 2 different designs:

Small width (FontAwesome)	Medium & large width (FontAwesome)

Small width (Silk)	Medium & large width (Silk)

On devices with a small screen, when panels are displayed under the page content (currently, it is the case for Flamingo only), the appbar is displayed differently to use all the available width:

You can select which applications are displayed in the Application Panel, and which are not:

You just need to drag & drop the applications from a list to the other!

You can also re-order the applications that are displayed, still by using the drag & drop mechanism:

To change this configuration, go to the Administration of the Wiki, in the "Applications Panel" section.

Create Page Panel

Panel's structure

Take a look at the "QuickLinks" panel in the list. We will use it as an example.

Click the panel's name (URL: http://<server>/xwiki/bin/view/Panels/QuickLinks)

Click the edit link > which allows you to see the different fields in order to edit the panel. You can fill in or select these fields:

"Name" field

The name of the wiki page where the panel is stored. Here, the name is: "QuickLinks".

"Type" field

There are two available options: "view" or "edit". According to your selection, the panel will be displayed when the wiki page is either in view mode or in edit mode. Most of the panels are used in view mode. For the new panel you're creating, leave the selector on "view".

"Category" field

Panels are sorted by category according to their purpose. The categories are: 

Category	Panel's name example
Information	Recently Modified
Information	Quick Links
Navigation	Navigation
Tools	New Page
Tools	Search
Administration	(empty category as of today)
Other	(empty category as of today)

"Description" field

Contains a short description of the wiki. This text will appear on the panel's home page.

"Executed Content" field

This section contains the panel's code. In our example, we provide an edit link for this panel for administrators.

"Asynchronous rendering"

Enabled or disable asynchronous rendering of the panel. Disabled by default.

"Cached"

Indicate if the result of the execution of the element should be cached. Disabled by default.

"Context elements"

The context information required during the execution of the panel (current user, current document, etc.). It's also used to generate the cache key.

Creation - Edition

Introduction

To create or to modify panels, you need to have administration rights.

Create a new panel

Go to this page : http://<server>/xwiki/bin/view/Panels/

In the field "Create new panel" type the name of your new panel, for instance "User Guide".

Click the "Create" button in order to open the creation panel form.

Notice that this page has been created under http://<server>/xwiki/bin/view/Panels/User+Guide

New panel creation form

Now you have the panel creation form on your screen, in edit mode. If this is not the case, please return to the previous section.

Fill in or select the following sections: "Name", "Type", "Category" and "Description" according to the information already presented in the previous section ("Panel's structure).

"Content" field

By default, two lines are displayed in this section:

#panelheader('User Guide')

#panelfooter()

Editing the panel's header

#panelheader allows you to change the name displayed in the panel's header. If User Guide is ok, leave it as it is: by default, those words have been automatically inserted when you created the panel a few minutes ago.

"Content" field: create a new link

The link code will occur between #panelheader('User Guide') and #panelfooter(). For instance, if you want to create a link to the sandbox home page, type:

#panelheader('User Guide')

* [[Accueil Sandbox>>Sandbox.WebHome]]

#panelfooter()

To add a second link to the blog's home page, type:

#panelheader('User Guide')

* [[Accueil Sandbox>>Sandbox.WebHome]]
* [[Blog>>Blog.WebHome]]

#panelfooter()

To finish your panel, click "Save & View": you've just completed your first panel!

You may add as many links as you wish. Here you can find some tips about the link syntax.

To learn more about Panels, you may study the content of panels executing scripts, such as "Space Docs". This panel renders a list of documents in a specific space.

"Content" field: finding the current panel column width

A panel can have several widths depending on the configuration of the panel column. To know the current width and display something else depending on it, you can use the $xwikiPanelWidth variable. The possible values are: "Small", "Medium" and "Large".

Configuration

The Panels application provides a configuration section in the Administration. This means you need administration rights to configure the panels. The configuration can be done for the entire wiki (from the wiki administration) or a specific page (from the page administration). For instance, the blog "Categories" panel is displayed on the Blog page but not on the Sandbox page.

The Panels administration section, located in the "Look & Feel" category, has two tabs: Page Layout and Panel List.

Page Layout

On this tab, you can select which panel column is visible (none, left, right or both) and you can choose the column width. The changes you make are applied instantly, but they are not saved. You need to click the Save button to persist your changes.

The advanced users can use a text input to specify the list of panels to display on the left and right columns. The value of the text input is a comma-separated list of references to panel pages. The non-technical users are advised to use the Panel List tab that supports drag & drop.

Panel List

On this tab, you can see the list of available panels. You have to drag & drop them to the panel column of your choice. And if you want to remove one of the panels, drag & drop it from the panel column to the middle section. Again, you must click the Save button at the end to keep your changes.

Controlling where to display Panels

Panels can be configured to be displayed at the wiki level (i.e., all pages) using the Panels administration section mentioned above. It's also possible to override the displayed Panels at any Page level (again using the Panels section from that page administration).

If you need finer-grained control, such as displaying a Panel only for a given page, you'd need to edit the Panel and add a condition in the Panel's script content. For example, imagine you'd like to display the "My Recent Modifications" Panel only for the Home Page Main.WebHome. To do, so edit the Panel http://<server>/xwiki/bin/inline/Panels/MyRecentModifications and modify the content as follows:

#if ($doc.fullName == "Main.WebHome")
#set($recentDocs = $xwiki.searchDocuments("where 1=1 and doc.author='$context.user' order by doc.date desc", 5, 0))
...
#end

Troubleshooting

Panel Wizard Slowness

The panel wizard can be slow on large wikis. A workaround consists of not loading the administration's panels section, and instead simply updating the page layout by editing the following fields of the XWiki.XWikiPreferences object attached to page XWiki.XWikiPreferences: Panels displayed on the left, Panels displayed on the right, Display the left panel column, Display the right panel column, Width of the left panel column, Width of the right panel column. See also the related issue: XWIKI-16579.