General Actions:
XWiki Standard 9.8.1 Documentation » Programming Overview » XWiki Platform Modules Overview » UIExtension Module
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.
Example
$services.uix.getExtensions('module.extensionPointId', { "exclude" : "module.extensionToExclude",
"sortByParameter" : "parameterKey" })
"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
Definition
| Category | Extension ID | Extension Content | Extension Parameters | |
|---|---|---|---|---|
| Add Application UIX | "Applications" panel | org.xwiki.platform.panels.Applications | No content expected |
|
| After Header UIX | Page layout | org.xwiki.platform.template.header.after | The content to be injected after the page header in wiki syntax | No parameters expected |
| Left Panels UIX | Panels | platform.panels.leftPanels | No content expected | No parameters expected |
| Right Panels UIX | Panels | platform.panels.rightPanels | No content expected | No parameters expected |
| More Applcations UIX | "Applications" panel | org.xwiki.platform.panels.Applications.more | No content expected |
|
| Search Provider UIX | Search | org.xwiki.platform.search | No content expected |
|
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')
#end
</div>
#foreach ($uix in $services.uix.getExtensions('org.xwiki.platform.template.header.after'))
$services.rendering.render($uix.execute(), 'xhtml/1.0')
#end
</div>
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")
#end
#end
</div>
#end
#set($xwikiPanelWidth = "Medium")
<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")
#end
#end
</div>
#end
#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")
#end
#end
</div>
#end
<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")
#end
#end
</div>
#end
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
Parameters
- 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:
Examples
1. Add your own extension point without parameters:
{velocity}}
#foreach ($extension in $services.uix.getExtensions("xwiki.platform.customEP"))
$services.rendering.render($extension.execute(), 'xhtml/1.0')
#end
{{/velocity}}
#foreach ($extension in $services.uix.getExtensions("xwiki.platform.customEP"))
$services.rendering.render($extension.execute(), 'xhtml/1.0')
#end
{{/velocity}}
2. Display the parameters of an extension point:
{{velocity}}
#set ($extensions = $services.uix.getExtensions('xwiki.platform.customEP', {'sortById' : ''}))
#foreach ($extension in $extensions)
$extension.parameters.label
#end
{{/velocity}}
#set ($extensions = $services.uix.getExtensions('xwiki.platform.customEP', {'sortById' : ''}))
#foreach ($extension in $extensions)
$extension.parameters.label
#end
{{/velocity}}
3. Test a parameter for an expected value:
{{velocity}}
#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}}
#end
#end
{{/velocity}}
#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}}
#end
#end
{{/velocity}}