User Interface plugin modules
Build Lifecycle plugin modules
Notification plugin modules
System plugin modules

Web Item module

Available:

Bamboo 1.0 and later

Description

The Web Item module allows you to define a link in the Bamboo system. (Usually in some form of menu). Currently, you can use the web-item to add links to the following locations:

Menu

Section

Dashboard Tabs (since 3.0)

system.dashboard/dashboard

Plan Sub Menu (tabs on the View Plan page)

chain.subMenu/chain

Plan Results Sub Menu (tabs on the View Plan Result page)

chainResults.subMenu/chainResults

Job Sub Menu (tabs on the View Job page)

build.subMenu/build

Job Results Sub menu (tabs on the View Job Result page)

results.subMenu/results

Plan Actions Menu (since 3.3)

chain.actions/chainActions

Plan Result Actions Menu (since 3.3)

chainResult.actions/chainResultActions

Job Actions Menu (since 3.3)

job.actions/jobActions

Job Result Actions Menu (since 3.3)

jobResult.actions/jobResultActions

Administration Menu

system.admin/plugins

User profile tabssystem.user/userconfig

When putting items in the Administration Menu, you can also add your own section to the menu (rather than using the suggested plugins section above). For more information see Web Section Module.

Bamboo-specific notes about Web Items

Module Parameters

Please take note of the following Bamboo-specific information that is relevant to the Module components described in the 'Configuration' section below.

Attributes:

  • key -- this is the unique identifier of the web-item, it is also used by Bamboo to give the link an id.
  • name -- in the plan sub menu and results sub menu this is used to determine if the current link (tab) is active
  • section -- the section is made of of the parent section's location followed buy the name of the parent section. In Bamboo this is used to retrieve the appropriate web-items for the menu. (see Web Section Module)
  • weight -- this is used to determine the order of the items on the page

Elements:

  • condition -- by implementing the com.atlassian.plugin.web.Condition class you can add rules to determine whether the link will be displayed or not.
  • label -- this will be displayed on the screen and can be plain text or a property key
  • link -- the link is the url the link will point to. It can be absolute or relative to Bamboo's context path

Both the link and the key id can make use of parameters passed to the page. For example:

<link>/build/viewBuildFiles.action?buildKey=${buildKey}</link>

where ${buildKey} is the parameter name.

Context Aware Navigation

In Bamboo 3.0 we have added the Plan Navigator. When moving between Jobs and the Plan (as well as Job Results and Plan Result), the navigator remembers your context i.e. which tab (Web Item) you are on and will attempt to keep you on the same tab. If you are adding a new tab to a page which has the Plan Navigator, you may also wish to manually define the corresponding Job/Plan/Result URL. You can find more information on how to do this on the XWork Plugin Module page.

Purpose of this Module Type

Web Item plugin modules allow plugins to define new links in application menus.

Configuration

The root element for the Web Item plugin module is web-item. It allows the following attributes and child elements for configuration:

Attributes

Name*

Description

class

The class which implements this plugin module and which is responsible for providing the web item's HTML.

In most cases you will not need to provide a custom class to generate the content,

as you can simply point to a static HTML file or a (Freemarker) template.

See the plugin framework guide to creating plugin module instances.

If you omit this attribute, you MUST provide a resource element and vice versa,

to ensure there is always exactly one source for the web panel's content.

state

 

Indicate whether the plugin module should be disabled by default (value='disabled') or enabled by default (value='enabled').

Default: enabled.

i18n-name-key

The localisation key for the human-readable name of the plugin module.

key

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.
1
2
<component-import 
  key="appProps" 
  interface="com.atlassian.sal.api.ApplicationProperties"/>

In the example, appProps is the key for this particular module declaration, for component-import, in this case.

name

The human-readable name of the plugin module.

Used only in the plugin's administrative user interface.

section

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.

system

Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins.

Default: false.

weight

 

Determines the order in which web items appear.

Items are displayed top to bottom or left to right in order of ascending weight.

The 'lightest' weight is displayed first, the 'heaviest' weights sink to the bottom.

The weights for most applications' system sections start from 100,

and the weights for the links generally start from 10.

The weight is incremented by 10 for each in sequence so that there is ample space to insert your own sections and links.

Default: 1000.

*key and section attributes are required.

Elements

The tables summarises the elements. The sections below contain further information.

Name*

Description

condition

Defines a condition that must be satisfied for the web panel 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).

conditions

 

Defines the logical operator type to evaluate its condition elements. By default 'AND' will be used.

Default: AND.

context-provider

Allows dynamic addition to the Velocity context available for various web panel elements (in XML descriptors only).

Currently only one context-provider can be specified per web panel.

description

The description of the plugin module. The 'key' attribute can be specified to declare a localisation key for the value instead of text in the element body.

I.e. the description of the web panel.

icon

Defines an icon to display with or as the link.

 Note: In some cases the icon element is required.

Try adding it if your web section is not displaying properly.

label

Is the i18n key that will be used to look up the textual representation of the link.
link

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.

param

Parameters for the plugin module. Use the 'key' attribute to declare the parameter key, then specify the value in either the 'value' attribute or the element body. This element may be repeated. An example is the configuration link described in Adding a Configuration UI for your Plugin.

This is handy if you want to use additional custom values from the UI. More below (Param).

resource

 

A resource element is used to provide a web item with content.

It can be used in a way similar to normal resources, using the resource's location attribute to point to a static HTML file or (Velocity) template file that is provided by the plugin's JAR file.

To differentiate between static HTML and Velocity templates that need to be rendered, always specify the type attribute.

It is also possible to embed the contents (both static HTML or velocity) directly in the atlassian-plugin.xml file by encoding it in the resource element's body and then omitting the location attribute.

Note that if you omit the resource element you MUST provide the module descriptor's class attribute, and vice versa, to ensure there is always exactly one source for the web panel's content.

styleClass

Defines an additional CSS class that will be added to this web item when it is rendered on the page.

Note that this value may be ignored in some situations.

tooltipIs the i18n key that will be used to look up the textual mouse-over text of the link.

*label and link elements are required.

Label Elements

Label elements may contain optional parameters, as shown below:

1
2
<label key="common.concepts.create.new.issue">
    <param name="param0">$helper.project.name</param>
</label>

Tooltip Elements

Tooltip elements have the same attributes and parameters as the label elements. See above.

Link elements may contain additional information:

1
2
<link linkId="create_link" absolute="false">/secure/CreateIssue!default.jspa</link>
  • The linkId is optional, and provides an XML id for the link being generated.
  • The absolute is optional and defaults to false unless the link starts with http:// or https://

The body of the link element is its URL. The URL is rendered with Velocity, so you can include dynamic information in the link. For example, in Confluence, the following link would include the page ID:

1
2
<link linkId="view-attachments-link">/pages/viewpageattachments.action?pageId=$page.id</link>

Icon Elements

Icon elements have a height and a width attribute. The location of the icon is specified within a link element:

1
2
<icon height="16" width="16">
    <link>/images/icons/print.gif</link>
</icon>

Param 

Param elements represent a map of key/value pairs, where each entry corresponds to the param elements attribute: name and value respectively.

1
2
<param name="key" value="value" />

The value can be retrieved from within the Velocity view with the following code, where $item is a WebItemModuleDescriptor:

1
2
$item.webParams.get("key") <!-- retrieve the value -->
$item.webParams.getRenderedParam("key", $user, $helper) <!-- retrieve the Velocity rendered value -->

If the value attribute is not specified, the value will be set to the body of the element. I.e. the following two param elements are equivalent:

1
2
<param name="isPopupLink" value="true" />
<param name="isPopupLink">true</param>

Context-provider

Available:Atlassian Plugins 2.5, Confluence 2.5, Bamboo 3.0, JIRA 4.2 and later

The context-provider element must contain a class attribute with the fully-qualified name of a Java class. The referenced class:The context-provider element adds to the Velocity context available to the web section and web item modules. You can add what you need to the context, to build more flexible section and item elements. Currently only one context-provider can be specified per module. Additional context-providers are ignored.

  • must implement com.atlassian.plugin.web.ContextProvider, and
  • will be auto-wired by Spring before any additions to the Velocity context.

For example, the following context-provider will add trackingEntry and bambooUserManager to the context.

In the following example, NotificationPanelContextProvider extends ContextProvider and add information for panel which shows person responsible for build failure.

1
2
public class NotificationPanelContextProvider implements ContextProvider {
    private final BambooUserManager bambooUserManager;
    private final TrackingEntryManager trackingEntryManager;

    @Autowired
    public NotificationPanelContextProvider(@ComponentImport final BambooUserManager bambooUserManager,
                                            final TrackingEntryManager trackingEntryManager) {
        this.bambooUserManager = bambooUserManager;
        this.trackingEntryManager = trackingEntryManager;
    }

    @Override
    public void init(final Map<String, String> params) throws PluginParseException {
    }

    @Override
    public Map<String, Object> getContextMap(final Map<String, Object> context) {
        final Map<String, Object> map = new HashMap<>(context);

        ResultsSummary resultsSummary = Narrow.to(map.get("resultsSummary"), ResultsSummary.class);
        if (resultsSummary != null) {
            map.put("trackingEntry", trackingEntryManager.getTrackingEntryByResultId(resultsSummary.getId()));
            map.put("bambooUserManager", bambooUserManager);
        }
        return map;
    }
}

The above NotificationPanelContextProvider can be used by nesting the following element in a web item module.

1
2
<context-provider class="com.atlassian.bamboo.brokenbuildtracker.notifications.NotificationPanelContextProvider"/>

The newly added context entries trackingEntry and bambooUserManager can be used in the XML module descriptors just like normal freemarker context variables, by prefixing them with the dollar symbol ($):

1
2
<!-- pass the value of trackingEntry as a parameter called trackingEntry (see param element above for its usage) -->
<param name="trackingEntry">$trackingEntry</param>

<label>Can create users: $bambooUserManager.canCreateUsers()</label>

Condition and Conditions elements

Conditions can be added to the web section, web item and web panel modules, to display them only when all the given conditions are true.

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

  • must implement com.atlassian.plugin.web.Condition, and
  • 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:

1
2
<condition class="com.atlassian.bamboo.ww2.actions.admin.GlobalAdminMenuCondition">
    <param name="permission">admin</param>
</condition>

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. Conditions elements are composed of a collection of condition/conditions elements and a type attribute. The type attribute defines what logical operator is used to evaluate its collection of condition elements. The type can be one of AND or OR.

For example: The following condition is true if the current user is a restricted administrator OR a system administrator:

1
2
<conditions type="OR">
    <condition class="com.atlassian.bamboo.ww2.actions.admin.GlobalAdminMenuCondition"/>
    <condition class="com.atlassian.bamboo.ww2.actions.admin.RestrictedAdminMenuCondition"/>
</conditions>

Example

Single web item in the admin section

Here is an example atlassian-plugin.xml file containing a single web item:

1
2
<atlassian-plugin name="Hello World Plugin" key="example.plugin.helloworld" plugins-version="2">
    <plugin-info>
        <description>A basic web item module test</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.0</version>
    </plugin-info>

    <web-item key="google_home" name="Google Home" section="system.admin/example1" weight="10">
        <description key="item.google.home.desc">Simple link to google.com.</description>
        <label key="item.google.home.label" />
        <link linkId="google_home">http://google.com</link>
    </web-item>
</atlassian-plugin>

Add a web item to the application header bar

Here is an example atlassian-plugin.xml file containing how to add your link to the application header.

1
2
<atlassian-plugin name="Hello World Plugin" key="example.plugin.helloworld" plugins-version="2">
    <plugin-info>
        <description>A basic web item module test</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.0</version>
    </plugin-info>

    <web-item key="google_home" name="Google Home" section="system.header/left" weight="60">
        <description key="item.google.home.desc">Simple link to google.com.</description>
        <label key="item.google.home.label" />
        <link linkId="google_home">http://google.com</link>
    </web-item>
</atlassian-plugin>

Rate this page: