Web UI Plugins

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.

On this page:

Sections and Items
Locations
Web Section Definition
Web Item Definition
Q and A

How do I make use of sections or web items in my own themes?
Can I create new locations for web UI plugins in my own themes?
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?
My web UI link isn't appearing when I use the Adaptavist Theme Builder plugin - why?
The breadcrumb trail for my web UI administration/space administration/tab plugin is showing the class name - how do I fix it?

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, in a 'section'.

Web items and 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.

Please be aware that the Descriptions below relate to the default Confluence theme. Bold text used in each description relates to a component on the product interface.

These are the locations that you can customise:

Location key	Description	Availability
Common Locations
Page-related
system.attachment	The links on the right of an Attachments list	2.8
system.comment.action	The links within each comment listed at the end of pages and blogs. The sections include the primary section on the lower-left of a comment (i.e. the Edit, Remove and Reply links) and the secondary section on the lower-right (i.e. the Permanent link icon)	2.8
system.content.action	The menu items on the Tools drop down menu available on pages and blogs. The sections of this menu include primary, marker, secondary and modify	2.8
User-related
system.profile	The tabs above user profile views	2.2
system.profile.view	These links are only visible to Confluence administrators and appear either beneath views of user profiles without personal spaces or beneath their own profile view. For example, Administer User	2.9
system.user	The menu items on the 'username' drop down menu available in the top bar of all pages. The sections of this menu include user-preferences, user-content and user-operations	2.8
Other
system.content.add	The menu items in the Add drop down menu available in pages, blogs and areas of the Space Admin and other Browse Space tabs. The sections of this menu include space and page	2.8
system.dashboard	The action section on the lower-left of the global dashboard. This section appears below the Spaces list on this dashboard	2.10.2
system.labels	The View sub-categories of the global All Labels / Popular Labels area	2.2
Space Admin and other Browse Space tabs
system.space	The Space Admin and other Browse Space tabs	2.2
system.space.actions	In versions of Confluence prior to and including version 2.9, these action icons appear in the top-right of most space-related views. However, from Confluence 2.10, this location key has been deprecated and has been superseded by 'system.content.add'	2.2
system.space.admin	The links in the left-hand menu of the Space Admin tab area	2.2
system.space.advanced	The links in the left-hand menu of the Advanced tab area	2.2
system.space.labels	The View sub-categories of the Labels tab area	2.2
system.space.pages	The View sub-categories of the Pages tab area	2.2
Administration Console
system.admin	The links in the left-hand menu of the global Administration Console	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 does not. 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 Section Definition

You may choose to create your own web sections or add to Confluence's predefined ones, if it makes logical sense to do that.

Here is a sample atlassian-plugin.xml fragment 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>

Here is another sample:

<web-section key="page" name="Add Page Content" location="system.content.add" weight="200">
    <label key="page.word" />
</web-section>

The above example will create a new section on the 'Add' menu. You can then add a web item in the section. The location of this section depends on the relative weight compared to the other sections that have already been defined by Confluence or by other installed plugins.

Take a look at the full configuration of Web Section plugin modules.

The diagrams below illustrate the web sections available in the Confluence dropdown menus.

Web sections for location system.content.action

Web sections for location system.content.add

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=$space.key</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>

Take a look at the full configuration of Web Item plugin modules.

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:

#set ($webInterfaceContext = $action.webInterfaceContext)
#foreach ($item in $action.webInterfaceManager.getDisplayableItems("system.space", $webInterfaceContext))
    <li><a href="$item.link.getDisplayableUrl($req, $webInterfaceContext)" #if ($context == $item.key) class="current" #end>
        $item.label.getDisplayableLabel($req, $webInterfaceContext)
    </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'.

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 in-built menulink location 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?

In the 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 file and locate it as follows:

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:
Define a resource in the atlassian-plugin.xml and tell it to live wherever you want. The standard is resources.

In the source: etc/resources
In the jar: resources/

The property that handles the breadcrumb has to be the fully qualified name of the class plus .action.name

So, for a SharePointAdmin property you might use: com.atlassian.confluence.extra.sharepoint.SharePointAdmin.action.name=SharePoint Admin

Web UI Plugins

Sections and Items

Locations

Web Section Definition

Web Item Definition

Q and A

How do I make use of sections or web items in my own themes?

Can I create new locations for web UI plugins in my own themes?

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?

My web UI link isn't appearing when I use the Adaptavist Theme Builder plugin - why?

The breadcrumb trail for my web UI administration/space administration/tab plugin is showing the class name — how do I fix it?

In the atlassian-plugin.xml:

In the java:

Use a normal properties file and locate it as follows:

RELATED TOPICS

Labels

Children (2)

Comments (21)

Dan Hardiker says:

Mike Cannon-Brookes says:

Dan Hardiker says:

Laura Kolker says:

Dan Hardiker says:

Dan Hardiker says:

Michelle A. Hoyle says:

Jonathan Nolen says:

Laura Kolker says:

Laura Kolker says:

Jean Marois says:

Jean Marois says:

Laura Kolker says:

Jean Marois says:

Laura Kolker says:

Anonymous says:

Roberto Dominguez says:

Shannon Krebs says:

Ming Giet Chong says:

Thomas Junghans says:

Anonymous says: