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

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

Project Configuration Operations Location

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

Adding Custom 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

Tools Drop-down on User Profile Location

The system.user.profile.links location defines web items of the 'Tools' drop-down menu on a JIRA user's user profile page.

This location has only one section (operations) to which custom web items can be added.

Adding Custom Items

To add your own web item to the Tools drop-down location, your web item must include a section attribute with the value "system.user.profile.links/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.user.profile.links/operations" ...>
    ...
</web-item>

It is not possible to add your own web sections to the system.user.profile.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 higher up the drop-down menu.

Source File

To find the values of JIRA's existing web items for the system.user.profile.links 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-profile-links.xml

Preset Issue Filters Drop-down on Project Summary 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 Custom 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 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

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

A web item is rendered as either a button or a link on a drop-down menu, based on the web section to which the item is added.

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

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>

Source File

To find out how existing web items for the jira.hints location are implemented in JIRA, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/webfragment/system-hints.xml

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.

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:
  • Google Home — static link to http://google.com
  • Hello World — static link to the HelloWorld action with no name argument
  • Hello User — dynamic link to the HelloWorld action with current user's login name

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