Webwork plugin module

Purpose of this Module Type

A webwork plugin module defines a URL-addressible 'action', allowing JIRA's user-visible functionality to be extended or partially overridden.

構成

The root element for the WebWork plugin module is webwork1. It allows the following attributes and child elements for configuration:

属性

名前	説明	既定
クラス	[Unable to render {include} The included page could not be found. ({include} をレンダリングできません。ページが見つかりませんでした)] を選択し、 The Java class of the module. For this module, it's fine to use `Object`, as the real brains are in the action classes below.
鍵 (キー)	[Unable to render {include} The included page could not be found. ({include} をレンダリングできません。ページが見つかりませんでした)] を選択し、 I.e. the identifier for this module.	N/A
i18n-name-key	[Unable to render {include} The included page could not be found. ({include} をレンダリングできません。ページが見つかりませんでした)] を選択し、
name	[Unable to render {include} The included page could not be found. ({include} をレンダリングできません。ページが見つかりませんでした)] を選択し、 I.e. the human-readable name of this module.	The plugin key.

Elements

名前	必須	説明
description		A human-readable description of this WebWork module. May be specified as the value of this element for plain text or with the `key` attribute to use the value of a key from the i18n system.
actions		Specifies WebWork 1 <action>s to define. Must contain at least one <action> element.

`<action>` Element Attributes

名前	必須	説明
name		Full name of the class that implements the WebWork action. Actions in JIRA must extend the class `com.atlassian.jira.action.JiraActionSupport`. The class must not live in a package that JIRA has already reserved; authors should avoid the `com.atlassian` namespace altogether.
alias		The path from which this action may be invoked in JIRA. For example, an action with alias `MyNewJiraAction` would be invoked by the URL `http://<my-jira-server>/secure/MyNewJiraAction.jspa`.

`<action>` Element Elements

名前	必須	説明
view		Directs where to send the user when the action completes. The `name` attribute maps to the return value from the overridden action methods (see the WebWork documentation for more details; common values are `error`, `input`, and `success`). The element's value is the path to the renderable view that is sent to the user (see Notes for more information).

例

Here is a sample webwork plugin module:

<webwork1 key="qquserissue" name="Quick Create User Issue" class="java.lang.Object">
    <actions>
        <action name="com.atlassian.jira.toolkit.action.QuickCreateUserIssueAction" alias="QuickCreateUserIssue">
            <view name="createuserissue">/templates/quickcreateuser.vm</view>
        </action>
    </actions>
</webwork1>

Webwork plugins effectively extend the actions defined in the JIRA WEB-INF/classes/actions.xml file. You should look there for examples of what is possible. There is also a Webwork Sample plugin that contains many other basic examples.

Overriding a JIRA action

By specifying as 'alias' the name of an existing action (in actions.xml), you can override default JIRA behaviour. For example, to override the Administrators.jspa action (the 'Contact Administrators' link at the bottom of every page):

    <webwork1 key="ASFAdministrators" name="Lists project leads on administrators page" class="java.lang.Object">
        <actions>
            <action name="org.apache.jira.plugins.actions.ASFAdministrators" alias="Administrators">
                <view name="success">/templates/asf_administrators.vm</view>
            </action>
        </actions>
    </webwork1>

Here, templates/asf_administrators.vm is a Velocity template provided by (and bundled inside of) the plugin. It will be rendered when the org.apache.jira.plugins.actions.ASFAdministrators action returns.

Use your own package for your action classes!

In the past, plugin authors could rely on a bit of magic: putting their action class in the package com.atlassian.jira.web.action was enough to have JIRA find it without specifying the fully qualified class name in <action name="">. This was never a good idea, and in a Plugins2 plugin, it will simply not work. Always create a separate package space for your code and stay out of the com.atlassian namespace.

Avoid complex inheritance!

You can override existing actions without worry, but you cannot override an already overridden action. JIRA's WebWork implementation isn't smart enough to resolve polymorphic action hierarchies.

Sample Code

The JIRA sample plugin shows how to display the project leads in each project Administrator's page
The Webwork Sample plugin contains many simple examples of using Webwork actions
The Copyright Information for Aattachments page is another example of how to override a default JIRA action.

注意

Renderable Views: The value of <view> should be a Velocity template; in the above example, the template templates/quickcreateuser.vm lives in the plugin artifact under that path. JSP views cannot be used from inside plugins; they can be used if they are installed into the JIRA webapp, but this complicates installation, upgrading, and troubleshooting. Use Velocity if you can.

Child pages