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

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

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. 

ApplicationsPanel.png

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:

UIExtensionClassObject.png

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.

BlogApplicationPanelEntry.png

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> 

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

AfterHeaderUIX.png

The result will then be

AfterHeaderUIXResult.png

with a corresponding entry and icon in the Applications panel.

AfterHeaderUIXPanel.png

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")

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

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:

AppWithinMinutesUIX.png

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

    SearchBarUIX.png

  • 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

    SearchConfigurationUIX.png

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

    SearchAdministrationUIX.png

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:

SolrSearchProvider.png

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

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

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

 

Related Pages

Search this space

 

Most popular tags

Failed to execute the [groovy] macro
  1. access rights
  2. activity stream
  3. annotation
  4. attachment
  5. comment
  6. Document Tree Macro
  7. export
  8. Extension Manager
  9. Flamingo skin
  10. global user
  11. Groovy event listener
  12. group
  13. nested page
  14. search
  15. skin
  16. syntax
  17. user
  18. user profile
  19. velocity macros
  20. wiki
  21. wysiwyg
  22. XWiki Applications
  23. xwikiattachment_archive table
  24. xwikiattachment table
  25. xwikiattrecyclebin table
  26. xwikiproperties table

[Display all tags from this space]