Changes to markup, CSS and Decorators in JIRA 5.0

JIRA 5.0 milestone 4 includes significant changes to markup, CSS and decorators. We're moving towards a common markup pattern and theme for all our applications. This will provide a baseline which each product can build upon.

Some of the key points regarding these changes are:

  • Consistent markup/CSS across JIRA pages: one common template/set of styles no matter what part of JIRA you are integrating with!
  • Better performance for the client and server: IE7 hacks and JS crutches removed now that IE7 is no longer a supported browser
  • More stability surrounding the markup/CSS: new template/styles are much more generic and flexible enough that changes to it should be rare
  • Structure/semantics of the markup is improved: use of HTML5 elements like header/footer/sections and better IDs/Classes make things a lot clearer
  • Default styles reflect Look & Feel: fall back on JIRA's styles to stay consistent with the L&F colours, font sizes, etc (headings now use the L&F heading colour)

New HTML structure

Atlassian intends to adopt this new template across all products, this will provide a much more consistent user experience when moving from one product to another as well as lower the learning curve for plugin writers when writing a plugin for an app they're not familiar with. In the future there may be the potential for a cross product plugin which only needs a single set of markup. 

Some side-by-side comparisons of various page structures in JIRA are shown below (click to enlarge). You can see that the markup is now a lot more consistent. In order to change how the template displays on certain pages we now use a CSS class of "page-type-foo" on the body. This replaces all the old classes like "nl", "type-a", "type-aa", etc. All pages now get a common look and feel, the baseline of which will be soon provided by AUI. JIRA will then extend the baseline styles with the customisations required. This method of changing how the template behaves is also recommended for plugins.

The nodes highlighted in blue are where most of the "content" starts. The new markup is longer in most cases due to the inclusion of a new wrapping div (<div id="page">). This is primarily there as a styling hook for people theming our products but it also brings JIRA more inline with some of the other products. You'll notice that there are now 3 distinct areas - #header, #content and #footer. This is now consistent across all of JIRA (some decorators don't include the header/footer - see the section on decorators below).

We realize that these changes will be extensive for plugins which provide additional UI elements inside of JIRA. However we believe that this new approach will make JIRA much easier to work with going forward. Because of the scale of the changes, we are providing a migration guide so you know exactly how to migrate from JIRA 4.4 markup to JIRA 5.0.

Changes to the Decorators

The table below shows the old and new decorators side-by-side. The example images use the following markup and simply change the decorator applied.

<html>
<head>
  <title>Title element in header</title>
  <meta name="decorator" content="none" />
</head>
<body>
 <h1>h1 text in the body</h1>
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eros turpis, adipiscing quis molestie ut, convallis nec turpis. Quisque sollicitudin purus dui. Integer nec lectus in velit volutpat pulvinar et a nunc. Etiam a nisl sed mauris ultrices scelerisque semper vitae lectus. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Duis fermentum auctor luctus. Cras augue leo, sodales mattis tempor ut, condimentum ut erat. Quisque a libero vitae massa bibendum consequat. Aliquam laoreet enim ut arcu eleifend venenatis. Morbi in adipiscing arcu. Vestibulum mollis, nisi ac hendrerit scelerisque, leo enim lacinia erat, vel bibendum nisi ligula sed purus. Nunc a dui dui. Vestibulum pharetra convallis urna, et accumsan mi feugiat at. Duis tincidunt, massa vitae imperdiet faucibus, augue augue ultrices eros, quis condimentum ligula erat quis nibh. Sed urna ante, cursus vel vestibulum vitae, consectetur ut mauris.</p>
 <p>Maecenas ultrices elit placerat lacus porta at interdum dui dictum. Quisque aliquet tincidunt justo, ac iaculis magna volutpat congue. Vestibulum suscipit justo sed justo posuere porttitor. Nullam ac purus sed quam porttitor bibendum in ut orci. Vivamus fermentum tempor venenatis. Etiam turpis urna, egestas quis rhoncus id, bibendum a justo. Mauris eu ligula et eros auctor facilisis sit amet in enim. Integer et felis ipsum. Nam dictum dictum gravida. Donec nec odio vel purus dapibus sodales at non ante. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nulla facilisi. Integer eu tincidunt nisl. Aenean enim ligula, blandit et hendrerit nec, dictum vitae massa. Sed in mauris elit, eget malesuada mauris. </p>
</body>
</html>  

JIRA 4.4.x

JIRA 5

Decorator name
Example
Notes

Contexts applied

Decorator name
Example
Notes

Contexts applied

atl.admin

atl.admin
jira.admin

atl.admin

class="page-type-admin"

atl.admin
jira.admin

atl.general

atl.general
jira.general

atl.general

atl.general
jira.general

atl.popup

atl.popup
jira.popup

atl.popup

class="page-type-popup"

atl.popup
jira.popup

atl.userprofile

atl.userprofile
jira.userprofile
atl.general
jira.general

atl.userprofile

atl.userprofile
jira.userprofile
atl.general
jira.general

none

Doesn't affect markup and includes no resources

none

Doesn't affect markup and includes no resources

admin
Same as "atl.admin"

atl.admin
jira.admin

admin
same as "atl.admin"
class="page-type-admin"

atl.admin
jira.admin

general
Same as "atl.general"

atl.general
jira.general

general
Same as "atl.general"

atl.general
jira.general

main

atl.general
jira.general

main
Same as "atl.general"
Mapped to "atl.general" in 5.0
DEPRECATED

atl.general
jira.general

insecure
Same as "main"
Mapped to "main" in 4.4

atl.general
jira.general

insecure
Same as "atl.general"
Mapped to "atl.general" in 5.0
DEPRECATED

atl.general
jira.general

frontpage

atl.general
jira.general

frontpage
Same as "atl.general"
Mapped to "atl.general" in 5.0
DEPRECATED

atl.general
jira.general

notitle

atl.general
jira.general

notitle
Same as "atl.general"
Mapped to "atl.general" in 5.0
DEPRECATED

atl.general
jira.general

setup
Not for plugin use

setup
Not for plugin use

setupgh
Not for plugin use

setupgh
Not for plugin use

dialog

dialog

dialog-iframe
DEPRECATED

dialog-iframe
DEPRECATED

error

atl.error
jira.error

error


class="page-type-message"
If you push messages to the error collection they'll be shown below the content (see second screenshot)

atl.error
jira.error

message

atl.message
atl.error
jira.message
jira.error

message

class="page-type-message"

atl.message
atl.error
jira.message
jira.error

issueaction
Not for plugin use

atl.general
jira.general

issueaction
Not for plugin use

atl.general
jira.general

navigator
Not for plugin use

jira.navigator
atl.general
jira.general

navigator
Not for plugin use

jira.navigator
atl.general
jira.general

printable

atl.general
jira.general

printable

atl.general
jira.general

popup
Same as "atl.popup"

atl.popup
jira.popup

popup
Same as "atl.popup"
class="page-type-popup"
No header/footer in 5.0

atl.popup
jira.popup

issuesummary
DEPRECATED

atl.general
jira.general


Removed in 5.0

genericaction

atl.general
jira.general

generication
Same as "atl.general"
Mapped to "atl.general" in 5.0
DEPRECATED

atl.general
jira.general

inline

Not recommended for use

atl.inline.dialog
jira.inline.dialog

Not changed

atl.inline.dialog
jira.inline.dialog

login
Not for plugin use

panel-general

(star) new in 5.0

atl.general
jira.general

panel-admin

(star) new in 5.0
class="page-type-admin"

atl.admin
jira.admin

blank

(star) new in 5.0
No header/footer/content panel but does have resources
class="page-type-blank"

content-panel-only

(star) new in 5.0
No header/footer but has the content panel and resources

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport