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


Document generated by Confluence on Oct 06, 2009 00:31