How to customize a menu in XWiki using the Menu Application

20 Jun 2023 5 min read

Written by

Oana Elena Florea

, Customer Support Manager

Since customization is at the core of any open-source software, it is only natural for you to look for ways to tailor your wiki to your needs. In this guide, we'll help you with the steps you need to take in order to personalize your navigation menus.

What is the Menu Application?

Your XWiki instance allows you to seamlessly create, edit or customize menus using the Menu Application in the Administer XWiki > Look & Feel > Menus. The Menu Application is an extension that helps you create navigation menus displayed horizontally as a top bar after the page header, or vertically in a side panel. The extension has been written using our versatile App Within Minutes.

By default, the Menu Application is configured to allow only Administrators to see it, but you can change this through permissions. However, all Menu entries that you created with the application are viewable by everyone by default.

Starting with 10.8, the Menu is available by default in the Administration under the Look & Feel section. If the Menu Application does not appear in your list, we recommend installing or upgrading it to the latest version using the Extension Manager from your XWiki instance.

admin-menu.png

Create and edit the menu

To create a new menu, press ADD NEW ENTRY and enter your desired name.

menu entry.png

From this page, you can also edit an existing menu.

Customize the menu

As you will see below, you can customize your menu by selecting its location and by stating in which context the menu will be visible. 

1. Choose the display location of your menu

The menu is defined using nested lists, anchors, and icons. You can place the menu:

  • After the page header
  • In a right panel
  • In a left panel

menu structure_display loc.png

2. Specify in which context the menu is visible

You can specify a visibility scope for the menu:

  • Current User (default)
  • Current Wiki
  • Global

menu structure_vis scope.png

Note that Current Wiki and Global scopes require admin or programming rights.

  • Current Wiki: select this option when you only need the menu on one wiki.
  • Global: select this option to use the menu globally on all wikis.

Save the menu page. Congratulations! You can use your new menu right away!

How your menu will be displayed

If you choose to place the menu after the page header, it will be displayed horizontally as a drop-down menu bar.

header menu.png

header menu2.png

If you choose to display the menu in a side panel, you need to do one more step. Please see below.

Add the menu page you created (you can get the reference from the Information tab, e.g. Menu.Test Menu.WebHome) to the list of right/left or both panels in the Administration, e.g. Panels.Applications,Panels.Navigation,Menu.Test Menu.WebHome

To find the Panels section, all you need to do is go to Administer Wiki, expand Look & Feel, and choose Panels. In the Panels Displayed on the Left/Right fields, add the syntax as in the example above. Click on Save and the menu should appear immediately.

panels.png

If you are interested in more customization resources, you can check our Tips & tricks blog articles.

You may also be interested in:

Best practices

Run your on-prem wiki instance like a pro with Admin Tools Application (Pro)

XWiki SAS has released the Admin Tools Application (Pro) v1.0, one of the many business-ready Pro Apps, available in the XWiki SAS store. Through this app, you can optimize your XWiki on-prem installation, maintenance, and resources allocation — all from one central dashboard. Read the full article here.