Menu Application
 | Menu application |
| Type | XAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard (9.4-rc-1+) |
Table of contents
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).
the menu is available in the Administration under the "Look & Feel" section.
Menu Usage
You can create a new menu or edit an existing one.
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
You can also specify a visibility scope for the menu:
- Current User (default)
- Current Wiki
- Global
Note that the wiki and global scopes require admin or programming rights.
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.
Here's how the menu looks like if it has multiple levels:
If you choose to display the menu in a side panel it will be displayed vertically. You can collapse/expand each sub-menu.
, 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
, the horizontal menu layout has been improved on Mobile by introducing menu burgers.
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
....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
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| id | yes | Valid HTML ID | Empty String | Optional 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. |
| type | yes | horizontal, vertical | horizontal | The 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
* [[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§ion=XWiki.AddExtensions"]]
* [[Documentation>>http://www.xwiki.org]]
** [[Syntax Help>>XWiki.XWikiSyntax||queryString="xpage=print"]]
** Take a Tour
*** [[Basic Features>>]]
*** [[Advanced Features>>]]
{{/menu}}
Vertical Menu
{{include reference="Space.PageHoldingMenuContent" /}}
{{/menu}}
Hierarchy Panel
{{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}}
Check Access Rights
You can use the Velocity Macro to check access right on the menu entries:
{{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:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- 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 16.7.1):
- org.webjars:requirejs 2.3.7
- org.webjars:jquery 3.7.1
- org.xwiki.platform:xwiki-platform-rendering-wikimacro-store 16.7.1
- org.xwiki.platform:xwiki-platform-rendering-macro-velocity 16.7.1
- org.xwiki.platform:xwiki-platform-appwithinminutes-ui 16.7.1
- org.xwiki.platform:xwiki-platform-uiextension-ui 16.7.1
- org.xwiki.platform:xwiki-platform-rendering-macro-include 16.7.1
- org.xwiki.platform:xwiki-platform-rendering-macro-code 16.7.1
- org.xwiki.platform:xwiki-platform-livedata-macro 16.7.1
- org.xwiki.platform:xwiki-platform-livedata-livetable 16.7.1
- org.xwiki.platform:xwiki-platform-panels-ui 16.7.1
- org.xwiki.platform:xwiki-platform-display-macro 16.7.1
