Skip to end of metadata
Go to start of metadata

Available:

Web Item plugin modules are available in JIRA 3.7 and later.

 

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

Required

Description

Default

class

 

The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances.

 

state

 

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

enabled

i18n-name-key

 

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

 

key

(tick)

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.
<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.

N/A

name

 

The human-readable name of the plugin module. Used only in the plugin's administrative user interface.

 

section

(tick)

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.

N/A

system

 

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

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.

1000

Elements

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

Name

Required

Description

Default

condition

 

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

N/A

conditions

 

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

AND

context-provider

 

Allows dynamic addition to the velocity context available for various web item elements (in XML descriptors only). Currently only one context-provider can be specified per web item and section.

 

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 item.

 

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.

N/A

label

(tick)

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

N/A

link

(tick)

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.

N/A

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.

N/A

resource

 

A resource for this plugin module. This element may be repeated. A 'resource' is a non-Java file that a plugin may need in order to operate. Refer to Adding Resources to your Project for details on defining a resource.

N/A

styleClass

 

Defines an additional CSS class that will added to this web item when it is rendered on the page. Note that this value may be ignored in some situations.

N/A

tooltip

 

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

N/A

Label Elements

Label elements may contain optional parameters, as shown below:

  • 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.

Tooltip Elements

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

Link Elements

Link elements may contain additional information:

  • 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:

Icon Elements

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

Param Elements

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

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

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:

Context-provider Element

Available:

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

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.

The context-provider element must contain a class attribute with the fully-qualified name of a Java class. The referenced class:

  • 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 historyWindowHeight and filtersWindowHeight to the context.

In the following example, HeightContextProvider extends AbstractJiraContextProvider, which is only available in JIRA and happens to implement ContextProvider. The AbstractJiraContextProvider conveniently extracts the User and JiraHelper from the context map, which you would otherwise have to do manually.

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

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

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:

(info) In versions before JIRA 3.7, this class is called com.atlassian.jira.plugin.web.conditions.JiraGlobalPermissionCondition

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 system administrator OR a project administrator:

(info) In versions before JIRA 3.7, the second class is called com.atlassian.jira.plugin.web.conditions.UserHasProjectsCondition

Example

Single web item in the admin section

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

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.

 

 

See Also

  • Web Fragments — This reference guide describes how to combine Web Items, Web Sections and Web Panels together to generate links, sections of links and panels at specific locations of the JIRA user interface.
  • No labels

11 Comments

  1. In Jira 3.13 you'll need to use

  2. The definition of condition and Context-provider Element are not working jira jira 4.x...

    The plugin can not be loaded in jira

    INFO talledLocalContainer Caused by: com.atlassian.plugin.PluginParseException: com.atlassian.plugin.web.conditions.ConditionLoadingException: java.lang.IllegalStateException: Cannot autowire object because the Spring context is unavailable. Ensure your OSGi bundle contains the 'Spring-Context'
    header.

    Is something else to do with the Spring-context ???

    1. Hallo Maxime,
      Please would you take a look at Don Brown's response.
      Cheers, Sarah

  3. The JIRA Create and Link Plugin (JCLP) contains a good example of how to turn a single Web Item such as a new issue operation into multiple links. I wrote the plugin and Jim Pease wrote the Javascript and REST that makes it work in JIRA 4.1 and beyond.

  4. Dear Lazyweb, does anyone know if you can override existing issue operations using this plugin module by using an existing key?
    I know that you can't create new conditions in a plugin for use by system webitem elements.

    ~Matt

    1. The Clone and Move plugin is a web-item that overrides CloneIssueDetails.

        1. Ah, yes. I see they have not committed the patch I sent. I converted it for our use and sent a patch to Mark about 9 months ago. See http://forums.atlassian.com/thread.jspa?messageID=257342387&#257342387

  5. Anonymous

    The description of Link Elements is missing the "acceskey" propertie. Found it by accident here: Attlasian Forum (http://forums.atlassian.com/thread.jspa?messageID=257364016ူ).

  6. If you want to have dynamic set of web-items, you should check out: http://jira.atlassian.com/browse/JRA-20407

  7. Is this the proper way to make a web item disabled on plugin install? Doesn't seem to work - all items show as enabled.

    1. as an attribute
      <web-item key= ... disabled="true">
      ...
      </web-item>
      
    2. as an element
      <web-item ... >
      ...
      <disabled>true</disabled>
      </web-item>