Web UI modules

Web UI plugin modules allow you to insert links, tabs, and sections of links into the Confluence web interface. They're not widely used on their own, but when combined with Struts modules 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, 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 they are displayed.

Locations

In a number of places in the Confluence UI, there are lists of links representing operations relevant to the content being viewed.

Note that the descriptions in the following tables 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 customize:

Pages, blogs, and comments

Editor

Users

Labels

Spaces

Global

Administration Console

• Locations marked as 'themeable' can be moved around, reformatted, or omitted by Theme module. The descriptions in the tables refer to where they are located in the default theme.
• Locations marked as 'sectioned' require that web items are 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.

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:

1
2
<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:

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

The previous example creates 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 are already defined by Confluence or by other installed plugins.

Take a look at full configuration of Web section plugin modules.

Web sections in Confluence 

The following diagrams illustrate the web sections available in the Confluence drop-down menus.

Web sections for location system.content.action

Web item definition

Here's a sample atlassian-plugin.xml fragment for a web item:

1
2
<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 full configuration of Web item plugin modules.

Q&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:

1
2
#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. 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 core use.

Once again, we don't recommend this as you end up with plugins that are only useful in your own themes. At least try to provide an alternative set of UI modules for people who use other themes and still want to access the same functionality. You can, for example, define alternative UI plugin modules that place your functions in Confluence standard locations, but have a <condition> that disables them in favor of your custom locations if your theme is 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:

1
2
#applyDecorator("root")
    #decoratorParam("helper" $action.helper)
    #decoratorParam("mode" "view")
    #decoratorParam("context" "page")

    <!-- some stuff... -->

#end

If you write a plugin that is to be added as another item in the page tabs, your Velocity file for that action
needs to have a similar decorator directive around it:

1
2
#applyDecorator("root")
    #decoratorParam("helper" $action.helper)
    #decoratorParam("mode" "myPluginKey")
    #decoratorParam("context" "page")

    <!-- some stuff... -->

#end

Note that you should put your web item plugin key as the 'mode'. This way, Confluence will make sure that the correct tab is highlighted as the active tab when people view your action.
Also notice that in some cases, such as the Browse Space tabs, you may have to use context instead of mode.

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

1. In the atlassian-plugin.xml file, do the following:

   1
   2
   <!--Make sure each name is unique-->
          <resource type="i18n" name="i18n-viewreview"
   location="resources/ViewReviewAction" />
   

2. In the Java do this:

   1
   2
   //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;
      }
   

3. Use a normal properties file and locate it as follows:

• If we talk 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 have XYZAction.java, then XYZAction.properties can live in the same directory. You will 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.

Related topics

• Web section plugin module.
• Web item plugin module.
• Writing Confluence plugins.