Menu Application

The Menu Application, now bundled with the XWiki Standard Flavor, was built with App Within Minutes in order to provide an easy way of creating navigation menus that you can choose to display:

  • horizontally as a top bar below the page header
  • vertically in a side panel

By default, only wiki administrators have permission to view and access the Menu Application home page. However, menu entries are viewable by all the wiki users, provided the visibility scope of the entry allows it. 

Access the Application Home Page

Wiki administrators have 2 possibilities to access the Menu Application home page:

  • from the "Applications" panel displayed by default in the column on the left

    MenuAppsPanel.png

  • from the drawer menu, by clicking the DrawerMenuIcon.png button, then on "Application Index" and finally on "Menu"
    ApplicationIndexDrawer.pngMenuAppsIndex.png

Create a Menu Entry

By default, you need administration rights in order to create navigation menus.

Start by accessing the Menu Application home page and click on "Add New Entry" in the "Actions" panel.

MenuAppHome.png

Next, enter the new menu name, then click the "+" icon or press Enter.

NewMenuName.png

You will notice that the "Menu Structure" field already contains a menu hierarchy example - basically, a menu consists of lists, anchors and icons. You may either choose to extend this one or to create a new structure from scratch. If you are familiar with the XWiki syntax, click on "Source" in the CKEditor menu bar and start customizing your menu.

MenuStructure.png

You may also associate Font Awesome or Silk icons to each menu line using the syntax:

  • image:icon:[IconName] inside the wiki link for Silk icons
  • $services.icon.render('[IconName]') inside the wiki link for Font Awesome icons. In this case, also make sure to include the content inside a {{velocity}}{{/velocity}} macro

The full list of icons supported in XWiki is available in the page IconThemes.FontAwesome and IconThemes.Silk respectively.

Using Silk IconsUsing Font Awesome Icons
MenuSilk.pngMenuFA.png

Menu Display Location

MenuDisplayLocation.png

By default, the option "Menu Display Location" is set to "Nowhere", meaning that the menu is hidden. To make it visible to other wiki users select:

  • "After the Page Header" - the menu is displayed horizontally as a top bar below the page header

    HorizontalMenu.png

  • "Inside a Right Panel" / "Inside a Right Panel" - the menu is displayed vertically in the panel column on the right / on the left
If you choose to display the menu in a panel column, you must also add it to that column from the Panel Layout. For instance, to display the menu "Menu.Navigation Menu" on the left column, simply add the value "Menu.Navigation Menu" in the field "Panels Displayed on the Left".

Menu Visibility Scope

MenuVisibilityScope.png

You can also specify a visibility scope for the menu:

  • Current User (default)
  • Current Wiki - visible to all users registered on the current wiki
  • Global - visible to all users registered on all the wiki farm
In case you set the menu visibility scope to Global, you must also add it to the correct sub-wiki column as previously explained.

Menu Macro

The "Menu" macro can be used outside the Menu Application to create a menu in the content of a wiki page.

Usage

{{menu id="<id>" type="<horizontal|vertical>"}}
....menu content here...
{{/menu}}

In the macro content you may add any wiki syntax but in order to generate a menu hierarchy it is easier to use just lists, wiki links and/or icons, as shown in the previous paragraphs. 

An empty list item is considered a menu separator. Based on the menu type, the separator is displayed either as a vertical bar or as an horizontal bar. In order to generate an empty list item you can use the following syntax: * ----.

Note that leaving the list item empty doesn't work because of the rendering engine implementation.

Parameters

NameOptionalAllowed ValuesDefault ValueDescription
idyesValid HTML IDEmpty StringOptional menu identifier that will be set on the HTML element wrapping the menu. You can use this identifier in the JavaScript code to access the menu DOM or in functional tests to assert the menu items.
typeyeshorizontal (default) or verticalhorizontalThe optional menu type determines how the menu is displayed in the UI and its behavior.

The value of the type parameter is used as a CSS class name on the menu container and so it can accept various additional class names like:

  • use fixedWidth in combination with type="horizontal" when you have more than 2 levels of menus. The reason is that the horizontal menu was written to work without JavaScript (i.e. CSS-based) and in order to know where to display a drop-down sub-menu the drop-down menu must have a fixed width defined.
Example{{menu type="horizontal fixedWidth"}}
* [[image:icon:house Home>>Main.WebHome]]
* ----
* Applications
** [[image:icon:transmit Blog>>Blog.WebHome]]
** [[image:icon:application_view_tile Dashboard>>Dashboard.WebHome]]
** [[image:icon:group User Directory>>Main.UserDirectory]]
** ----
** [[Create>>AppWithinMinutes.WebHome]]
** [[Install>>XWiki.XWikiPreferences||queryString="editor=globaladmin&section=XWiki.AddExtensions"]]
* [[Documentation>>http://www.xwiki.org]]
** [[Syntax Help>>XWiki.XWikiSyntax||queryString="xpage=print"]]
** Take a Tour
*** [[Basic Features>>]]
*** [[Advanced Features>>]]
{{/menu}}
  • collapsible makes a vertical menu collapsible but it requires JavaScript
  • open makes a collapsible vertical menu expanded by default when the page is loaded
Hierarchy Panel{{menu type="vertical collapsible"}}
{{velocity}}
#set ($depth = 3)
#set ($limit = 10)
#macro (children $parentDoc $level)
 #foreach ($child in $parentDoc.getChildren($limit, 0))
   #set ($childDoc = $xwiki.getDocument($child))
    $stringtool.repeat('*', $level) {{html}}<a href="$childDoc.getURL()">$escapetool.xml($childDoc.plainTitle)</a>{{/html}}
   #if ($level < $depth)
     #children ($childDoc $mathtool.add($level, 1))
   #end
 #end
#end
#children ($doc 1)
{{/velocity}}
{{/menu}}

  

Search this space