UIExtension Module

The UIExtension Module provides an API for adding User Interface Extensions to XWiki.

UI Extension Filters

UI Extension filters are passed to the API through a Map in order to exclude some results from the list of retrieved extensions. The available filters are:

  • exclude - excludes UIExtensions from a list, identified by their ID.
  • select - selects only some UIExtensions from a list (defined manually), identified by their ID. 
  • sortByCustomOrder - sorts a list of UIExtensions by following a custom order strategy. If some extension IDs are not passed through the filter, they will be placed at the end of the list.
  • sortById - sorts a list of UIExtensions by ID.
  • sortByParameter - sorts a list of UIExtensions by the value of their parameters. The values of the chosen parameters must be String.


$services.uix.getExtensions('module.extensionPointId', { "exclude" : "module.extensionToExclude",
"sortByParameter" : "parameterKey" })

Extension Points

Extensions Points (UIXP) specify where the new content is about to be inserted and are created using the UIExtensionScriptService as follows: $services.uix.getExtensions('module.extensionPointId')

XWiki already made available 6 Extension Points:

  • Add Application UIXP
  • After Header UIXP
  • Left Panels UIXP
  • Right Panels UIXP
  • More Applications UIXP
  • Search Provider UIXP


CategoryExtension IDExtension ContentExtension Parameters
Add Application UIX"Applications" panelorg.xwiki.platform.panels.ApplicationsNo content expected
  • label
  • target
  • targetQueryString
  • icon       
After Header UIXPage layoutorg.xwiki.platform.template.header.afterThe content to be injected after the page header in wiki syntaxNo parameters expected
Left Panels UIXPanelsplatform.panels.leftPanelsNo content expectedNo parameters expected
Right Panels UIXPanelsplatform.panels.rightPanelsNo content expectedNo parameters expected
More Applcations UIX"Applications" panelorg.xwiki.platform.panels.Applications.moreNo content expected
  • label
  • target
  • targetQueryString
  • icon  
Search Provider UIXSearchorg.xwiki.platform.searchNo content expected
  • label
  • admin
  • search

Add Application UIXP

The Add Application extension point is contributed by the Panels Application in order to add extensions to the "Applications" panel. 


To contribute an entry to the Applications panel, start by creating a new wiki page that includes the "XWiki.UIExtensionSheet" document: {{include reference="XWiki.UIExtensionSheet" /}}. Next, edit the document in "Objects" mode and add an object of type XWiki.UIExtensionClass:


The rule for an Extension ID is platform.panels.[nameOfYourApplication]Application like for instance platform.panels.blogApplication.

The Extension Point requires 3 parameters:

  • label - the label of the link that will be created
  • target - the target of the link that will be created (it must be a document reference)
  • targetQueryString - the query string to add to the URL for the target document
  • icon - the icon that will be put in the link; it must be a reference to an 16x16 image in xwiki/2.1 syntax. Currently, the Applications panel uses the new Icon Theme Application. 

The below image shows an Applications panel entry for the Blog Application.


After Header UIXP

The After Header extension point is contributed in the templates/global.vm Velocity template and allows to add content (like for instance a Navigation Menu) below the page header, just under the logo:

<div class="clearfloats"></div>
  #foreach ($uix in $services.uix.getExtensions('org.xwiki.platform.template.header.after'))
    $services.rendering.render($uix.execute(), 'xhtml/1.0')

Below there is an example of how to create an Applications panel entry using the After Header extension point and the Menu Application.


The result will then be


with a corresponding entry and icon in the Applications panel.


Left Panels UIXP

The Left Panels extension point was contributed in the templates/leftpanels.vm Velocity template and allows adding panels to the left panel column:

#if($showLeftPanels == "1" || $request.getParameter("forceLeftPanels"))
<div id="leftPanels" class="panels left panel-width-$!{leftPanelsWidth}"#if($showLeftPanels != "1" && $request.getParameter("forceLeftPanels")) style="display: none;"#end>
## Global Variable
#set($xwikiPanelWidth = $leftPanelsWidth)
#set($panelUixs = $services.uix.getExtensions('platform.panels.leftPanels'))
#foreach($panelUix in $panelUixs)
  ## We need to set this because the panelheader macro used in panels needs it
  #set($paneldoc = $xwiki.getDocument($panelUix.getId()))
  #if($paneldoc && $!xwiki.hasAccessLevel('view', $paneldoc))
  $services.rendering.render($panelUix.execute(), "xhtml/1.0")
#set($xwikiPanelWidth = "Medium")

Since this extension is only a bridge, it is not meant to be implemented. This is the reason why, in order to add a panel to the left column you should use the wiki administration page.

Right Panels UIXP

The Right Panels extension point was contributed in the templates/rightpanels.vm Velocity template and allows adding panels to the right panel column:

#if($showRightPanels == "1" || $request.getParameter("forceRightPanels"))
<div id="rightPanels" class="panels right panel-width-$!{rightPanelsWidth}"#if($showRightPanels != "1" && $request.getParameter("forceRightPanels")) style="display: none;"#end>
#set($panelUixs = $services.uix.getExtensions('platform.panels.rightPanels'))
## Global Variable
#set($xwikiPanelWidth = $rightPanelsWidth)
#foreach($panelUix in $panelUixs)
  ## We need to set this because the panelheader macro used in panels needs it
  #set($paneldoc = $xwiki.getDocument($panelUix.getId()))
  #if($paneldoc && $!xwiki.hasAccessLevel('view', $paneldoc))
  $services.rendering.render($panelUix.execute(), "xhtml/1.0")

Similarly to the Left Panels extension point, the Right Panels UIX is only a bridge and it is not meant to be implemented.

More Applications UIXP

The More Applications extension point adds items to the Application Panel that are visible only when clicking the "More Applications" link. In the image below, you can see the Applications panel entry for App Within Minutes:


Search Provider UIXP

The Search Provider extension point was contributed by the search application and allows to add a search provider. In XWiki, the Search Provider is used:

  • by the Search bar to direct the user to the page provided by the Search extension point


  • by the Search engine configuration in the wiki preferences page in order for an administrator to select which Search engine to use: Solr, Lucene or Database


  • by the Search engine administration UI to offer specific Search configuration options for the current provider



  • label - the name of the search provider (Lucene, Solr)
  • admin - the document reference containing configuration options
  • search - the search page to redirect to when the user submits a search query

In the image below you can see an example illustrating the Solr search provider extension point:



1. Add your own extension point without parameters:

#foreach ($extension in $services.uix.getExtensions("xwiki.platform.customEP"))
  $services.rendering.render($extension.execute(), 'xhtml/1.0')

2. Display the parameters of an extension point:

#set ($extensions = $services.uix.getExtensions('xwiki.platform.customEP', {'sortById' : ''}))
#foreach ($extension in $extensions)

3. Test a parameter for an expected value:

#foreach ($extension in $services.uix.getExtensions("my.new.extension.point"))
 #if ($extension.getParameters().get('parameter_name') == 'expected_value')

 {{html clean=false}}$services.rendering.render($extension.execute(), 'xhtml/1.0'){{/html}}


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space