Web Panel module

Web Panel plugin modules allow plugins to define panels, or sections, on an HTML page. A panel is a set of HTML that will be inserted into a page

Purpose of this Module Type

Web Panel plugin modules allow plugins to define panels, or sections, on an HTML page. A panel is a set of HTML that will be inserted into a page.

Configuration

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

Attributes

1
2
<component-import
key="appProps"
interface="com.atlassian.sal.api.ApplicationProperties"/>

*key and location attributes are required.

Elements

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

*label element is required.

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>

Context-provider

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>

Label

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>

• 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. I.e. param0 is {0}, param1 is {1}, param2 is {2}, etc.
• Parameter values are rendered using Velocity, allowing you to include dynamic content.

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>

Resource

Unless the module descriptor's class attribute is specified, a web panel will contain a single resource child element that contains the contents of the web panel. This can be plain HTML, or a (Velocity) template to provide dynamic content.

A web panel's resource element can either contain its contents embedded in the resource element itself, as part of the atlassian-plugin.xml file, or it can link to a file on the classpath when the location attribute is used.

A resource element's type attribute identifies the format of the panel's content (currently "static" and "velocity" are provided by Atlassian Plugin Framework 2.5.0 and atlassian-template-renderer 2.5.0 respectively) which allows the plugin framework to use the appropriate com.atlassian.plugin.web.renderer.WebPanelRenderer.

The template rendering system is extensible. You can add custom renderers by creating plugins. For more information on this, check out the Web Panel Renderer Plugin Module.

Web Panel Examples

NOTE: The values of the location attributes in the examples below are not real. They are just illustrative of the kind of location that Confluence, Bamboo and FishEye make available.

A web panel that contains static, embedded HTML:

1
2
<web-panel key="myPanel" location="atl.confluence.comments">
    <resource name="view" type="static"><![CDATA[<b>Hello World!</b>]]></resource>
</web-panel>

A web panel that contains an embedded Velocity template:

1
2
<web-panel key="myPanel" location="atl.bamboo.buildplan">
    <resource name="view" type="velocity"><![CDATA[#set($name = 'foo')My name is $name]]></resource>
</web-panel>

A web panel containing a Velocity template that is on the classpath (part of the plugin's JAR file):

1
2
<web-panel key="myPanel" location="atl.fisheye.annotatedfile">
    <resource name="view" type="velocity" location="templates/pie.vm"/>
</web-panel>

As mentioned previously, it is also possible to provide your own custom class that is responsible for producing the panel's HTML, by using the descriptor's class attribute (which makes the resource element redundant):

1
2
<web-panel key="myPanel" location="atl.crucible.dashboard" class="com.example.FooWebPanel">

Note that com.example.FooWebPanel MUST implement WebPanel.

Bamboo specific notes for Web Panels

Locations

Bamboo supports the following web panel locations:

Default Context Objects

The following objects are available by default without having to specify your own context-provider. 

Freemarker resource type

In addition to the standard velocity and static Web Panel resource types Bamboo introduces a freemarker type used to render Bamboos preferred templating engine Freemarker.

1
2
<web-panel key="feedbackPanel" location="plan.navigator">
    <resource name="view" type="freemarker" location="/fragments/feedback/feedbackWebPanel.ftl" />
</web-panel>

Adding Web Panel locations to your own plugins

Bamboo provides easy support for adding your own Web Panels via the ui.renderWebPanels freemarker macro.

Example

1
2
[@ui.renderWebPanels 'my.webpanel.location' /]

Once specified in any Freemarker template any plugin can specify my.webpanel.location in their web-panel location declaration and be expected to render along side your template.