Hide last authors
Ecaterina Moraru (Valica) 2.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc start='2'/}}
3 {{/box}}
4
5 == Introduction to Interface Extensions and Extension Points ==
6
Ecaterina Moraru (Valica) 3.1 7 User Interface Extensions (abbreviated as UIX) 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]].
Ecaterina Moraru (Valica) 2.1 8
9 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.).
10
11 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.
12 There are two questions that need to be answered:
Vincent Massol 4.1 13
Ecaterina Moraru (Valica) 3.1 14 * where we insert? - this is the Extension Point (UIXP)
15 * what we insert? - this is the UI Extension (UIX)
Ecaterina Moraru (Valica) 2.1 16
17 === About Extension Points ===
18
Ecaterina Moraru (Valica) 3.1 19 Extensions Points (UIXP) specify where the new content is about to be inserted. Is like a hoof defined in the interface where Interface Extensions are gathered.
Ecaterina Moraru (Valica) 2.1 20 For our example, we need to know the extension point ID for the 'Applications' panel. That is '##org.xwiki.platform.panels.Applications##'.
21
22 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.
23
24 === About Interface Extensions ===
25
Ecaterina Moraru (Valica) 3.1 26 All the UIXs provided for a given Extension Point are displayed in that location.
27 For our example, if we want to add a new link in the 'Applications' panel, we need to create a new UIX that uses the '##org.xwiki.platform.panels.Applications##' extension point. UIXs are stored as standard XObjects, instances of ##XWiki.UIExtensionClass##. For our UIX we will need to provide the label, target and icon parameters, in order to be properly displayed in the panel.
Ecaterina Moraru (Valica) 2.1 28
Vincent Massol 4.1 29 Read the documentation on [[how to add an UIX>>extensions:Extension.UIExtension Module||anchor="HWritingasimpleUIExtension"]] inside the 'Applications' panel.
Ecaterina Moraru (Valica) 2.1 30
31 == Adding your own Extension Point ==
32
33 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:
34
Vincent Massol 3.2 35 * Without parameters:(((
Ecaterina Moraru (Valica) 2.1 36 {{code language="velocity"}}
37 {{velocity}}
38 #foreach ($extension in $services.uix.getExtensions("my.new.extension.point"))
39 $services.rendering.render($extension.execute(), 'xhtml/1.0')
40 #end
41 {{/velocity}}
42 {{/code}}
Vincent Massol 3.2 43 )))
44 * Display the parameters:(((
Ecaterina Moraru (Valica) 2.1 45 {{code language="velocity"}}
46 {{velocity}}
47 #set ($extensions = $services.uix.getExtensions('my.new.extension.point', {'sortById' : ''}))
48 #foreach ($extension in $extensions)
49 $extension.parameters.label
50 #end
51 {{/velocity}}
52 {{/code}}
Vincent Massol 3.2 53 )))
54 * Test the parameter for a particular value:(((
Ecaterina Moraru (Valica) 2.1 55 {{code language="velocity"}}
56 {{velocity}}
57 #foreach ($extension in $services.uix.getExtensions("my.new.extension.point"))
58 #if ($extension.getParameters().get('parameter_name') == 'expected_value')
59
60 {{html clean=false}}$services.rendering.render($extension.execute(), 'xhtml/1.0'){{/html}}
61 #end
62 #end
63 {{/velocity}}
64 {{/code}}
Vincent Massol 3.2 65 )))
Ecaterina Moraru (Valica) 5.1 66
67 == Disabling some Extension Points ==
68
69 Until we fix [[XWIKI-13076>>http://jira.xwiki.org/browse/XWIKI-13076]], there is no 'clean' way to disable an UIX.
70
Ecaterina Moraru (Valica) 6.1 71 In order to disable a page having an ##XWiki.UIExtensionClass## object you can delete the page, delete the object, or use an invalid extension point ID.
Ecaterina Moraru (Valica) 5.1 72
73 For example, if you would want to remove "User Index" from the Drawer, you should:
Ecaterina Moraru (Valica) 6.1 74
75 * Identify the extension point used by the [[Drawer>>extensions:Extension.Flamingo Skin||anchor="HDrawer"]]. In our case this is ##[[org.xwiki.plaftorm.drawer>>xwiki:Documentation.DevGuide.ExtensionPoint.DrawerItem]]##.
76 * Identify all the pages that use this extension point. For this, you can use [[Search>>extensions:Extension.Solr Search Application]] to filter for documents that have ##Object Type## = ##UI Extension##. Make sure you have the "Display Hidden Pages" preference set to true, from the [[User Profile>>extensions:Extension.User Profile Application||anchor="HEditPreferences"]].
77 * You will get a list of such pages, like ##Applications.WebHome##, ##XWiki.UserIndexUIX##, ##XWiki.DocumentIndexUIX##, etc.
Ecaterina Moraru (Valica) 7.1 78 * Go to the ##XWiki.UserIndexUIX## page and from the [[Object Editor>>xwiki:Documentation.UserGuide.Features.PageEditing||anchor="HObjectseditingmode"]] change the “Extension Point ID" value from ##org.xwiki.plaftorm.drawer## ID to something else.
Ecaterina Moraru (Valica) 6.1 79 * Save the page and the Drawer entry should disappear.
Ecaterina Moraru (Valica) 8.1 80
81 In case you want to have conditional display for some entries, like showing "User Index" just for registered users, the ID needs to remain the valid one, but [[Velocity>>extensions:Extension.Velocity Macro]] can be used to write conditions in the ##Extension Content## property.

Get Connected