Building UI for a plugin shipping to multiple versions of JIRA

Before you begin

Please refer to the following documents, which should answer some of your questions:

Some suggestions

  • Use AUI components exclusively

    The markup patterns for AUI components for most things are practically identical between JIRA 5.x and JIRA 6.0. There should be a minimum of fuss for these things.

  • Don't extend or override AUI patterns

    Extending or overriding AUI/JIRA's UI patterns are the #1 reason a UI "breaks" across versions of JIRA.

  • Minimise your dependencies

    If you're shipping bespoke UI, it's best to depend on as little as possible – ideally nothing other than your own plugin's assets. If you need something "like this, but a bit different," build it entirely yourself within your plugin. Don't depend on JIRA's or AUI's UI assets whatsoever. If you own the code that renders your UI, the chances of your UI breaking when you deploy it are greatly minimised.

  • Put your markup in small, composable templates

    If your markup is static, it will be difficult for you to update your plugin. Instead, pull as many UI concepts as you can out into templates and make template calls. This affords you the ability to swap out templates based on the version of JIRA you're using.

On determining what is safe to rely upon

When building across multiple versions of anything (of which JIRA is a subset), you need to determine your lowest common version for each dependency. Once you know this, you can determine the set of (UI) assets that will be available across all the versions you intend to support.

AUI assets across JIRA versions

JIRA version AUI version AUI components available
5.0.0 3.5.5 Dialog, Dropdown, Group+Item, Forms, Icons, Inline-dialog (popup), Messages, Tables, Tabs, Toolbar
5.1.x 3.5.5 Dialog, Dropdown, Group+Item, Forms, Icons, Inline-dialog (popup), Messages, Tables, Tabs, Toolbar
5.1.8 3.7-m6 Dialog, Dropdown, Dropdown2, Group+Item, Forms, Icons, Inline-dialog (popup), Messages, RESTful Table, Tables, Tabs, Toolbar
5.2.x 5.0-m10

Badges, Dialog, Dropdown, Dropdown2, Group+Item, Forms, Icons, Inline-dialog (popup), Labels, Lozenges, Messages, RESTful Table, Tables, Tabs, Toolbar

6.0-m06 5.0-m25

Avatars, Badges, Breadcrumbs (Navigation), Buttons, Dialog, Dropdown, Dropdown2, Group+Item, Forms, Icons, Inline-dialog (popup), Labels, Lozenges, Messages, RESTful Table, Tables, Tabs, Toolbar, Toolbar2, Tooltips

Multi-step Progress Tracker, Page Layouts, Page Panel/Content Layouts, Navigation (Horizontal, Vertical)

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport