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. Activity Stream Plugin
  4. annotation
  5. attachment
  6. CKEditor
  7. comment
  8. Document Tree Macro
  9. edit
  10. Error Message macro
  11. export
  12. Extension Manager
  13. Extension module
  14. Flamingo skin
  15. global group
  16. global user
  17. Groovy event listener
  18. Groovy module
  19. group
  20. import
  21. Info macro
  22. java macros
  23. MySQL
  24. nested page
  25. network
  26. Office Importer
  27. page
  28. RSS
  29. search
  30. skin
  31. SOLR
  32. statistics
  33. Success Message macro
  34. syntax
  35. user
  36. user profile
  37. velocity macros
  38. Warning macro
  39. wiki
  40. Wiki Application
  41. wiki macro
  42. wysiwyg
  43. XWiki Applications
  44. xwikiattachment_archive table
  45. xwikiattachment_content table
  46. xwikiattachment table
  47. xwikiattrecyclebin table
  48. xwikiproperties table

[Display all tags from this space]

External Links