This page last changed on Mar 25, 2011 by ggaskell.
Available: JIRA 3.7 and later
Changed: In JIRA 4.0 and later, the system.user.options location was added and the method of defining web items and sections for the system.top.navigation.bar changed.
In JIRA 4.1 and later, the view.issue.opsbar location was added.
In JIRA 4.2 and later, the system.user.hover.links and jira.hints locations were added.
Deprecated: In JIRA 4.0 and later, the system.user.navigation.bar location was deprecated and replaced by the system.user.options location.

Web Fragments

A web fragment is a link or a section of links inserted at a particular location of the JIRA web interface. A web fragment can also be a menu in JIRA's top navigation bar, which in itself may contain its own links and link sections, or buttons on the issue operations bar.

Plugin Modules Involved in Creating a Web Fragment

A web fragment can consist of two kinds of plugin module:

  • A Web Item module defines an individual link that will be displayed in the UI at a particular section/location. For example, this could be an individual item within a JIRA drop-down menu or a button on the issue operations bar.
  • A Web Section module defines a collection of links that will be displayed together at a particular location. For example, this could be a group of items within a JIRA drop-down menu (separated by lines) or a group of buttons on the issue operations bar.

Web items or web sections are utilised in a number of different ways, depending on the location of the web fragment you are creating.

Existing Web Fragments in JIRA

You can insert custom web fragments into existing ones in JIRA (e.g. web sections which are 'built in' to JIRA). However, you cannot redefine JIRA's existing web fragments.

We recommend downloading the JIRA source archive, so you can access the appropriate source files that define JIRA's existing web fragments. This will help you:

  • Alter the positions of your own web fragments
  • Help you ensure key values in your own <web-items> and <web-sections> remain unique.

You need to log in as a user with a commercial license to access the download page for the JIRA source archive.

Locations

Web fragments can be developed for a number of locations throughout the JIRA web interface. This section describes these locations and for each one:

  • where you can add web fragments for your plugin
  • how you implement web items and web sections plugin modules for these web fragments

Administration Console Location

The system.admin location defines web sections and items in the left-hand navigation column of JIRA's administration console.

You can add new web items to existing web sections in the left-hand navigation column of JIRA's administration console (see below), or add new sections to this column along with new items.

Adding New Items to Existing Web Sections

To add your own web item to an existing web section of JIRA's administration console location, your web item must include a section attribute with the value "system.admin/<web-section>", where <web-section> is the section of the left-hand navigation column to which the web item will be added.

For example, to add a web item module that defines a new item in the Global Settings section, your web item module would contain:

<web-item ... section="system.admin/globalsettings" ...>
    ...
</web-item>

Existing Web Sections of the Administration Console Location

project

schemes

exportimport

usersgroups

issuefields

options

globalsettings

issuesettings

system

Adding Custom Sections and Items

To add your own section to the left-hand navigation column, define a web section that includes a location attribute with the value "system.admin".

For example, your web section module would contain:

<web-section key="my-custom-admin-console-section" ... location="system.admin" ...>
    ...
</web-section>

Adding new web items to your own sections is similar to the method above for adding new web items to existing web sections. However, specify the value of your web section's key attribute in the value of your web item's section attribute (preceded by the location). Hence, following on from the previous example, your web item would contain:

<web-item... section="system.admin/my-custom-admin-console-section" ...>
    ...
</web-item>

Customising the Positions of Your Own Items and Sections

To customise the position of your own web items or sections in this location, add a weight attribute to your <web-item> or <web-section> and adjust its value with respect to JIRA's existing web items or sections. Lower weight values result in these items/sections appearing higher up in the left-hand navigation column.

Source File

To find the values of JIRA's existing web items and sections for the system.admin location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/webfragment/system-admin-sections.xml

Preset Issue Filters Drop-down Location

In JIRA 4.0 and later, the system.preset.filters location defines web items of the 'Filters' drop-down menu on the project summary page of a JIRA project.

In versions of JIRA prior to 4.0, the system.preset.filters location defines links on the Project portlet of the dashboard and on the right-hand side of Browse Project page.
The filter links are only defined once and reused in both places.

Links are displayed in two columns from left to right, then down (that is, the right column contains every second link).

Adding New Items

To add your own web item to JIRA's preset issue filters drop-down location, your web item must include a section attribute with the value "system.preset.filters".

For example, to add a web item module that defines a new 'Filters' drop-down menu link (on a project summary page), your web item module would contain:

<web-item ... section="system.preset.filters" ...>
    ...
</web-item>

It is not possible to add your own web sections to the system.preset.filters location.

Customising the Positions of Items

To customise the position of your own web items in this location, add a weight attribute to your <web-item> and adjust its value with respect to JIRA's existing web items. Lower weight values result in these items appearing to the left and then higher up this 'Filters' drop-down menu.

Source File

To find the values of JIRA's existing web items and sections for the system.preset.filters location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/system-preset-filters-sections.xml

Project Configuration Operations Location

The system.view.project.operations location defines web items of the project operation links on the project configuration page, which can be accessed by JIRA project administrators.

Adding New Items

To add your own web item to JIRA's project configuration operations location, your web item must include a section attribute with the value "system.view.project.operations".

For example, to add a web item module that defines a new project operation link on a project configuration page, your web item module would contain:

<web-item ... section="system.view.project.operations" ...>
    ...
</web-item>

It is not possible to add your own web sections to the system.view.project.operations location.

Customising the Positions of Items

To customise the position of your own web items in this location, add a weight attribute to your <web-item> and adjust its value with respect to JIRA's existing web items. Lower weight values result in these items appearing further to the left.

Source File

To find the values of JIRA's existing web items and sections for the system.view.project.operations location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/system-view-project-operations-sections.xml

Top Navigation Bar Location

Available in JIRA 4.0 and later.

The system.top.navigation.bar location defines web sections and items in JIRA's top navigation bar, which is accessible from all JIRA screens.

You can add new drop-down menus each with their own web sections and web items to this navigation bar, or add new items to JIRA's existing drop-down menus.

Adding Custom Drop-down Menus, Sections and Items

Adding a new drop-down menu with its own sections and items to the top navigation bar can be broken down into three module definition steps.

To add a new drop-down menu with its own sections and items:

  1. Define a <web-item> module for the drop-down menu itself.
    • This web item module must include:
      • A section attribute with the value "system.top.navigation.bar".
      • A child <link> element with a linkID attribute and a unique value "linkID_for_my_dropdown_menu".
    • For example:
      <web-item ... section="system.top.navigation.bar" ...>
          ...
          <link linkID="linkID_for_my_dropdown_menu" ...>
              ...
          </link>
          ...
      </web-item>

  2. Define one or more <web-section> modules for this drop-down menu.
    • Each of these web section modules must include:
      • A key attribute with a unique value.
      • A location attribute whose value is that of the linkID attribute's value specified in the web item module for the drop-down menu (see 1 above).
    • For example:
      <web-section key="first_section_of_my_dropdown_menu" ... location="linkID_for_my_dropdown_menu" ...>
          ...
      </web-section>

  3. Define a <web-item> module for each item that appears in one of these web sections in this drop-down menu.
    • Each of these web item modules must include a section attribute whose value is:
      • The linkID attribute's value specified in the web item module for the drop-down menu (see 1 above), followed immediately by
      • A slash symbol /, followed immediately by
      • The key attribute's value specified in the relevant web section module (see 2 above).
    • For example:
      <web-item ... section="linkID_for_my_dropdown_menu/first_section_of_my_dropdown_menu" ...>
          ...
      </web-item>

Adding Items to Existing Drop-down Menus

Based on the process above, you can add your own item to an existing drop-down menu by defining a <web-item> module whose section attribute's value is:

  • The linkID attribute's value specified in the web item module for the drop-down menu (defined in the JIRA source code), followed immediately by
  • A slash symbol /, followed immediately by
  • The key attribute's value specified in the relevant web section module (again found in the JIRA source code).

For example, if you wanted to add a web item to the 'Dasboard' drop-down menu, the following diagram shows what values you would use for the section attribute of this web item, based on the web section of the drop-down menu.

Source File

To find the values of JIRA's existing web items and sections for the system.top.navigation.bar location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/system-top-navigation-plugin.xml

Customising the Positions of Menus, Items and Sections

To customise the position of your own web items or sections throughout JIRA's top navigation bar, add a weight attribute to your <web-item> or <web-section> and adjust its value with respect to JIRA's existing web items or sections.

  • For web items that define the drop-down menu itself (see 1 above), lower weight values result in menus appearing closer to the left of the user interface.
  • For web items and sections defined within a drop-down menu (see two and three above), lower weight values result in these items/sections appearing higher up the drop-down menu.

User Name Drop-down Location

Available in JIRA 4.0 and later.

The system.user.options location defines web sections and items in JIRA's user name drop-down menu, which is accessible from all JIRA screens.

You can add new web items to existing web sections in the user name drop-down menu (see below), or add new sections to this menu along with new items.

Adding New Items to Existing Web Sections

To add your own web item to an existing web section of JIRA's user name drop-down location, your web item must include a section attribute with the value "system.user.options/<web-section>", where <web-section> is the section of the user name drop-down menu to which the web item will be added.

For example, to add a web item module that defines a new item in the 'jira-help' section, your web item module would contain:

<web-item ... section="system.user.options/jira-help" ...>
    ...
</web-item>

Existing Web Sections of the User Name Drop-down Location

Adding Custom Sections and Items

To add your own section to the user name drop-down menu, define a web section that includes a location attribute with the value "system.user.options".

For example, your web section module would contain:

<web-section key="my-custom-user-name-dropdown-section" ... location="system.user.options" ...>
    ...
</web-section>

Adding new web items to your own sections is similar to the method above for adding new web items to existing web sections. However, specify the value of your web section's key attribute in the value of your web item's section attribute (preceded by the location). Hence, following on from the previous example, your web item would contain:

<web-item ... section="system.user.options/my-custom-user-name-dropdown-section" ...>
    ...
</web-item>

Customising the Positions of Items and Sections

To customise the position of your own web items or sections in this location, add a weight attribute to your <web-item> or <web-section> and adjust its value with respect to JIRA's existing web items or sections. Lower weight values result in these items/sections appearing higher up the user name drop-down menu.

Source File

To find the values of JIRA's existing web items and sections for the system.user.options location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/webfragment/system-user-nav-bar-sections.xml

Issue Operations Bar Locations

Available in JIRA 4.1 and later.

The two opsbar-operations and opsbar-transitions locations together define web sections and items in the issue operations bar, which is visible on all JIRA issues.

You can add new web items to existing web sections within the opsbar-operations and opsbar-transitions locations of the issue operations bar (see below). You can also add new web sections to the 'More Actions' drop-down menu (in the opsbar-operations location).

Adding New Items to Existing Web Sections

To add your own web item to an existing web section of one of JIRA's issue operations bar locations, your web item must include a section attribute with the value "<web-section>", where <web-section> is one of the sections specified in the diagram below.

For example, to add a web item module that defines a new item in the 'operations-operations' section, your web item module would contain:

<web-item ... section="operations-operations" ...>
    ...
</web-item>

Web items added to the 'operations-top-level' section will appear in the top level of the opsbar-operations location.
To add an item to the opsbar-transitions location, the value of your web item's section attribute must be "transitions-all". Referencing the opsbar-transitions location explicitly in your web item definition will not work.

Existing Web Sections of the Issue Operations Bar Locations

Adding Custom Sections and Items

To add your own section to the 'More Actions' drop-down menu, define a web section that includes a location attribute with the value "opsbar-operations".

For example, your web section module would contain:

<web-section key="my-custom-more-actions-section" ... location="opsbar-operations" ...>
    ...
</web-section>

It is not possible to add your own web sections to the opsbar-transitions location.

Adding new web items to your own sections is similar to the method above for adding new web items to existing web sections. However, specify the value of your web section's key attribute as the value of your web item's section attribute. Hence, following on from the previous example, your web item would contain:

<web-item ... section="my-custom-more-actions-section" ...>
    ...
</web-item>

Customising the Positions of Items and Sections

To customise the position of your own web items or sections throughout the issue operations bar, add a weight attribute to your <web-item> or <web-section> and adjust its value with respect to JIRA's existing web items or sections.

  • For web items added to the 'operations-top-level' section, lower weight values result in buttons appearing closer to the left of the user interface.
  • For web items and sections which target the 'More Actions' drop-down menu, lower weight values result in these items/sections appearing higher up the drop-down menu.
  • For web items added to the 'transitions-all' section, lower weight values result in these items appearing closer to the left and then higher up the 'Workflow' drop-down menu.
    Note that these values are overridden by opsbar-sequence property keys, which can be specified by a JIRA administrator through the administration console. See Customising the appearance and order of workflow transitions on the 'View Issue' page for details.

Source File

To find the values of JIRA's existing web items and sections for the opsbar-operations and opsbar-transitions locations, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/system-issueoperations-plugin.xml

Hover Profile Links Location

Available in JIRA 4.2 and later.

The system.user.hover.links location defines web items in JIRA's hover profile feature, which is accessible when a user hovers their mouse pointer over a JIRA user's name throughout JIRA's user interface.

Adding New Items

To add your own web item to JIRA's hover profile links location, your web item must include a section attribute with the value "system.user.hover.links".

For example, to add a web item module that defines a new hover profile link, your web item module would contain:

<web-item ... section="system.user.hover.links" ...>
    ...
</web-item>

It is not possible to add your own web sections to the system.user.hover.links location.

Customising the Positions of Items

To customise the position of your own web items in this location, add a weight attribute to your <web-item> and adjust its value with respect to JIRA's existing web items. Lower weight values result in these items appearing to the left and then higher up the hover profile drop-down menu.

Source File

To find the values of JIRA's existing web items and sections for the system.user.hover.links location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/system-user-format-plugin.xml

Dialog Box Hint Location

Available in JIRA 4.2 and later.

The jira.hints location defines web items that allow you to add hints on JIRA's dialog boxes. You can add hints to most JIRA dialog boxes.

Adding New Items

To add your own web item to JIRA's dialog box hints location for a specific dialog box, your web item must include a section attribute with the value "jira.hints/<LOCATION CONTEXT>", where <LOCATION CONTEXT> is a predefined 'context' in JIRA that determines on which dialog box your hints will appear.

The following table lists these predefined contexts available in JIRA's dialog box hint location.

Context Description
TRANSITION Hints on a 'transition issue' dialog box.
ASSIGN Hints on the 'Assign' dialog box.
LABELS Hints on the 'Labels' dialog box.
COMMENT Hints on 'Comment' dialog boxes.
CLONE Hints on 'Clone Issue' dialog box.
DELETE_FILTER Hints on 'Delete Filter' dialog box.
ATTACH Hints on 'Attach Files' dialog box (not the 'Attach Screenshot' one).
DELETE_ISSUE Hints on 'Delete Issue' dialog box.
LINK Hints on 'Link Issue' dialog box.
LOG_WORK Hints on 'Log Work' dialog box.

For example, to add a web item module that defines hints on the 'Attach Files' dialog box, your web item module would contain:

<web-item ... section="jira.hints/ATTACH" ...>
    ...
</web-item>

Deprecated Locations

Former Top Navigation Bar Location

Deprecated in JIRA 4.0. Please refer to the Top Navigation Bar location for JIRA 4.0+ (above).

In versions of JIRA prior to 4.0, the system.top.navigation.bar location could optionally specify up to 2 URL prefixes (in web items with section="system.top.navigation.bar"), which are used to determine whether the link is selected or not.

This is done by adding a param element with names: selected and selected2. See Web Item Plugin Module for details on how to add these elements.

Navigation Bar User Options Location

Deprecated in JIRA 4.0. This location has been replaced by the User Name Drop-down location for JIRA 4.0+ (above).

The system.user.navigation.bar location, defines web items or sections for user options at the top-right of JIRA's navigation bar.

Custom web items must be added to either the 'links' or 'views' web sections of this location in JIRA:

  • links web section — allows its links to be plain or pop-up links.
    • To make a link to be a pop-up link, set a param element with name isPopupLink as true. Additional parameters can be set to dynamically set the height (windowHeight), width (windowWidth) and whether to have scrollbars (scrollbars) for the pop-up.
  • views web section — displays all its links as icons and requires the icon element.

See Web Item Plugin Module for details on how to add these elements.

Velocity Context

The following table lists out the velocity context available for use in the XML descriptor and velocity views.

Name Type Description
user User Currently logged in user
helper JiraHelper Convenient class which holds information such as the current request and selected project
xmlutils XMLUtils Utilities for basic XML reading
textutils TextUtils Utilities for common String manipulations
urlcodec JiraUrlCodec Utility for encoding a string
outlookdate OutlookDate Class to give a nice String representation of a date
authcontext JiraAuthenticationContext User locale dependant utility class. Can get the current user, locale, I18nBean (for internationalisation) and OutlookDate
dateutils DateUtils Utilities for displaying date/time
externalLinkUtil ExternalLinkUtil A simple utility class that lets you resolve external links that may need to change, because of partner sites and such
requestContext VelocityRequestContext A context that allows for different implementations depending on whether it is running in the scope of a web request, or via email.
req HttpServletRequest current request
baseurl String The base URL for this instance (velocityRequestContext.getBaseUrl())

Examples

Here is a simple example that uses both the web UI module and the Webwork plugin module.

A webwork plugin module defines a URL-addressable 'action', allowing JIRA's user-visible functionality to be extended or partially overridden. In this example, the action simply prints "Hello World" or greets a given name. However the action can only be executed by entering a specific URL that is not linked from JIRA. This is where the web UI plugin comes in play, by adding the specific URL as a link from the JIRA web interface.

The following plugin modules will:

  • Register a new webwork action that prints "Hello World" (or "Hello" to a specific name)
  • Add a new section to the administration menu called Example 1 Section
  • Add 3 links under the new section:
<webwork1 key="HelloWorld" name="Hello World Action Example" i18n-name-key="action.hello.world.name">
        <description key="action.hello.world.desc">Webwork plugin example that prints hello world. Can also specify a name to say hello to.</description>
        <resource type="i18n" name="i18n" location="com.atlassian.jira.web.action.HelloWorldAction" />
        <actions>
            <action name="com.example.jira.web.action.HelloWorldAction" alias="Hello">
                <view name="input">/templates/example/helloworld_input.vm</view>
                <view name="success">/templates/example/helloworld.vm</view>
            </action>
        </actions>
    </webwork1>

    <web-section key="example1" name="Example Section" i18n-name-key="section.example.one.name" location="system.admin" weight="105">
        <description key="section.example.one.desc">Example section in the admin page with example links</description>
        <label key="section.example.one.label" />
    </web-section>

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

    <web-item key="hello_world" name="Greet world link" i18n-name-key="item.hello.world.name" section="system.admin/example1" weight="20">
        <description key="item.hello.world.desc">Static link to the HelloWorld action with no name parameter.</description>
        <label key="item.hello.world.label" />
        <link linkId="hello_world">/secure/Hello!default.jspa</link>
        <condition class="com.atlassian.jira.plugin.webfragment.conditions.UserLoggedInCondition" />
    </web-item>

    <web-item key="filter_closed" name="Closed Issues Filter" i18n-name-key="item.filter.closed.name" section="system.preset.filters" weight="25">
        <description key="item.filter.closed.desc">Custom preset-filter to find closed issues in current project</description>
        <label key="item.filter.closed.label" />
        <link linkId="filter_closed">/secure/IssueNavigator.jspa?reset=true&amp;pid=$helper.project.id&amp;status=6&amp;sorter/field=issuekey&amp;sorter/order=DESC</link>
    </web-item>

Here is the screenshot of the new administration menu:

The new section "Example 1 Section" appears in between the "Project" and "Users, Groups & Roles" as its weight is in between the two.

Get the full sample plugin from the JIRA Plugin Development Kit. The sample shows how to combine a simple webwork module with a web UI module to provide you with an interface to your plugin from Jira. You can find a real life application of this in the JIRA Subversion plugin (for Jira 3.7 compatible versions only).

location_preset_filters.PNG (image/png)
location_admin.PNG (image/png)
action_hello_world.PNG (image/png)
action_hello_user.PNG (image/png)
location_view_project_operations.PNG (image/png)
location_user_navigation_bar.PNG (image/png)
location_top_navigation_bar.PNG (image/png)
location_preset_filters_project.PNG (image/png)
location_preset_filters_portlet.PNG (image/png)
newAdminMenu.png (image/png)
ops-bar-web-sections.png (image/png)
jira-4-3-admin-console-global-settings.png (image/png)
jira-4-3-admin-console-project.png (image/png)
jira-4-3-admin-console-options-settings.png (image/png)
jira-4-3-admin-console-import-export.png (image/png)
jira-4-3-admin-console-issue-fields.png (image/png)
jira-4-3-admin-console-issue-settings.png (image/png)
jira-4-3-admin-console-schemes.png (image/png)
jira-4-3-admin-console-system.png (image/png)
jira-4-3-admin-console-users-groups-roles.png (image/png)
jira-4-3-top-navigation-bar.png (image/png)
jira-4-3-user-name-drop-down.png (image/png)
Existing User Name Drop Down Web Sections (text/xml)
jira-4-3-user-name-drop-down.jpg (image/jpeg)
Existing User Name Drop Down Web Sections (text/xml)
Existing User Name Drop Down Web Sections (text/xml)
jira-4-3-top-navigation-bar-dashboard-drop-down.jpg (image/jpeg)
Section Attribute Values for Web Items in the Dashboard Drop-Down (text/xml)
Section Attribute Values for Web Items in the Dashboard Drop-Down (text/xml)
Section Attribute Values for Web Items in the Dashboard Drop-Down (text/xml)
Section Attribute Values for Web Items in the Dashboard Drop-Down (text/xml)
Existing User Name Drop Down Web Sections (text/xml)
Existing User Name Drop Down Web Sections (text/xml)
Section Attribute Values for Web Items in the Dashboard Drop-Down (text/xml)
jira-4-3-issue-operations-bar.png (image/png)
jira-4-3-issue-operations-bar.jpg (image/jpeg)
jira-4-3-issue-operations-bar-operations.jpg (image/jpeg)
Existing Issue Operations Bar Web Sections (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
This is an example diagram (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
Issue Operations Bar (text/xml)
Issue Operations Bar (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
Issue Operations Bar (text/xml)
Existing Issue Operations Bar Web Sections (text/xml)
jira-4-3-hover-profile.png (image/png)
jira-4-3-shortcut-hints.png (image/png)
jira-4-3-project-filters.png (image/png)
jira-4-3-project-configuration-operations.png (image/png)
Document generated by Confluence on Mar 27, 2011 18:53