High-quality interface JIRA-plugin using the AUI Framework

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

A few years ago we were content with simple JS scripts and third-party general purpose plugins. Over time, JIRA penetrated into operational processes deeper, respectively, and the requirements for functions sharpened specifically for these processes grew. Currently we have a separate division whose task is to develop customized functionality for JIRA and Confluence. As part of it accumulated a good expertise.
')
Now, many third-party JIRA plug-ins cannot boast 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 - the AUI Framework (Atlassian User Interface Framework).

It is assumed that the reader is familiar with how a 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 about the same thing as in another framework like Bootstrap. However, the AUI Framework does not need to be additionally embedded on the page and loaded by it, and all components are completely identical in style with JIRA itself - it is built with them. 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 one article, and it is not necessary, there is documentation for this. Instead, the most useful of them are described below - those that make our lives as easy as possible and are used in almost every project.

2.1 Page Layout and Decorators

If you need a page in a plugin, for example, to manage settings, you will need to impose it. For this there are 2 approaches.

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

If these changes are not required, a different approach would be a better choice — use a decorator. So called tool for automatic framing of the page in accordance with one of the standard styles.

A frequent task can be, for example, quickly create a page in the Administration area. This can be done very simply using the admin decorator. Layout will only need content highlighted in purple in the screenshot. Additionally, you can specify which section the page belongs to and which tab it corresponds to using the corresponding meta tags.

Here is the HTML code for this page:

 <html> <head> <title>$i18n.getText( "ru.mail.jira.plugins.recruitment.configuration.title" )</title> <meta name="decorator" content="admin" /> <meta name="admin.active.section" content="admin_plugins_menu/recruitment-admin-section"> <meta name="admin.active.tab" content="ru.mail.jira.plugins.recruitment:configuration-link"> </head> <body> <!--,   ,  --> </body> </html>

A full list of possible decorators can be found here .

2.2 Dialogues

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

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

2.3 AUI Select2

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

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

2.4 Buttons

As in many other frameworks, various styles of buttons are supported:

2.5 Design Elements

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

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

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

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

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

2.6 Auxiliary scripts

The jQuery library is not part of the AUI Framework, but is still embedded in JIRA. It can be accessed through AJS.$ . We usually wrap the scripts in:

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

The first wrapper allows you to access jQuery in the usual way, and the second ensures that the DOM tree and AUI are already initialized by the time you start executing our scripts.

There is a special component for the implementation of the hot keys.

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

3. Examples of what can be done

Let's look at some examples of our real interface problems solved using the framework.

One of them was the creation and storage of counterparties - certain 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 in the form of issue, overloading the system, but to save them into the database using the Active Objects API. Accordingly, the ability to manage counterparties was needed.

An interface with paging, search and control of these entities was implemented. Synchronization utility information 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. In AJS there were no such components, so we just adapted the layout and the Inline Issue Editing scripts, having understood the source code:

As a final example, we’ll give the choice of a unit from the list. The task could have been handled by the usual Select, but we wanted to show the user to the head of the department in order to simplify the selection. 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 the built-in JIRA libraries. It is clear that in the next versions of JIRA they may change or disappear altogether, but, firstly, this is unlikely, and, secondly, the benefits from their use are quite large.

As an example, we give the above-mentioned css-class aui-table-rowhover for tables. It will definitely not disappear anywhere in the upcoming versions of JIRA, as it is used in almost all standard tables.

Another example is the darkening and blocking of the page. We wanted to do this when we called up synchronization on the described page for managing contractors. Looking at the sources of JIRA, we found that it was already implemented using:

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

and correspondingly

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

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

5. Reefs

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

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

All known problems can be found and reported in the official bug tracker , but we do not think that 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 multiple versions of JIRA, you need to not forget about testing under them. When developing our internal plug-ins, we do not do this, since we write directly to the current version of JIRA. But still, before upgrading JIRA to a new version, we have to consider the Release Notes published by Atlassian.

6. What's next?

Rather detailed official documentation on the components of the AUI Framework.
The official documentation on the AUI Framework itself is about how you can integrate it into your project, participate in the development and prepare for the update.
Sandbox where you can play with the components and see how they will look.

7. Conclusion

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

In addition to the interface, there are other, invisible to the user practice quality development. We will tell about them in one of the following posts.

Source: https://habr.com/ru/post/243543/

All Articles