UIExtension Module

Version 14.1 by Vincent Massol on 2013/09/05 08:45

cogDefines a way to add User Interface Extensions to the XWiki platform
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise

Description

Introduction

XWiki has evolved into a platform made of a collection of modules. The User Interface of those modules are made of wiki pages. Those modules can provide:

Writing a simple UI Extension

In this example we will write an extension for the Applications Panel UI Extension Point (ID: org.xwiki.platform.panels.Applications).

To create a UI Extension you need to:

Create a new document, for example Main.HelloWorldUIExtension

UIExtension-Step1.png

Switch to the object editor

UIExtension-Step2.png

Add a XWiki.UIExtensionClass object to it

UIExtension-Step3.png

Fill the information required by the extension point, you need to refer at the Extension Point (EP) documentation at this point.
In this example the extension point requires the following:

  • Extension Point ID: in our example org.xwiki.platform.panels.Applications
  • Extension Name: any name would be fine but we're following a rule for this EP "platform.panels." + the name of your extension, in our case "HelloWorld"
  • Extension Content: the EP doesn't require any here
  • Extension Parameters: here's the important part, the EP 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 reference to a document
    • icon: the icon that will be put in the link, it must be a reference to an image, to look good this image must be 16 pixels in both height and width. 
  • Extension Scope: defines where and for who your extension will appear: only in the current wiki (default value), globally (for a whole wiki farm) or only for the current user (ie. you, the user who wrote the extension)

UIExtension-Step4.png

Save the document

UIExtension-Step5.png

You can now see a new entry in the Applications Panel

UIExtension-Step6.png

Extension Points

Extension Points are "declared" or "created" through a call to the UIX api :

$services.uix.getExtensions('module.extensionPointId')

While they are easy to created you must remember that the Extension Point itself will be considered as an API. They must not be renamed or removed once they've been released.
Filters can be applied to the list of retrieved extensions, in order to exclude some of them for example. Filters are passed to the API through a Map :

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

The list of available filters is the following:

  • exclude : takes a list of UI Extension IDs as parameter. Those extensions won't be retrieved.
  • select : takes a list of UI Extension IDs as parameter. Only the listed extensions will be retrieved
  • sortByCustomOrder : takes a list of UI Extension IDs as parameter. The extensions will be in the same order as they've been listed, additional extensions will be put at the end of the list.
  • sortById : takes an empty string as parameter. The extensions will be ordered by their IDs, alphabetically.
  • sortByParameter : takes a parameter key as parameter. The extensions will be ordered by the value of this parameter, alphabetically. If all the parameter values appear to be numbers they will be numerically ordered.

Available UI Extension Points

Here is the exhaustive list of UI Extension Points (EP) provided by the XWiki Platform.

Page Layout

Extension Point: After Header

Allows you to add content (e.g. a navigation menu) after the page header (i.e. the region that contains the logo on the left and the search bar on the right, after the top menu bar).

Extension Point ID
org.xwiki.platform.template.header.after
Extension Name
Something to identify your extension.
Content
The content to be injected after the page header. Use wiki syntax.
Parameters
No parameters

Applications Panel

The Application Panel defines 2 EPs.

Extension Point: List of applications

This EP allows adding items in the Application Panel.

Extension Point ID
org.xwiki.platform.panels.Applications
Extension Name
The rule here is platform.panels.[nameOfYourApplication]Application, for example: platform.panels.blogApplication. This is important because extensions are ordered by name by this EP.
Content
not taken into account by the Extension Point
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 reference to a document
  • icon : the icon that will be put in the link, it must be a reference to an image, to look good this image must be 16 pixels in both height and width. 

Extension Point: More applications

This EP allows adding items in the Application Panel but those items are only visible when clicking the "More Applications" link.

Extension Point ID
org.xwiki.platform.panels.Applications.more
Extension Name
The extension name, for example platform.panels.newApplication. Extensions are ordered by name by this EP.
Content
not taken into account by the Extension Point
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 reference to a document
  • icon: the icon that will be put in the link, it must be a reference to an image, to look good this image must be 16 pixels in both height and width. 

Extension Point: Search Provider

Allows you to define a Search Provider. This extensions point is used for example:

  • in the Search Admin to let the user select which Search provider to use (Lucene, Solr, Database, etc).
  • by the Search bar itself to direct the user to the page provided by the Search extension point.
  • in the Search Admin UI to offer specific Search configuration options for this provider
Extension Point ID
org.xwiki.platform.search
Extension Name
Something to identify your extension.
Content
not taken into account by the Extension Point
Parameters
  • label: the name of the search provider (e.g. Lucene, Solr, etc)
  • admin: the document reference for offering specific Admin configuration options
  • search: the search page to redirect to when the user enter a search query in the search bar and submits it
Tags:
    

Get Connected