JIRA: creating plugins. Framework Features
- From the sandbox
- Tutorial
Welcome all.
This article will help beginners in the field of web programming to learn how to write plugins under JIRA. Himself at the beginning of work with this system I was faced with the fact that, firstly, there is not a single sufficiently detailed and Russian-language guide. And secondly, most of the articles are designed for experienced enough people.
To begin with, I will consider the main points and errors when creating plugins, as well as the structure of the JIRA plugin, which greatly simplifies the task of a novice web programmer.
About the configuration and installation of Maven and the SDK, the things necessary to create plugins, and their integration in the IDE is written in sufficient detail on the Atlassian website, therefore, I will only briefly describe why they are needed. Maven is a framework that implements the creation of plugins. SDK (software development kit) Expands the capabilities of Maven and simplifies the process of creating a plug-in, and also adds a bunch of libraries to Maven necessary for working with JIRA.
It starts by selecting the directory for its location (in the command line cd C: \ your_directory ), after which the plug-in skeleton is created with the atlas-create-jira-plugin command . a choice of settings is offered. After such simple operations as choosing a name, version, etc., we have a skeleton in the end. The skeleton consists of the following main parts:
Located at the root of the plugin. This xml file contains the name, version of the plugin, information about it (the developer, for example) and, most importantly, the necessary libraries.
There are enough examples in the tutorials on the site indicated above, however I will outline a couple of problem places.
If the plugin is not built with the atlas-mvn clean package or atlas-run command on the command line, and does not display syntax errors, then it is the pom.xml file.
The most common errors during command-line actions:
1) the jira-core dependency was not uncommented, which gives access to most jira libraries and is necessary if you are going to do at least something that minimally goes beyond the standard functionality.
2) not quite an error in the pom.xml file, but spent a lot of my time. If you have a proxy at home / at work / in the place where you code, then carefully configure the proxies in the Maven configuration file . How to do this - see the Atlassian website.
3) the necessary libraries are not registered. And here a problem may arise: the installation of external libraries in Maven is described on the Maven website, however, if we are dealing with the Atlassian SDK, then run mvn install: install with the full path to the mvn.bat file, i.e. as follows : C: \ Atlassian \ atlassian-plugin-sdk \ apache-maven \ bin \ mvn install: install ....., after which you must add the library to the Maven repository, which is located at% Atlassian_HOME% \ atlassian-plugin-sdk \ repository
Located in src / main / resources.
This file is fully responsible for the interaction between the system and the plugin at the time of installation. It describes the modules that will be included in the plugin, the components and resources that the plugin uses (localization files, javascript, css, images). All possible modules are identified by Atlassian, for a complete list again at that very place . These modules are quite enough for the implementation of tasks. Including, you can override some JIRA classes.
Also, a thing that is not quite clear to beginners is written in this file: the relationship between java classes and velocity templates. Velocity is a page-template language like jsp. It has its own simple syntax similar to pascal. The main function - depending on the parameters that are passed to it from the java classes, generate partially (in our case) or completely the page code. In it you can set various conditions, do cycles, etc. Moreover, the velocity code is compatible with both html and javascript, which makes it a powerful tool.
Consider the example of creating a custom field module in atlassian-plugin.xml, it is best suited for understanding the principles of building the atlassian-plugin.xml file, as well as velocity templates. Then we will have the following code:
Let's consider it in more detail:
name - the name of the module that you will see when viewing the installed
i18n-name-key plugin - the key by which JIRA will search for the human-readable module name in the .properties file (especially relevant for internalization, that is, translating the plugin into several languages)
class - Java class that defines the behavior of the field. Some methods from it are executed every time when trying to view / edit the value of a field, some to check the validity of the value. However, this is a separate story
description - everything is just like with name, only for description
And, perhaps, the most interesting, resource. Here, for custom fields velocity files are always indicated, which will be responsible for displaying the field in various situations, such as editing the field, viewing the field, viewing the field in the "Search for Queries", viewing the field when outputting in the form of xml, etc.
By default, values are transferred to velocity files for a custom field: $ value - current value, $ customfiled - field object $ fieldLayoutItem - field characteristics. Inside the velocity file is a call to the #header and #footer objects, which are rarely touched, usually what is contained between them is enough to configure the behavior. In the simplest examples, one html is enough, then you may need to enable javascript. Well, for complex fields you will need everything together: the transfer of new parameters to velocity, conditions and velocity cycles, skillful combination of the above with html and javascript.
They are used, as was already mentioned in passing, to internationalize their plugin.
It is enough to indicate it in the list of resources, make copies with different endings (for the Russian Federation - MyProject_ru_RU.properties), and voila, depending on the language chosen, the interface will change from English to Russian in my example.
Everything is simple here: the atlas-create-jira-plugin-module command allows you to add a new module (customfield, rest, project tab) to an existing project. This command modifies atlassian-plugin.xml, adds new java classes and velocity files. It is executed after the transition to the project with the cd command . Accurately , far from always the path to the templates of the city is written correctly in atlassian-plugin.xml. Please note that not all modules can be added in this way, some will have to be added manually.
I use Eclipse as the recommended Atlassian development environment. The .project file will help you create the atlas-mvn eclipse: eclipse command. Based on your pom.xml, it also loads the necessary libraries from the maven and atlassian repositories.
UPDATE: after I tried building plugins in Intellij IDEA, I realized that IDEA is my choice. Most of the dependencies defined in .pom files are loaded automatically (without a command in cmd), which significantly saves time and nerves.
And finally, after all the above and writing the code, you can write atlas-mvn clean package on the command line, which will collect the plugin version for you, or atlas-run, which will collect the plugin and launch the local Jira and enjoy the further development and testing process.
This article will help beginners in the field of web programming to learn how to write plugins under JIRA. Himself at the beginning of work with this system I was faced with the fact that, firstly, there is not a single sufficiently detailed and Russian-language guide. And secondly, most of the articles are designed for experienced enough people.
To begin with, I will consider the main points and errors when creating plugins, as well as the structure of the JIRA plugin, which greatly simplifies the task of a novice web programmer.
About the configuration and installation of Maven and the SDK, the things necessary to create plugins, and their integration in the IDE is written in sufficient detail on the Atlassian website, therefore, I will only briefly describe why they are needed. Maven is a framework that implements the creation of plugins. SDK (software development kit) Expands the capabilities of Maven and simplifies the process of creating a plug-in, and also adds a bunch of libraries to Maven necessary for working with JIRA.
Plugin creation
It starts by selecting the directory for its location (in the command line cd C: \ your_directory ), after which the plug-in skeleton is created with the atlas-create-jira-plugin command . a choice of settings is offered. After such simple operations as choosing a name, version, etc., we have a skeleton in the end. The skeleton consists of the following main parts:
Pom.xml file
Located at the root of the plugin. This xml file contains the name, version of the plugin, information about it (the developer, for example) and, most importantly, the necessary libraries.
There are enough examples in the tutorials on the site indicated above, however I will outline a couple of problem places.
If the plugin is not built with the atlas-mvn clean package or atlas-run command on the command line, and does not display syntax errors, then it is the pom.xml file.
The most common errors during command-line actions:
1) the jira-core dependency was not uncommented, which gives access to most jira libraries and is necessary if you are going to do at least something that minimally goes beyond the standard functionality.
2) not quite an error in the pom.xml file, but spent a lot of my time. If you have a proxy at home / at work / in the place where you code, then carefully configure the proxies in the Maven configuration file . How to do this - see the Atlassian website.
3) the necessary libraries are not registered. And here a problem may arise: the installation of external libraries in Maven is described on the Maven website, however, if we are dealing with the Atlassian SDK, then run mvn install: install with the full path to the mvn.bat file, i.e. as follows : C: \ Atlassian \ atlassian-plugin-sdk \ apache-maven \ bin \ mvn install: install ....., after which you must add the library to the Maven repository, which is located at% Atlassian_HOME% \ atlassian-plugin-sdk \ repository
Atlassian-plugin.xml file
Located in src / main / resources.
This file is fully responsible for the interaction between the system and the plugin at the time of installation. It describes the modules that will be included in the plugin, the components and resources that the plugin uses (localization files, javascript, css, images). All possible modules are identified by Atlassian, for a complete list again at that very place . These modules are quite enough for the implementation of tasks. Including, you can override some JIRA classes.
Also, a thing that is not quite clear to beginners is written in this file: the relationship between java classes and velocity templates. Velocity is a page-template language like jsp. It has its own simple syntax similar to pascal. The main function - depending on the parameters that are passed to it from the java classes, generate partially (in our case) or completely the page code. In it you can set various conditions, do cycles, etc. Moreover, the velocity code is compatible with both html and javascript, which makes it a powerful tool.
Consider the example of creating a custom field module in atlassian-plugin.xml, it is best suited for understanding the principles of building the atlassian-plugin.xml file, as well as velocity templates. Then we will have the following code:
The new field Let's consider it in more detail:
name - the name of the module that you will see when viewing the installed
i18n-name-key plugin - the key by which JIRA will search for the human-readable module name in the .properties file (especially relevant for internalization, that is, translating the plugin into several languages)
class - Java class that defines the behavior of the field. Some methods from it are executed every time when trying to view / edit the value of a field, some to check the validity of the value. However, this is a separate story
description - everything is just like with name, only for description
And, perhaps, the most interesting, resource. Here, for custom fields velocity files are always indicated, which will be responsible for displaying the field in various situations, such as editing the field, viewing the field, viewing the field in the "Search for Queries", viewing the field when outputting in the form of xml, etc.
Velocity files
By default, values are transferred to velocity files for a custom field: $ value - current value, $ customfiled - field object $ fieldLayoutItem - field characteristics. Inside the velocity file is a call to the #header and #footer objects, which are rarely touched, usually what is contained between them is enough to configure the behavior. In the simplest examples, one html is enough, then you may need to enable javascript. Well, for complex fields you will need everything together: the transfer of new parameters to velocity, conditions and velocity cycles, skillful combination of the above with html and javascript.
.Properties files
They are used, as was already mentioned in passing, to internationalize their plugin.
It is enough to indicate it in the list of resources, make copies with different endings (for the Russian Federation - MyProject_ru_RU.properties), and voila, depending on the language chosen, the interface will change from English to Russian in my example.
Creating a plugin module
Everything is simple here: the atlas-create-jira-plugin-module command allows you to add a new module (customfield, rest, project tab) to an existing project. This command modifies atlassian-plugin.xml, adds new java classes and velocity files. It is executed after the transition to the project with the cd command . Accurately , far from always the path to the templates of the city is written correctly in atlassian-plugin.xml. Please note that not all modules can be added in this way, some will have to be added manually.
Preparing a project for import into eclipse
I use Eclipse as the recommended Atlassian development environment. The .project file will help you create the atlas-mvn eclipse: eclipse command. Based on your pom.xml, it also loads the necessary libraries from the maven and atlassian repositories.
UPDATE: after I tried building plugins in Intellij IDEA, I realized that IDEA is my choice. Most of the dependencies defined in .pom files are loaded automatically (without a command in cmd), which significantly saves time and nerves.
Finish line
And finally, after all the above and writing the code, you can write atlas-mvn clean package on the command line, which will collect the plugin version for you, or atlas-run, which will collect the plugin and launch the local Jira and enjoy the further development and testing process.