This page last changed on Mar 05, 2007 by jnolen.

Web UI plugin modules are available in Confluence 2.2 and later.
Web UI plugin modules allow you to insert links, tabs and sections of links into the Confluence web interface. They're not much use on their own, but when combined with XWork-WebWork Plugins they become a powerful way to add functionality to Confluence.

Sections and Items

Web UI plugins can consist of two kinds of plugin modules:

  • web-item modules define links that are to be displayed in the UI at a particular location
  • web-section modules define a collection of links to be displayed together

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.

Locations

In 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:

Location key Themeable? Sectioned? Description Availability
system.admin The links in the left-hand menu on the global administrative console 2.2
system.space The tabs in 'Browse Space' 2.2
system.space.admin The links in the left-hand menu on the space administrative tab 2.2
system.space.advanced The links in the left-hand menu on the space advanced tab 2.2
system.space.pages The 'sub-tabs' in Browse Space → Pages 2.2
system.space.labels The 'sub-tabs' in Browse Space → Labels 2.2
system.space.actions The action icons in the top-right of most space-related views 2.2
system.page The tabs for 'View Page' 2.2
system.page.actions The action icons in the top right of the page view (eg. Watch this page) 2.3
system.news The tabs for 'View News' 2.2
system.labels The 'sub-tabs' in the global label view 2.2
system.profile The tabs above the user profile 2.2
  • Those locations marked as being 'themeable' can be moved around, reformatted or omitted by Theme Plugins. The descriptions above refer to where they are located in the default theme.
  • Locations marked as being 'sectioned' require that web items be grouped under web sections. In sectioned locations, web items that are not placed under a section will not be displayed.
  • It is possible for themes to make any themeable locations sectioned, even when the default theme doesn't. We do not recommend this, as it would mean any plugin taking advantage of this would only be compatible with a particular theme.
Theme Compatibility
Themes based on Confluence versions prior to 2.2 will continue to function with Confluence 2.2, but will not be able to display any custom Web UI fragments until they are updated.

Web Item Definition

Here'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>
  • The key is the required plugin module key, which must be unique within the plugin. It is also used in the UI for determining which module is currently being displayed.
  • The name is a required displayable name for the module, only used in the plugin administrative UI
  • The section is the required location into which this web item should be placed. For non-sectioned locations, this is just the location key. For sectioned locations it is the location key, followed by a slash ('/'), and the name of the web section in which it should appear
  • The weight is required , and determines the order in which web items appear. Items are displayed top to bottom or left to right in order of ascending weight. (i.e. the 'lightest' weight is displayed first, the 'heaviest' weights sink to the bottom)
  • The label element is required, and is the i18n key that will be used to look up the textual representation and mouse-over text of the link.
  • The link element is required, and defines where the web item should link to. The contents of the link element will be rendered using Velocity, allowing you to put dynamic content in links. For more complex examples of links, see below.
  • The icon element is optional, and defines an icon to display with or as the link.
  • The condition element is optional, and defines a condition that must be satisfied for the web item to be displayed. If you want to 'invert' a condition, add an attribute 'invert="true"' to it. The web item will then be displayed if the condition returns false (not true).

Label elements

Label 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>
  • The parameters allow you to insert values into the label using Java's MessageFormat syntax.
  • Parameter names must start with param and will be mapped in alphabetical order to the substitutions in the format string.
  • Parameter values are rendered using Velocity, allowing you to include dynamic content

Link elements

Link elements may contain additional information:

<link linkId="editPageLink" accessKey="$helper.action.getTextStrict('navlink.edit.accesskey')">/pages/editpage.action?pageId=$helper.page.id</link>
  • The linkId is optional, and provides an XML id for the link being generated.
  • The accessKey is optional and provides an access key for the link being generated. The contents of this element will be rendered using Velocity, allowing you to generate an access key dynamically.
There is no standard way for Confluence to display a web item, so depending on where the item is being displayed, some information in the configuration may be ignored. For example themes may choose not to display the icon, or may choose to only display the icon. Similarly, the linkId and accessKey are only used in some locations.

Condition elements

Condition elements must contain a class attribute with the fully-qualified name of a Java class. The referenced class:

  • must implement com.atlassian.confluence.plugin.descriptor.web.Condition
  • must be able to be instantiated via a no-argument constructor
  • will be auto-wired by Spring before any condition checks are performed

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 Definition

Here'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>
  • key, name, weight, label and condition are all the same as web-item
  • location is required, and serves the same purpose as section in web-item, except that a section can not be contained within another section.
  • Web sections do not have links or icons.

Q and A

How 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.

In some cases, such as the browse space tabs, you may have to use "context" instead of "mode"

The label element is required, and is the i18n key that will be used to look up the textual representation and mouse-over text of the link.

If I add a menu item to the admin menu (through the system.admin key), and I give it the label key of "myPlugin.link.text" ... how do I provide a value for it? If I want to have the text resolve into multiple languages, can I do that too?

Posted by dhardiker@adaptavist.com at Apr 30, 2006 05:36

The above tells me lists the various areas I can link into (system.admin for example) but doesnt list the sections available ... there is only one in your example which is system.space.admin/looknfeel but doesn't list which others there are.

Posted by dhardiker@adaptavist.com at Apr 30, 2006 05:38

For reference, you can find the built in sections available in confluence-2.2-source/confluence/src/etc/java/plugins if you have source access, or confluence-2.2/confluence/WEBINF/classes/plugins if you have the dist. They are listed in the *-sections.xml files.

Posted by dhardiker@adaptavist.com at Apr 30, 2006 05:50

Mate - the value is simply provided in the i18n properties files with your plugin. Bundled as a <resource> type="i18n" from memory.

Posted by mike@atlassian.com at Apr 30, 2006 18:16

A ha!

An example of this can be seen on the JIRA:Report Plugin Module page ... a clearer example of i18n in plugins may be worth while for newbies, as even I had trouble figuring out what goes where. (Granted, I've not worked with any i18n implementation that I hadn't written myself though.)

Posted by dhardiker@adaptavist.com at May 01, 2006 03:54

So can I use this to replace the nasty hard-coded additions I had to make to confluence/template/includes/macros.vm? Every time I upgrade Confluence, I have to go back and manually reapply the following changes:

1) #macro (usernameLink $username): This is used to modify the usernameLink to include a clickable icon which takes you to the person's Guild Profile page in addition to the standard (and, for our purposes, mostly useless) Confluence user profile page.

Original Code
#macro (usernameLink $username)
#if ($username != "")
    #if ($action.getUserFullName($username))
        <a href="$!req.contextPath/display/~$generalUtil.
        doubleUrlEncode($username)">
        $action.getUserFullName($username)</a>
    #else
Changed Code
#macro (usernameLink $username)
#if ($username != "")
    #if ($action.getUserFullName($username))
        <a href="$!req.contextPath/display/PROFILE/
        $generalUtil.doubleUrlEncode($action.
        getUserFullName($username))" 
        title="Visit $action.getUserFullName($username)'s 
        Guild Profile page">
        <img src="$req.contextPath/images
        /icons/droplet_16.png" 
        height="16" width="16" 
        border="0" align="middle" alt="" /></a>
       <a href="$!req.contextPath/display/~$generalUtil.
       doubleUrlEncode($username)" 
       title="View $action.getUserFullName($username)'s 
       Confluence profile">
       $action.getUserFullName($username)</a>
    #else

2) usernavbar: added code to include guild profile page edit droplet and link to Java chat applet page.

Original Code
<a href="$req.contextPath/display/~$generalUtil.
doubleUrlEncode($user.name)">Profile</a> |
Changed Code
<a href="$req.contextPath/display/PROFILE/$generalUtil.
doubleUrlEncode($user.fullName)" title="Visit your Guild Profile 
page"><img src="$req.contextPath/images/icons/droplet_16.png" 
height="16" width="16" border="0" align="absmiddle" alt="" 
style="margin: 0 3px 0 0;" class="none" /></a><a 
href="$req.contextPath/display/~$generalUtil.
doubleUrlEncode($user.name)">Profile</a> | 
<a href="http://www.wowkindness.com/cgi-bin/chat/index.php?nick=
$generalUtil.doubleUrlEncode($user.fullName)" title="Multi-Chat">Chat</a> |

3) usernavbar: Added code to put inactive "Chat" link into nav bar when not logged in.

Original Code
<a href="$seraph.getLinkLoginURL($req)">Log In</a>
Changed Code
Chat |
            <a href="$seraph.getLinkLoginURL($req)">Log In</a>

It's a pain in the butt but I didn't see an easy way around it previously. Will this new UI plugin help at all?

Posted by eingang at May 09, 2006 06:19

Yep! This is exactly the usecase we built this feature for. It should do the trick.

Cheers,
Jonathan

Posted by jnolen at May 09, 2006 12:18

FYI: Looks like web ui plugin + resources don't work in 2.2

http://jira.atlassian.com/browse/CONF-6317

(Just a reference, as I spent way too much time poking at this.)

Posted by laura.kolker at Nov 10, 2006 06:51

Quote from above:

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. In some cases, such as the browse space tabs, you may have to use "context" instead of "mode"

I've found if I'm creating a new space tab, that I run into some difficulties here.
If I don't make the context equal to "space", then the tabs don't show.
But the space decorator (space.vmd) shows that it's the context == plugin.key that determines which tab is highlighted:

## line 29 in space.vmd
<li><a href="$item.link.getDisplayableUrl($req, $helper)" #if ($context == $item.key)
 class="current" #end>$item.label.getDisplayableLabel($req, $helper)</a></li>

Just for thoroughness, I checked setting the mode to my plugin key, and that appears to have no effect.

I've found the following JIRA issue,
http://jira.atlassian.com/browse/CONF-6853

which seems related, but no one's responded to Dan Hardiker's request for clarification on whether related space issues have been resolved.

In the meantime, I've got a work-around, which is more than a bit of kludge, but it'll do until I hear of a better solution.

//add this in the body of your velocity file
        <script type="text/javascript">
           function fixTab() {
             var tablist = document.getElementById('foldertab');
             for (var i = 0; i < tablist.childNodes.length; i++) {
                var liElement = tablist.childNodes[i];
                if (liElement.childNodes[0] == null) {
                   continue;
                }
                if (liElement.childNodes[0].href.match("something.unique.in.my.action.name")) {
                   liElement.childNodes[0].className = "current";
                   
                }
             }
           }
           fixTab();
        </script>
Posted by laura.kolker at Nov 16, 2006 07:32

I just thought of a better solution:

root.vmd shows the following

#elseif ($context.startsWith("space-"))           
## Space tabs (Friday afternoon hack)
      #applyInlineDecorator("space" $body $params)

So, all you have to do is make the plugin key start with space- (and still be unique, and then when you make the context equal to, the highlighting works correctly.

Posted by laura.kolker at Nov 16, 2006 07:37

I have a similiar issue with tabs added to the User Profile, but can't use the "simpler" hack, so I used a modified version of your previous solution:

<script type="text/javascript">
           function fixTab() {
             var tablist = document.getElementById('foldertab');
             for (var i = 0; i < tablist.childNodes.length; i++) {
                var liElement = tablist.childNodes[i];
                if (liElement.childNodes[0] == null) {
                   continue;
                }
                if (liElement.childNodes[0].href.match("/path/to/myplugin.action*")) {
                   liElement.childNodes[0].className = "current";
                }
                else { 
                   liElement.childNodes[0].className = "";
                }
             }
           }
           fixTab();
</script>

I added the else statement to make sure no other tab is set as the current.

Posted by marois at Dec 08, 2006 14:29

I forgot to explain why I need to unset the current tab. The global.vm will not display your page unless you set your decorator mode parameter to one of the existing tabs, i.e. view-profile, edit-profile, ... There is no else block in the profile context section.

#elseif ($context == "profile")
...
                    ##MODE - VIEW-PROFILE
                    #if ($mode == "view-profile")
...
                    ##MODE - EDIT-PROFILE || CHANGE-PASSWORD-PROFILE
                    #elseif ($mode == "edit-profile" || $mode == "change-password-profile")
...
                    #elseif ($mode == "configure-rss-feed" || $mode == "my-labels" || $mode == "edit-notifications-profile")
...
                    #elseif ($mode == 'drafts')

...
                    #end
          #elseif ($context == "labels")
...
Posted by marois at Dec 08, 2006 14:43

Condition elements must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
must implement com.atlassian.confluence.plugin.descriptor.web.Condition

This appears to be out of date as of Confluence 2.3.
Anyone know what the new class is?

Thanks
Laura

Posted by laura.kolker at Feb 16, 2007 17:28

I believe its actually been com.atlassian.confluence.plugin.descriptor.web.conditions.AbstractConfluenceCondition since at least 2.2.9.

Jean

Posted by marois at Feb 17, 2007 04:06

Hi Jean,

Thanks for the tip.

re: 2.2.9

Interesting. The Condition class was, however, still usable in 2.2.9
Perhaps it was deprecated at that time?

Laura

Posted by laura.kolker at Feb 19, 2007 13:46
Document generated by Confluence on Mar 22, 2007 21:00