JIRA: create plugins. Framework Features
Greetings to all.
This article will help beginners in web programming learn how to write plugins under JIRA. At the beginning of work with this system, I myself was confronted with the fact that, firstly, there was not a single sufficiently detailed and Russian-speaking guide. And secondly, most of the articles are designed for quite experienced people.
For a start, I will review the main points and errors when creating plugins, as well as the structure of the JIRA plug-in, which greatly simplifies the task of a novice web programmer.
About configuring and installing Maven and SDK, things needed to create plug-ins, and their integration into the IDE is written in sufficient detail on the Atlassian website, so I’ll only briefly describe what they are for. Maven is a framework on which plug-in creation is implemented. SDK (software development kit) Extends the capabilities of Maven and simplifies the process of creating a plugin, and also adds to Maven a bunch of libraries needed to work with JIRA.
It starts with the selection of the directory for its placement (in the cd C: \ your_directory command line), 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 the choice of name, version, etc., we end up with a skeleton. The skeleton consists of the following main parts:
Located at the root of the plugin. The name, version of the plugin, information about it (the developer, for example) and, most importantly, the necessary libraries are written in this xml file.
There are enough examples in the tutorials on the site indicated above, however, I will mark a couple of problem areas.
If the plugin is not built by the atlas-mvn clean package or atlas-run command on the command line, and does not display errors related to the syntax, then the case is in the pom.xml file.
The most common errors during command line actions:
1) the jira-core dependency has not been uncommented, which gives access to most of the jira libraries and is necessary if you are going to do at least something that is minimally beyond the standard functionality.
2) not quite an error in the pom.xml file, but spent a lot of my time. If you are at home / at work / in the place where you code there is a proxy, then very carefully configure the proxy 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 you need to run mvn install: install with the full path to the mvn.bat file, that is, as follows : C: \ Atlassian \ atlassian-plugin-sdk \ apache-maven \ bin \ mvn install: install ..... , then be sure to 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 thereof. 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 defined by Atlassian, again in the full list in that very place . These modules are quite enough for the implementation of tasks. This includes overriding some JIRA classes.
The thing that is not quite understandable to beginners is also written in this file: the connection between java classes and velocity patterns. Velocity is a page-styling language like jsp. It has its simple syntax, similar to pascal. The main function - depending on the parameters that are passed to it from the java classes to generate partly (in our case) or completely the page code. It is possible to set various conditions, make cycles, etc. And the velocity code is compatible with both html and javascript, which makes it a powerful tool.
Consider an example of creating a custom field module in atlassian-plugin.xml, it is best suited for understanding the principles of constructing the atlassian-plugin.xml file, as well as the velocity patterns. Then we will have the following code:
Consider it in more detail:
name - the name of the module that you will see when viewing the installed plugin
i18n-name-key is the key by which JIRA will search for a human-readable module name in the .properties file (especially relevant for internalization, that is, translating the plugin into several languages)
class is a Java class that defines the behavior of a field. Some methods from it are executed every time when you try 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 like a name, only for description
And, perhaps, the most interesting, resource . Here, velocity files are always specified for custom fields, which will be responsible for displaying the field in various situations, such as editing the field, viewing the field, viewing the field in the “Query Search”, viewing the field when outputting as xml, and so on.
By default, the values ​​for the custom field are transmitted to the velocity files: $ value is the current value, $ customfiled is the field object $ fieldLayoutItem is the field characteristics. Inside the file velocity, there is a call to the #header and #footer objects, which are very rarely touched; usually, what is contained between them is enough to adjust the behavior. In the simplest examples, one html is enough, then it may be necessary to enable javascript. Well, for complex fields you need everything together: the transfer of new parameters to velocity, the conditions and velocity cycles, the skillful combination of the above with html and javascript.
Used, as already mentioned, for the internationalization of its plugin.
It is enough to specify it in the list of resources, make copies with a different ending (for the Russian Federation - MyProject_ru_RU.properties), and, voila, depending on the selected language, the interface will change from English to Russian in my example.
Everything is simple: the atlas-create-jira-plugin-module command allows you to add a new module to your existing project (customfield, rest, project tab). This command modifies atlassian-plugin.xml, adds new java classes and velocity files. It is executed after transition to the project by the cd command . Carefully , by no means always the path to the velocity templates is written correctly in atlassian-plugin.xml. Please note that not all modules can be added this way, some will have to be added manually.
I use Eclipse as the recommended Atlassian development environment. The .project file can be created by the atlas-mvn eclipse: eclipse command. Based on your pom.xml, it also loads the necessary libraries from the maven and atlassian repository.
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 automatically loaded (without a cmd command), which saves time and nerves.
Well, finally, after all the above and writing the code, you can write atlas-mvn clean package on the command line, which will assemble the plugin version for you, or atlas-run, which will assemble the plugin and launch the local Djiru and enjoy the further development and testing process.
This article will help beginners in web programming learn how to write plugins under JIRA. At the beginning of work with this system, I myself was confronted with the fact that, firstly, there was not a single sufficiently detailed and Russian-speaking guide. And secondly, most of the articles are designed for quite experienced people.
For a start, I will review the main points and errors when creating plugins, as well as the structure of the JIRA plug-in, which greatly simplifies the task of a novice web programmer.
About configuring and installing Maven and SDK, things needed to create plug-ins, and their integration into the IDE is written in sufficient detail on the Atlassian website, so I’ll only briefly describe what they are for. Maven is a framework on which plug-in creation is implemented. SDK (software development kit) Extends the capabilities of Maven and simplifies the process of creating a plugin, and also adds to Maven a bunch of libraries needed to work with JIRA.
Creating a plugin
It starts with the selection of the directory for its placement (in the cd C: \ your_directory command line), 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 the choice of name, version, etc., we end up with a skeleton. The skeleton consists of the following main parts:
Pom.xml file
Located at the root of the plugin. The name, version of the plugin, information about it (the developer, for example) and, most importantly, the necessary libraries are written in this xml file.
There are enough examples in the tutorials on the site indicated above, however, I will mark a couple of problem areas.
If the plugin is not built by the atlas-mvn clean package or atlas-run command on the command line, and does not display errors related to the syntax, then the case is in the pom.xml file.
The most common errors during command line actions:
1) the jira-core dependency has not been uncommented, which gives access to most of the jira libraries and is necessary if you are going to do at least something that is minimally beyond the standard functionality.
2) not quite an error in the pom.xml file, but spent a lot of my time. If you are at home / at work / in the place where you code there is a proxy, then very carefully configure the proxy 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 you need to run mvn install: install with the full path to the mvn.bat file, that is, as follows : C: \ Atlassian \ atlassian-plugin-sdk \ apache-maven \ bin \ mvn install: install ..... , then be sure to 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 thereof. 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 defined by Atlassian, again in the full list in that very place . These modules are quite enough for the implementation of tasks. This includes overriding some JIRA classes.
The thing that is not quite understandable to beginners is also written in this file: the connection between java classes and velocity patterns. Velocity is a page-styling language like jsp. It has its simple syntax, similar to pascal. The main function - depending on the parameters that are passed to it from the java classes to generate partly (in our case) or completely the page code. It is possible to set various conditions, make cycles, etc. And the velocity code is compatible with both html and javascript, which makes it a powerful tool.
Consider an example of creating a custom field module in atlassian-plugin.xml, it is best suited for understanding the principles of constructing the atlassian-plugin.xml file, as well as the velocity patterns. Then we will have the following code:
<customfield-type name="MyCF" i18n-name-key="my-first-cf" key="MyCf" class="com.example.cf"> <description key="field-desc">The new field</description> <resource name="view" type="velocity" location="/templates/view.vm"/> <resource name="edit" type="velocity" location="/templates/edit.vm"/> </customfield-type> Consider it in more detail:
name - the name of the module that you will see when viewing the installed plugin
i18n-name-key is the key by which JIRA will search for a human-readable module name in the .properties file (especially relevant for internalization, that is, translating the plugin into several languages)
class is a Java class that defines the behavior of a field. Some methods from it are executed every time when you try 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 like a name, only for description
And, perhaps, the most interesting, resource . Here, velocity files are always specified for custom fields, which will be responsible for displaying the field in various situations, such as editing the field, viewing the field, viewing the field in the “Query Search”, viewing the field when outputting as xml, and so on.
Velocity files
By default, the values ​​for the custom field are transmitted to the velocity files: $ value is the current value, $ customfiled is the field object $ fieldLayoutItem is the field characteristics. Inside the file velocity, there is a call to the #header and #footer objects, which are very rarely touched; usually, what is contained between them is enough to adjust the behavior. In the simplest examples, one html is enough, then it may be necessary to enable javascript. Well, for complex fields you need everything together: the transfer of new parameters to velocity, the conditions and velocity cycles, the skillful combination of the above with html and javascript.
.Properties files
Used, as already mentioned, for the internationalization of its plugin.
It is enough to specify it in the list of resources, make copies with a different ending (for the Russian Federation - MyProject_ru_RU.properties), and, voila, depending on the selected language, the interface will change from English to Russian in my example.
Creating plugin module
Everything is simple: the atlas-create-jira-plugin-module command allows you to add a new module to your existing project (customfield, rest, project tab). This command modifies atlassian-plugin.xml, adds new java classes and velocity files. It is executed after transition to the project by the cd command . Carefully , by no means always the path to the velocity templates is written correctly in atlassian-plugin.xml. Please note that not all modules can be added 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 can be created by the atlas-mvn eclipse: eclipse command. Based on your pom.xml, it also loads the necessary libraries from the maven and atlassian repository.
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 automatically loaded (without a cmd command), which saves time and nerves.
Finish line
Well, finally, after all the above and writing the code, you can write atlas-mvn clean package on the command line, which will assemble the plugin version for you, or atlas-run, which will assemble the plugin and launch the local Djiru and enjoy the further development and testing process.
Source: https://habr.com/ru/post/178871/
All Articles