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.

1
2
<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 new in 5.0	atl.general jira.general
		panel-admin new in 5.0 class="page-type-admin"	atl.admin jira.admin
		blank new in 5.0 No header/footer/content panel but does have resources class="page-type-blank"	--
		content-panel-only new in 5.0 No header/footer but has the content panel and resources	--