JIRA is widely used in the Mail.Ru Group. Now we use this system not only for project management and tracking errors, but also for organizing a wide variety of operational processes - recruiting, negotiating agreements, business trips and so on. This, on the one hand, is very convenient, since many business processes fit perfectly on the Issue model in JIRA. However, specific functions that are implemented using specially written plugins are often also required.

A few years ago, we were content with simple third-party JS scripts and general-purpose plugins. Over time, JIRA penetrated deeper into operational processes, respectively, and the requirements for functions sharpened specifically for these processes grew. We currently have a separate division whose task is to develop customized functionality for JIRA and Confluence. As part of it, good expertise has been accumulated.

Now many third-party JIRA plugins cannot boast of a high-quality interface. This applies even to some paid plugins. However, all the tools for the rapid development of convenient and beautiful interfaces are. The article discusses one of them - AUI Framework (Atlassian User Interface Framework).

It is assumed that the reader is familiar with how the plugin can be made in principle. If not, then you can read about it, for example, here .

1. What is the AUI Framework?

The AUI Framework consists of a set of scripts, style sheets, templates, and other resources used to create the interface. Developed and maintained by Atlassian. In general, in the AUI Framework, you can find roughly the same thing as in another framework like Bootstrap. However, the AUI Framework does not need to be additionally embedded in the page and loaded with it, and all components are completely identical in style to the JIRA itself - it is built with their help. Thus, the resulting plugin will look great and work in the system.

Developing an interface using the library can be much faster, and using the result is a pleasure. Our employees using the developed functionality are very satisfied.

2. The main components of the framework

It is impossible to consider all the components within the framework of one article, and it is not necessary, there is documentation for this. Instead, the most useful ones are described below - those that make our life as easy as possible and are used in almost every project.

2.1 Page Layout and Decorators

If in the plugin you need some page, for example, to manage the settings, you will need to make it up. There are 2 approaches for this.

The first method is to create this page from scratch, but in such a way that it completely repeats the design of standard ones using the Page component . In this case, the header and footer of the page can be changed as you want.

If these changes are not required, a different approach would be a better choice - using a decorator. This is the name of the tool for automatically framing a page in accordance with one of the standard styles.

A common task may be, for example, quickly creating a page in the Administration area. This can be done very simply using the decorator.admin. Only content that is highlighted in purple in the screenshot will be needed to layout. Additionally, you can specify which section the page belongs to and which tab corresponds to it using the appropriate meta tags.



Here is the HTML code corresponding to this page:

A complete list of possible decorators can be found here .

2.2 Dialogs

We often use dialogs, for example, to allow the user to create or modify an entry in a table with an AJAX request. On the one hand, this is convenient for the user, and on the other, it is implemented faster than using a separate page.

There are 2 versions of modal dialogs in the framework - Dialog and Dialog 2 . Dialog 2 is a newer component that provides more flexibility, but is in the Experimental status. This means that there is a chance of changing the API in the new version of the framework. Despite this, we use it.

2.3 AUI Select2

This component is a jQuery Select2 plugin styled according to the Atlassian Design Guidelines . It provides great features such as searching by value, AJAX-loading of options, custom display of options, and others.



We often use it to make it convenient to choose an option.

2.4 Buttons

As with many other frameworks, various button styles are supported :

2.5 Design Elements

There are various tools available to make the page brighter and easier to read. One of them is the icons . They can be used directly in the text or inserted into links and buttons:



We have configured Gravatar in JIRA, which loads images from profiles on the intranet. Therefore, it makes sense to display an avatar next to user names. It looks like this:



Statuses can be issued in the form of highlighted labels . This allows the user not to read the text after some time, paying attention only to the color:



In addition to the above-described specialized components, the framework automatically draws up headings, paragraphs and lists.

You can apply design to the table.by adding a class aui. Additionally, you can add a class aui-table-rowhover. This will automatically highlight the entire line when you hover. Interestingly, this feature is not described in the documentation. Like some other things, you can find out about this by analyzing the layout of JIRA pages using AUI.

2.6 Helper scripts

The jQuery library is not part of the AUI Framework, however it is still built into JIRA. Access to it can be obtained through AJS.$. We usually wrap scripts in:

(function ($) {
    AJS.toInit(function () {
        // Script starts here...
    });
})(AJS.$);

The first wrapper allows you to access jQuery in its usual form, and the second ensures that by the time the execution of our scripts begins, the DOM tree and AUI will already be initialized.

There is a special component for implementing the work of hot keys.

AJS also contains several other useful helper functions: to get the full path to the application, load localized strings, and so on. Read more about them here .

3. Examples of what can be done

Let's look at a few examples of our real interface tasks solved with the framework.

One of them was the creation and storage of counterparties - some entities with a small set of parameters. This data was imported from SAP, and there were a lot of them - several tens of thousands. We decided not to store them as an issue, overloading the system, but to save them to the database using the Active Objects API. Accordingly, the ability to manage counterparties was needed.

An interface was implemented with paging, search and the ability to manage these entities. The service information about synchronization was hidden in the tooltip, which is displayed only for synchronized counterparties:



Another task was to display a table with integer data, some of which should have been editable. There were no such components in AJS, so we just adapted the layout and scripts of Inline Issue Editing, having figured out the source:



As a final example, let us select the unit from the list. Ordinary Select could do the job, but we wanted to show the head of the department to the user in order to simplify the choice. Therefore, we used AUI Select2. Here's what happened:

4. Undocumented features

There are some features not described in the documentation of the framework and built-in libraries in JIRA. It is clear that in future versions of JIRA they may change or disappear altogether, but, firstly, this is unlikely, and secondly, the benefits of using them are quite large.

As an example, we cite the css class mentioned above aui-table-rowhoverfor tables. It will definitely not disappear anywhere in the next versions of JIRA, since it is used in almost all standard tables.

Another example is dimming and blocking a page. We wanted to do this when invoking synchronization on the described counterparty management page. Looking at the JIRA sources, we found that this has already been implemented with:

AJS.dim();
JIRA.Loading.showLoadingIndicator();

and correspondingly

AJS.undim();
JIRA.Loading.hideLoadingIndicator();

In general, we recommend looking for where the desired functionality is already in JIRA and then looking at the source for how it is implemented. Often this allows you to get the desired result easier and faster.

5. Pitfalls

In general, the framework behaves quite stably. The only bug we encountered during development was the disappearance of Inline Dialog when clicking on input inside it. Again, digging a bit in the source, I managed to find workaround - preventing the event of a click on an element from being transmitted inside the dialog:

content.click(function(e) {
    e.stopPropagation();
});

All known problems can be found out and reported in the official bugtracker , but we don’t think you will need it.

It should also be understood that the version of the framework (and, accordingly, the set of components) depends on the version of JIRA under which the plugin is running. If you need support for several versions of JIRA, you should not forget about testing under them. When developing our internal plugins, we do not do this, as we write immediately under the current version of JIRA. But still, before upgrading JIRA to the new version, we have to consider the Release Notes published by Atlassian.

6. What next?

• A pretty detailed white paper on AUI Framework components.
• The official documentation on the AUI Framework itself is about how you can implement it in your project, participate in the development and prepare for the update.
• A sandbox in which you can play with the components and see how they will look.

7. Conclusion

Developing a quality interface is not the only, but very important step in creating a good plugin. The AUI Framework makes this development easier, faster and more efficient. And do not be afraid of analyzing the source code of the framework - this allows you to better understand it and interact with it.

In addition to the interface, there are other high-quality development practices that are invisible to the user. We will talk about them in one of the following posts.