This page last changed on Oct 05, 2009 by rosie@atlassian.com.
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 |
|
The administrative menu links on the left-hand side of the Administration page |
system.preset.filters |
|
|
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 |
|
|
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 |
|
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 |
|
|
Project operation links on the 'View Project' Page |
- 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.
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&pid=$helper.project.id&status=6&sorter/field=issuekey&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). |
|