Menu Application

Version 100.1 by Manuel Leduc on 2021/06/17 17:30

text_list_bulletsMenu application
TypeXAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard (9.4-rc-1+)

Installable with the Extension Manager

Description

This is a simple application that helps you create navigation menus to be displayed either horizontally as a top bar after the page header or vertically in a side panel. The application has been written using the App Within Minutes Application so you should be familiar with the home page.

By default the application is configured to only allow Administrators to see it (this can be changed through permissions). However all Menu entries created with the application are viewable by everyone by default (provided the visibility scope used when creating the entry allows it; for example selecting a "Current User" visibility makes the created menu only visible for the current user, see below for more). Since 9.6RC1

Since 10.8 the menu is available in the Administration under the "Look & Feel" section. 

admin-menu.png

Menu Usage

 
menuHomePage.png

You can create a new menu or edit an existing one.

menuEditPage.png

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

Currently, in order to have the menu displayed inside a right/left panel you need to make one more step: add the menu page you created (e.g. Menu.MyMenu) to the list of right/left panels in the administration, e.g. Panels.Applications,Panels.Navigation,Menu.MyMenu.

You can also specify a visibility scope for the menu:

  • Current User (default)
  • Current Wiki
  • Global

When using the Global option, to see the right/left panel in a subwiki you need to make the step as stated above, but also, you need to link the subwiki to the Main wiki (e.g. xwiki:Menu.Navigation Panel).

Starting with 5.2, admins don't have Programming Rights by default anymore. So, if you're on a XE instance, macros with Global visibility which weren't saved with Programming Rights won't work. That's why you have to either change macro visibility to Current Wiki or Current User, or to give Programming Rights to XWikiAdminGroup, depending on your needs.

Note that the wiki and global scopes require admin or programming rights.

menuViewPage.png

Save the menu page and you should be able to use the menu right away. If you chose to place the menu after the page header it will be displayed horizontally as a drop-down menu bar.

menuBarAfterHeader.png

Here's how the menu looks like if it has multiple levels:

menuBarAfterHeader-multipleLevels.png

If you choose to display the menu in a side panel it will be displayed vertically. You can collapse/expand each sub-menu.

menuPanel.png

Since XWiki 6.4M2, on Flamingo based skins, the menu is responsive and also is using LESS variables in order to adapt its styling according to the active Flamingo Theme, see screenshots

Starting with XWiki 9.2-rc-1, the horizontal menu layout has been improved on Mobile by introducing menu burgers.

MenuMobile-closed.png

Menu Macro

The menu application uses the menu macro to generate the menus. The menu macro can be used outside the menu application, for instance to create a menu inside the content of a wiki page.

Usage

{{menu id="..." type="..."}}
....content here...
{{/menu}}

The macro content supports any wiki syntax but you can create menus using just lists and links. You can also put icons before menu items, as you can see in the example below.

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:

* ----

Leaving the list item completly empty doesn't work due to the way the rendering engine works.

Parameters

NameOptionalAllowed valuesDefault valueDescription
idyesValid HTML IDEmpty StringOptional menu identifier that will be set on the HTML element that wraps the menu. You can use this identifier in JavaScript code to access the menu DOM or in functional tests to assert the menu items.
typeyeshorizontal, verticalhorizontalThe optional menu type determines the menu appearance and behaviour. The supported values are: horizontal (default value) and vertical.

The value of the type parameter is used as a CSS class name on the menu container and so it can accept various 'modifiers' (i.e. additional class names):

  • fixedWidth, used in combination with horizontal (see the example below), is needed 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 fixed width.
  • collapsible, makes a vertical menu collapsible (requires JavaScript)
  • open, makes a collapsible vertical menu expanded by default (when the page is loaded)

Examples

The following examples are not limited to the Menu macro: they are valid for the Menu Application too. You just have to copy the content of the Menu macro from the example to the "Menu Structure" field in Inline edit mode (Source tab).

Horizontal Menu

{{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}}

Vertical Menu

{{menu type="vertical collapsible open"}}
{{include reference="Space.PageHoldingMenuContent" /}}
{{/menu}}

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}}

hierarchyPanel.png

Check Access Rights

You can use the Velocity Macro to check access right on the menu entries:

{{menu type="horizontal"}}
{{velocity}}
#if ($services.security.authorization.hasAccess('edit', 'Path.To.Specs'))
* Edit Specs
** [[Feature A>>Path.To.Specs.A]]
** [[Feature B>>Path.To.Specs.B]]
#end
* Applications
#if ($services.security.authorization.hasAccess('view', 'Blog.WebHome'))
** [[image:icon:transmit Blog>>Blog.WebHome]]
#end
** [[image:icon:application_view_tile Dashboard>>Dashboard.WebHome]]
* Take a Tour
** [[Basic Features>>]]
#if ($hasAdmin)
** [[Advanced Features>>]]
#end
{{/velocity}}
{{/menu}}

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-menu-ui 13.4):

Tags:
    

Get Connected