From version 1.1 >
edited by Vincent Massol
on 2013/09/05
To version < 2.1 >
edited by Ecaterina Moraru (Valica)
on 2014/02/26
>
Change comment: Draft

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.evalica
Content
... ... @@ -1,3 +1,70 @@
1 1  {{todo}}
2 2  Explain how to use existing extension points and how to create new ones based on examples.
3 3  {{/todo}}
4 +
5 +{{box cssClass="floatinginfobox" title="**Contents**"}}
6 +{{toc start='2'/}}
7 +{{/box}}
8 +
9 +== Introduction to Interface Extensions and Extension Points ==
10 +
11 +User Interface Extensions (abbreviated as UIX or IX) are used in order to provide a way to alter the content of existing interface elements. This functionality was added in version 4.2 and is documented in the [[UI Extension Module>>extensions:Extension.UIExtension Module]].
12 +
13 +The main use case Interface Extensions try to fix is the need for applications (like Blog, Watchlist, etc.) to insert custom content in already existing interface components (like panels, menus, layout, etc.).
14 +
15 +Let's take an example: We developed an application called 'Hello World' and we want to provide a link to it inside the 'Applications' panel.
16 +There are two questions that need to be answered:
17 +* where we insert? - this is the Extension Point
18 +* what we insert? - this is the UI Extension (IX)
19 +
20 +=== About Extension Points ===
21 +
22 +Extensions Points specify where the new content is about to be inserted. Is like a hoof defined in the interface where Interface Extensions are gathered.
23 +For our example, we need to know the extension point ID for the 'Applications' panel. That is '##org.xwiki.platform.panels.Applications##'.
24 +
25 +There is a list of [[available extension points>>platform:ExtensionPoint.WebHome]] where we can add functionality, but we can also manually define new extension points.
26 +
27 +=== About Interface Extensions ===
28 +
29 +All the IXs provided for a given Extension Point are displayed in that location.
30 +For our example, if we want to add a new link in the 'Applications' panel, we need to create a new IX that uses the '##org.xwiki.platform.panels.Applications##' extension point. IXs are stored as standard XObjects, instances of ##XWiki.UIExtensionClass##. For our IX we will need to provide the label, target and icon parameters, in order to be properly displayed in the panel.
31 +
32 +Read the documentation on [[how to add an IX>>extensions:Extension.UIExtension Module||anchor='HWritingasimpleUIExtension']] inside the 'Applications' panel.
33 +
34 +== Adding your own Extension Point ==
35 +
36 +Your UIExtension can define its own extension points, where other extensions can plug in. Here is an example of velocity code to include in your extension in order to make it an entry point for others:
37 +
38 +* Without parameters:
39 +
40 +{{code language="velocity"}}
41 +{{velocity}}
42 +#foreach ($extension in $services.uix.getExtensions("my.new.extension.point"))
43 + $services.rendering.render($extension.execute(), 'xhtml/1.0')
44 +#end
45 +{{/velocity}}
46 +{{/code}}
47 +
48 +* Display the parameters:
49 +
50 +{{code language="velocity"}}
51 +{{velocity}}
52 +#set ($extensions = $services.uix.getExtensions('my.new.extension.point', {'sortById' : ''}))
53 +#foreach ($extension in $extensions)
54 + $extension.parameters.label
55 +#end
56 +{{/velocity}}
57 +{{/code}}
58 +
59 +* Test the parameter for a particular value:
60 +
61 +{{code language="velocity"}}
62 +{{velocity}}
63 +#foreach ($extension in $services.uix.getExtensions("my.new.extension.point"))
64 + #if ($extension.getParameters().get('parameter_name') == 'expected_value')
65 +
66 + {{html clean=false}}$services.rendering.render($extension.execute(), 'xhtml/1.0'){{/html}}
67 + #end
68 +#end
69 +{{/velocity}}
70 +{{/code}}

Get Connected