Confluence 2.9 : Web UI Plugins
This page last changed on May 19, 2008 by mryall.
Sections and ItemsWeb UI plugins can consist of two kinds of plugin modules:
Web items or web sections (referred to collectively as 'web fragments') may be displayed in a number of different ways, depending on the location of the fragment and the theme under which it is being displayed. LocationsIn a number of places in the Confluence UI, there are lists of links representing operations relevant to the content being viewed. These are the locations that you can customise:
Web Section DefinitionYou may choose to create your own web sections or add to Confluence's predefined ones (if it makes logical sense to). Here is a sample atlassian-plugin.xml fragment for a web-section: <web-section key="page" name="Add Page Content" location="system.content.add" weight="200"> <label key="page.word" /> </web-section> This will create a new section on the Add Menu where you can add a new web-item. The location of this section depends on the relative weight compared to the other sections that have already been defined by Confluence (or other installed plugins). The diagrams below illustrate the new web sections for the drop down menus.
Web Item DefinitionHere's a sample atlassian-plugin.xml fragment for a web item: <web-item key="spacelogo" name="Space Logo" section="system.space.admin/looknfeel" weight="40"> <label key="configure.space.logo" /> <link>/spaces/configurespacelogo.action?key=$helper.spaceKey</link> <icon height="16" width="16"> <link>/images/icons/logo_add_16.gif</link> </icon> <condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.NotPersonalSpaceCondition"/> </web-item>
Label elementsLabel elements may contain optional parameters, as shown below: <label key="navlink.attachments"> <param name="param0">$!helper.page.title</param> <param name="param1">$!helper.numberOfAttachments</param> </label>
Link elementsLink elements may contain additional information: <link linkId="editPageLink" accessKey="$helper.action.getTextStrict('navlink.edit.accesskey')">/pages/editpage.action?pageId=$helper.page.id</link>
Condition elementsCondition elements must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
For compatibility with Confluence 2.2 – 2.7, you should extend AbstractConfluenceCondition instead. However, this deprecated class will be removed in a future release. Condition elements can take optional parameters. These parameters will be passed in to the Condition's init() method as a Map of String key/value pairs after autowiring, but before any condition checks are performed. For example: <condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.PagePermissionCondition"> <param name="permission">edit</param> </condition> Multiple condition elements can be included in a single web item. If a web item contains multiple conditions, all conditions must be satisfied for the web item to be displayed. To invert a condition, add the attribute 'invert="true"' to the condition element. This is useful where you want to show the section if a certain condition is not satisfied. Web Section DefinitionHere's a sample atlassian-plugin.xml for a web section: <web-section key="mail" name="Mail" location="system.space.admin" weight="300"> <label key="space-mail" /> <condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.NotPersonalSpaceCondition"/> </web-section>
Q and AHow do I make use of sections or web items in my own themes?Take a look at how they are used in the default themes, you should be able to get a good idea of the necessary code. For example, here is some sample code from space.vmd #foreach ($item in $action.webInterfaceManager.getDisplayableItems("system.space", $action.remoteUser, $helper)) <li><a href="$item.link.getDisplayableUrl($req, $helper)" #if ($context == $item.key) class="current" #end> $item.label.getDisplayableLabel($req, $helper) </a></li> #end Can I create new locations for web UI plugins in my own themes?Yes. Just pick a new key for the location or section parameters of your plugin modules. By convention, you should probably use the standard 'inverted domain name' prefix so as not to clash with anyone else's plugins. We reserve all system.* locations for Confluence's core use. Once again, however, we don't recommend this as you end up with plugins that are only useful in your own themes. Try to at least provide an alternative set of UI modules for people who are using other themes and still want to access the same functionality. You could, for example, define alternative UI plugin modules that placed your functions in Confluence's standard locations, but have a <condition> that disabled them in favour of your custom locations if your theme was installed. If I create a Web Item that links to my custom action, how do I make it appear in the same tabs/context as the other items in that location?The best way is to look at the .vm file of one of the existing items in that location. You are most interested in the #applyDecorator directive being called from that file. For example viewpage.vm, which defines the "View" tab in the system.page location has the following #applyDecorator directive: #applyDecorator("root") #decoratorParam("helper" $action.helper) #decoratorParam("mode" "view") #decoratorParam("context" "page") <!-- some stuff... --> #end If you were writing a plugin that was destined to be added as another item in the page tabs, your Velocity file for that action would also have to have a similar decorator directive around it: #applyDecorator("root") #decoratorParam("helper" $action.helper) #decoratorParam("mode" "myPluginKey") #decoratorParam("context" "page") <!-- some stuff... --> #end Note that you should put you Web Item's plugin key as the "mode". This way, Confluence will make sure that the correct tab is highlighted as the active tab when people are viewing your action.
My Web UI link isn't appearing when I use the Adaptavist Theme Builder plugin - why?Theme Builder uses completely customisable navigation and as such can't automatically display Web UI links because this would likely lead to duplication of many other, more common links. You can, however use the {menulink} macro to insert any Web UI link using the following notation: {menulink:webui|location=XXXX|key=YYYY}webui link{menulink} Theme Builder 2.0.8 and above now supports a growing number of third party plugins as standard - for more information see the online documentation. If you have a publicly available plugin and want an inbuilt menulink locaiton for it, please contact Adaptavist. The breadcrumb trail for my web ui administration/space administration/tab plugin is showing the class name - how do I fix it?atlassian-plugin.xml<!--Make sure each name is unique--> <resource type="i18n" name="i18n-viewreview" location="resources/ViewReviewAction" /> In the java//in an action I18NBean i18NBean = getI18n(); //or in a macro or other sort of plugin ThemeHelper helper = this.getHelper(); ConfluenceActionSupport action = (ConfluenceActionSupport) helper.getAction(); Locale locale = action.getLocale(); I18NBean i18nBean = i18NBeanFactory.getI18NBean(locale); //and public void setI18NBeanFactory(I18NBeanFactory i18NBeanFactory) { this.i18NBeanFactory = i18NBeanFactory; } Use a normal properties filere: where the properties file goes If we're talking about actions: the properties file with the same name as the relevant action can go in the same directory as the action: So, if you had XYZAction.java, then XYZAction.properties could live in the same directory. And you would not have to do anything in the atlassian-plugin.xml file. If you don't want it to live there, or if you're not talking about an action, then you define a resource in the atlassian-plugin.xml and tell it to live whereever you want, the standard appears to be resources. In the source it would be etc/resources. In the jar it would be resources/ The property that handles the breadcrumb has to be the fully qualified name of the class plus .action.name So, for the SharePointAdmin property I used: com.atlassian.confluence.extra.sharepoint.SharePointAdmin.action.name=SharePoint Admin |
![]() |
Document generated by Confluence on Aug 07, 2008 19:08 |