UIExtension Module
 | Defines a way to add User Interface Extensions to the XWiki platform |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Table of contents
Description
Introduction
XWiki is a platform made of a collection of Extensions. Extensions can contribute UI changes through:
The goal of UI Extensions is to offer another way to contribute some small UI changes without requiring to build a completely new Skin. More precisely, through the concepts of UI Extension Points/UI Extension, it allows Skins (and any Extensions) to provide places in the UI to let other Extensions contribute some custom content that will be inserted.
Terminology:
- UI Extension Points (known as UIXP): A place in the UI where Extensions can contribute custom content that will be inserted
- UI Extension (known as UIX): Some custom content to insert
To get an idea of UIXP, you can check the exhaustive list of existing UI Extension Points.
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
Switch to the object editor
Add a XWiki.UIExtensionClass object to it
Fill the information required by the UIXP (you need to refer to the UIXP 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)
- Asynchronous rendering: Enabled or disable asynchronous rendering of the panel. Disabled by default.
- Cached: Indicate if the result of the execution of the element should be cached. Disabled by default.
- Context elements: The context information required during the execution of the extension (current user, current document, etc.). It's also used to generate the cache key.
Save the document
You can now see a new entry in the Applications Panel
More Details
When you contribute a new UIX, you should know the following:
- The UIX Content can contain wiki syntax (in the syntax of the page holding the UIX xobject)
- The UIX Parameters can contain Velocity scripts (each parameter's value is evaluated with Velocity). For example the following would work:label=$services.localization.render("key")
UI Extension Points
In Velocity
UIXP are "declared" or "created" through a call to the UIX api:
While they are easy to create, you must remember that the UIXP itself will be considered as an API. Thus, 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", "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.
In Java
You can use the component org.xwiki.uiextension.UIExtensionManager to gather UI extensions associated to a given UI extension point id.
private UIExtensionManager uixManager;
private void foo()
{
List<UIExtension> uixs = uixManager.get("module.extensionPointId");
}
In a wiki content
XWiki 14.0+
A macro is available to gather and execute UI extensions:
- uiextensions: create a UI extension point (gather and execute all the UI extensions associated to a specific extension point id)
XWiki 14.4.4+, 14.10.5+, 15.1+
A macro is available to execute a specific UI extension:
- uiextension: execute a specific UI extension
