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

XWork plugin module

Available:

Bamboo 1.0 and later

Changed:

Bamboo 3.0 added context aware navigation and decorators, both described below.

Description

Each XWork module is deployed as a plugin module of type xwork and contains one or more XWork package elements. The XWork plugin module allows you to define your own XWork package and actions that you can access.

To build the action into the system, you will typically need to add a Web Item Module to link to your action.

Below is an example atlassian-plugin.xml file containing a single XWork module.

Sample Module Descriptor Element

1
2
<xwork key="viewCloverResult" name="View Clover Result">
    <package name="cloverPlugin" extends="buildView">
      <action name="viewCloverResult" class="com.atlassian.bamboo.build.ViewBuildResults">
        <result name="success" type="freemarker">/plugins/clover-plugin/viewCloverResult.ftl</result>
        <result name="error" type="freemarker">/error.ftl</result>
      </action>
    </package>
  </xwork>

Context Aware Navigation

Available:

Bamboo 3.0 and later

Only applicable to people adding web items to Plan/Job/Result tabs

Some pages in Bamboo have a Plan Navigator. When moving between Jobs and the Plan (as well as Job Results and Plan Result), the navigator remembers our context i.e. which tab you are on and will attempt to keep you on the same tab. There is some default behaviour available to determine which page to navigate to (and hence which tab), however, if you would like your plugin to dictate exactly where to go, you can manually define the corresponding page to navigate to via your xwork action definition.

For each xwork action you can define the jobEquiv and chainEquiv parameters. The chainEquiv will be used when navigating to the Plan (or Plan Result), the jobEquiv when navigating to the Job (or Job Result). Note that even though you are already on a Job level page, you can set the jobEquiv to be something different for other Jobs in the Plan.

You can use the markers ${planKey} and ${buildNumber} as place holders in the equivalent URL.

Examples:

1
2
<action name="viewChainAuditLog" class="com.atlassian.bamboo.ww2.actions.chains.admin.ViewChainAuditLog">
  <param name="jobEquiv">/build/admin/edit/editBuildDetails.action?buildKey=${planKey}</param>
  <param name="chainEquiv">chain/admin/config/viewChainAuditLog.action?buildKey=${planKey}</param>
  <result name="success" type="freemarker">/chain/edit/viewChainChangeHistory.ftl</result>
</action>

1
2
<action name="viewBuildResultsSuccessfulTests" class="com.atlassian.bamboo.build.ViewBuildResultsSuccessfulTests">
  <param name="chainEquiv">/browse/${planKey}-${buildNumber}/test</param>
  <param name="jobEquiv">/browse/${planKey}-${buildNumber}/test</param>
  <result name="success" type="freemarker">/build/result/viewBuildResultsSuccessfulTests.ftl</result>
  <result name="error" type="freemarker">/error.ftl</result>
</action>

If Bamboo can not figure out where to take the user, it will default to the first tab on the page.

Using Bamboo's Decorators

Available:

Bamboo 3.0 and later

Bamboo will decorate any HTML returned by your action. In most cases this will just be the Header and Footer, however there are a few decorators which do much more than this. There are two ways to control the decoration occurring on your page.

  1. URL Mapping - Each decorator is mapped to a specific URL pattern, if your action URL matches that pattern it will use that decorator.

  2. Manual Specification - If your action URL does not match the required pattern, you will need to manually define which decorator you want Bamboo to use.

    1
2
    <head>
    <meta name="decorator" content="<decorator-name>">
</head>

Available Decorators

Decorator Name

Notes

plan

For Plans and Job, provides Breadcrumbs, Plan Navigator and Tab menu

Default URL Mappings: 

<pattern>/build/*.action</pattern>
<pattern>/chain/*.action</pattern>

result

For Plan Results and Job Results, provides Breadcrumbs, Status Ribbon, Plan Navigator and Tab menu

Default URL Mappings: 

<pattern>/chain/result/*.action</pattern>
<pattern>/build/result/*.action</pattern>

atl.admin

For Administration Pages, provides Admin menu

Default URL Mappings: 

<pattern>/admin/*.action</pattern>

atl.general

The default decorator (Header + Footer only)

Default URL Mappings: Everything

none

Will not provide any decoration

Tabs and Decorators

If the decorator is providing a row of tabs to your page, you will need to manually define on their page which tab is selected as follows:

1
2
<head>
    <meta name="tab" content="<web-item-name>"/>
</head>

People using  web items  to add to the Plan/Job/Result tabs should use the plan or result decorator

Rate this page: