JIRA: создание плагинов. Особенности фреймворка

Приветствую всех.
Эта статья поможет начинающим в области веб-программирования научиться писать плагины под JIRA. Сам в начале работы с этой системой столкнулся с тем, что, во-первых, нет ни одного достаточно подробного и русскоязычного гайда. А во-вторых, большая часть статей рассчитана на достаточно опытных людей.
Для начала, я рассмотрю основные моменты и ошибки при создании плагинов, а так же структуру JIRA плагина, что сильно упростит задачу начинающему веб-программисту.

Про настройку и установку Maven и SDK, вещей необходимых для создания плагинов, и их интеграцию в IDE достаточно подробно написано на сайте Atlassian ^[1], поэтому я лишь вкратце опишу для чего они нужны. Maven — фреймворк, на котором реализовано создание плагинов. SDK (software development kit) Расширяет возможности Maven и упрощает процесс создания плагина, а так же добавляет в Maven кучу библиотек, необходимых для работы с JIRA.

Создание плагина

Начинается с выбора директории для его размещения(в командой строке cd C:your_directory), после чего создается скелет плагина командой atlas-create-jira-plugin. предлагается выбор настроек. После таких нехитрых операций как выбор названия, версии итд мы имеем в итоге скелет. Скелет состоит из следующих основных частей:

Файл pom.xml

Располагается в корне плагина. В данном xml файле прописываются имя, версия плагина, информация о нем (разработчик, к примеру) и, самое важное, необходимые библиотеки.
Примеров достаточно в туториалах на сайте, указанном выше, однако я обозначу пару проблемных мест.
Если плагин не собирается командой atlas-mvn clean package или atlas-run в командной строке, и не выводит ошибок, связанных с синтаксисом, то дело именно в файле pom.xml.
Самые распространенные ошибки при действиях из командной строки:
1) не была раскомментирована зависимость jira-core, которая дает доступ к большей части библиотек джиры и необходима в том случае, если вы собираетесь сделать хоть что-то, что минимально выходит за пределы стандартного функционала.
2) не совсем ошибка в файле pom.xml, однако потратила кучу моего времени. Если у Вас дома/на работе/в месте, где вы кодите есть прокси, то крайне внимательно настраивайте прокси в конфигурационном файле Maven. Как это сделать — см. сайт Atlassian.
3) не прописаны нужные библиотеки. И здесь может возникнуть проблема: установка внешних библиотек в Maven описана на сайте Maven, однако, в случае, если мы имеем дело с Atlassian SDK, то запускать mvn install:install нужно с указанием полного пути к файлу mvn.bat, то есть следующим образом: C:Atlassianatlassian-plugin-sdkapache-mavenbinmvn install:install.....

Файл atlassian-plugin.xml

Находится в src/main/resources.
Этот файл целиком и полностью отвечает за взаимодействие между системой и плагином в момент установки оного. В нем описываются в модули, которые будут включены в плагин, компоненты и ресурсы, которыми плагин пользуется (файлы локализации, javascript, css, images). Все возможные модули определены Atlassian, за полным списком снова в то самое место ^[2]. Этих модулей вполне хватает для реализации задач. В том числе можно и переопределять некоторые классы JIRA.
Так же в этом файле прописывается не вполне понятная новичкам вещь: связь между java классами и шаблонами velocity. Velocity — язык шаблонирования страниц, наподобие jsp. Имеет свой простой синтаксис, похожий на pascal. Основная функция — в зависимости от параметров, которые в него передаются из java классов генерировать частично (в нашем случае) или полностью код странички. В нем можно ставить различные условия, делать циклы и т.д. Причем код velocity совместим и с html, и с javascript, что делает его мощнейшим инструментом. Рассмотрим пример создания кастомного поля, он наилучшим образом подходит для осознания принципов построения файла atlassian-plugin.xml, а так же шаблонов velocity. Тогда мы будем иметь следующий код:

<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>

Рассмотрим его поподробнее:
name — имя модуля, которое вы увидите при просмотре установленного плагина
i18n-name-key — ключ, по которому JIRA будет искать human-readable название модуля в файле .properties (особенно актуально для интернализации, то бишь перевода плагина на несколько языков)
class — Java class, который определяет поведение поля. Некоторые методы из него выполняются каждый раз при попытке просмотра/редактирования значения поле, некоторые для проверки валидности значения. Впрочем, это отдельная история
description — тут все как с name, только для описания
И, пожалуй, самое интересное, resource. Здесь для кастомных полей всегда указываются файлы velocity, которые будут отвечать за отображение поля в различных ситуаций, таких как редактирование поля, просмотр поля, просмотр поля в «Поиске запросов», просмотр поля при выводе в виде xml итд.

Файлы velocity

По умолчанию в файлы velocity для кастомного поля передаются значения: $value — текущее значение, $customfiled — объект поля $fieldLayoutItem — характеристики поля. Внутри velocity файла находится вызов объектов #header и #footer, которые трогаются очень редко, обычно для настройки поведения достаточно того, что содержится между ними. В простейших примерах достаточно одного html, потом может возникнуть необходимость подключить javascript. Ну а для сложных полей потребуется все вместе: и передача новых параметров в velocity, условия и циклы velocity, умелое объединение описанного выше с html и javascript.

Файлы .properties

Используются, как уже было вскользь упомянуто, для интернационализации своего плагина.
Достаточно указать его в списке ресурсов, сделать копии с разным окончанием (для РФ — MyProject_ru_RU.properties), и, вуаля, в зависимости от выбранного языка будет меняться интерфейс с англоязычного на русский в моем примере.

Создание модуля плагина

Тут все просто: команда atlas-create-jira-plugin-module позволяет добавить в существующий проект новый модуль (customfield, rest, project tab). Эта команда модифицирует atlassian-plugin.xml, добавляет новые java классы и файлы velocity. Выполняется после перехода в проект командой cd. Аккуратно, далеко не всегда путь к шаблонам велосити прописывается правильно в atlassian-plugin.xml. Прошу заметить, что далеко не все модули можно добавить таким образом. Некоторые придется добавлять вручную.

Подготовка проекта к импорту в eclipse

Eclipse я использую как рекомендуемую Atlassian среду разработки. Файл .project поможет создать команда atlas-mvn eclipse:eclipse. На основе Вашего pom.xml она так же подгружает необходимые библиотеки из репозитория maven и atlassian.

Финишная прямая

Ну и, наконец, после всего пройденного выше и написания кода можно написать atlas-mvn clean package, что соберет для Вас версию плагина, или atlas-run, что соберет плагин и запустит локальную Джиру и наслаждаться дальнейшим процессом разработки и тестирования.

Автор: MrSeventh

Источник ^[3]