Documentation for JIRA 4.2. Documentation for other versions of JIRA is available too.

Web Fragments

Web Fragments are available in Jira 3.7 and later.

Web Fragments allow you to insert links, tabs and sections of links into the Jira web interface

Web Sections and Web Items

Web Fragments can consist of two kinds of plugin modules:

  • Web Item modules define links that will be displayed in the UI at a particular location
  • Web Section modules define a collection of links that will be displayed together

Web Items or Web Sections may be displayed in a number of different ways, depending on the location of the fragment.

Locations

In a number of places in the Jira UI, there are lists of links representing operations relevant to the content being viewed. These are the locations and sections that you can customise:

Location key

Sections

Dynamic Sections?

Description

system.admin

project
usersgroups
globalsettings
schemes
issuefields
issuesettings
exportimport
options
system

(tick)

The administrative menu links on the left-hand side of the Administration page

system.preset.filters

 

(error)

The filter links on the right hand side of Browse Project page and on the project portlets of the dashboard. Note that the filter links are defined only once and is reused in both places.
Links are displayed in two columns where the right column contains the every second link, and the rest in the left column

system.top.navigation.bar

 

(error)

System links on the top navigation bar
The web-item can optionally specify up to 2 URL prefix that will be used to determine whether the link is selected or not. This is done by adding a param element with names: selected and selected2

system.user.navigation.bar

links
views

(error)

Links on the top-right user navigation bar.
web-item's must be added to either the links or views section.

  • links section allows its links to be plain or popup links. To make a link to be a popup 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 popup
  • views section displays all its links as icons and require the icon element

system.view.project.operations


(error)

Project operation links on the 'View Project' Page

opsbar-operations
operations-top-level
operations-work
operations-attachments
operations-voteswatchers
operations-subtasks
operations-operations
operations-delete

 

(error)

Items on the View Issue operations bar, including sections in the 'More Actions' drop-down. See screenshot of their location below. Note that these are not prefixed with their location, which is "view.issue.opsbar".

  • Locations marked as being 'Dynamic Sections' allows new sections to be added. Whereas unmarked locations will not display new sections added to that location and require the items to be added to the existing sections. If there are no sections, the items should be added to the location key itself.

A screenshot of the operations bar sections is shown below.


View Issue operation bar web sections

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

Heres 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
  • Adds a new section to the administration menu called Example 1 Section
  • Adds 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).

  • No labels