Написание гаджетов для Jira

Написание гаджетов для Jira

 

Обзор учебника

В этом уроке мы создадим новый атласский гаджет для Jira, соберем его внутри приложения, воспользуемся ресурсом REST, чтобы предоставить ему данные, и поговорим о гаджете в этом ресурсе. Гаджет, который мы сделаем, отобразит проекты в вашем экземпляре Jira, которые может видеть текущий пользователь.

Atlassian внедрил некоторые из спецификаций OpenSocial во всех своих приложениях. Гаджет, который вы напишете здесь, на самом деле является гаджетом OpenSocial (также называемым гаджетом Google) с каким-то специальным соусом для Jira. Мы примем мимолетное знакомство с гаджетами, но в случае, если они новы для вас, есть пространство, посвященное созданию гаджетов.

Приложение гаджета будет состоять из следующих компонентов:

1. Файл спецификации гаджета для хранения XML и JavaScript гаджета.
2. Java-классы, реализующие ресурс REST, который будет использовать гаджет.
3. Ресурсы для отображения пользовательского интерфейса приложения.
4. Дескриптор приложения для включения модуля плагина в Jira.

Все эти компоненты будут содержаться в одном JAR-файле. Каждый компонент далее обсуждается в примерах ниже.

Об этих инструкциях

Вы можете использовать любую поддерживаемую комбинацию операционной системы и IDE для создания этого приложения. Эти инструкции были написаны с использованием IntelliJ IDEA 2018.1 на Ubuntu Linux. Если вы используете другую операционную систему или комбинацию IDE, вы должны использовать эквивалентные операции для своей конкретной среды.

 

Этот учебник был последний раз проверен с помощью Jira 7.10.0 с использованием Atlassian Plugin SDK 6.3.10.

Прежде чем вы начнете

 

Чтобы получить максимальную отдачу от этого урока, вы должны знать следующее:

1. Основы разработки Java, такие как классы, интерфейсы, методы и т. д.
2. Как создать проект Atlassian plugin с помощью Atlassian Plugin SDK.

 

Исходный код

Мы рекомендуем вам проработать этот учебник. Если вы хотите пропустить или проверить свою работу, когда закончите, вы можете найти исходный код приложения на Atlassian Bitbucket.

Чтобы клонировать репозиторий, выполните следующую команду:

git clone https://bitbucket.org/atlassian_tutorial/jira-gadget-2.git

Кроме того, вы можете загрузить исходный код в виде ZIP-архива.

 

Шаг 1. Создайте проект приложения

На этом этапе вы создадите свой скелет приложения, используя Atlassian Plugin SDK.

 

1. Настройте SDK Atlassian Plugin и создайте проект, если вы этого еще не сделали.
2. Откройте терминал и перейдите в каталог, в котором вы хотите сохранить свой проект.
3. Чтобы создать скелет приложения, выполните следующую команду:

atlas-create-jira-plugin

 

4. Чтобы определить ваше приложение, введите следующую информацию при появлении запроса.

 

5. Подтвердите свои записи при появлении запроса.

 

SDK генерирует домашнюю директорию проекта с файлами проекта, такими как POM (то есть файл определения объектной модели проекта), исходный код заглушки и ресурсы приложения.

 

6. Перейдите в каталог, созданный на предыдущем шаге.

 

7. Удалите тестовые каталоги.

 

Настройка тестирования для вашего приложения не входит в этот учебник. Чтобы удалить сгенерированный тестовый скелет, выполните следующие команды:

rm -rf ./src/test/java
rm -rf ./src/test/resources/

8. Удалите ненужные файлы классов Java.

rm -rf ./src/main/java/com/atlassian/plugins/tutorial/*

9. Импортируйте проект в свою избранную среду IDE.

Шаг 2. Просмотрите и настройте код заглушки

Это хорошая идея, чтобы ознакомиться с файлом конфигурации проекта, известным как POM. POM определяет общие настройки для проекта, включая зависимости проекта и настройки сборки.

SDK генерирует и поддерживает POM самостоятельно, по большей части. Однако вам необходимо вручную настроить некоторые из включенных метаданных для вашего проекта.

1. Перейдите в каталог проекта, созданный SDK, и откройте файл pom.xml.
2. Добавьте название своей компании или организации и URL вашего сайта в качестве значений name и url элемента organization:

<organization>
<name> Пример компании</name>
<url>http://www.example.com/</url>
</organization>

3. Обновите элемент description :

<description></description>

4. Сохраните файл.

Шаг 3. Отредактируйте файл дескриптора приложения

1. Перейдите в src / main / resources / и откройте файл дескриптора приложения atlassian-plugin.xml.
2. Добавить объявление модуля для спецификации гаджета:

<gadget key="tutorial-gadget" name="JIRA Tutorial Gadget" location="gadget.xml"/>

Гаджет - это модуль в atlassian-plugin.xml, как и любой другой модуль Jira. Необходимо отметить три свойства:

• key должен быть уникальным для всех модулей этого приложения.
• name - это имя, под которым модуль плагина будет отображаться в консоли администрирования Jira.
• location - путь к файлу спецификации гаджета, относительно src / main / resources.

3. Добавьте resources для пакета сообщений:

<resource type="download" name="i18n/ALL_ALL.xml" location="i18n/ALL_ALL.xml">
<param name="content-type" value="text/xml; charset=UTF-8"/>
</resource>

Создание URL-адресов для пакетов сообщений

 

Во время рендеринга гаджета __ATLASSIAN_BASE_URL__ в XML-файле гаджета автоматически заменяется настроенным базовым URL-адресом Jira. Остальная часть URL-адреса загрузки создается из ключа приложения atlassian-plugin.xml (в данном случае com.atlassian.plugins.tutorial.jira-gadget-tutorial-plugin) и значения ключа resources (в этом случае i18n / ALL_ALL. XML).

Ниже приведена atlassian-plugin.xml для нашего приложения:

<atlassian-plugin key="${atlassian.plugin.key}"
name="JIRA Gadget Tutorial Plugin"
pluginsVersion="2">
<!-- Содержит метаданные плагина.  -->
<plugin-info>
<description>Пример плагина, показывающий, как добавить гаджет в JIRA. </description>
<vendor name="Atlassian" url="http://www.atlassian.com"/>
<version>1.0</version>
</plugin-info>

<!--
Регистрирует спецификацию гаджета как модуль плагина. Это позволяет гаджету отображаться в каталоге гаджета, а также позволяют администраторам отключить / включить гаджет.
-->
<gadget key="tutorial-gadget" name="JIRA Tutorial Gadget" location="gadget.xml"/>

<!-- Делает сообщения гаджета Locale доступными для использования гаджета. -->
<resource type="download" name="i18n/ALL_ALL.xml" location="i18n/ALL_ALL.xml">
<param name="content-type" value="text/xml; charset=UTF-8"/>
</resource>

<!--
Автоматически находит все классы ресурсов JAX-RS в плагине и
публикует их.
-->
<rest key="tutorial-gadget-rest-resources" path="/tutorial-gadget" version="1.0">
<description>Предоставляет ресурс REST для списка проектов.</description>
</rest>

</atlassian-plugin>

4. Чтобы поддерживать включенный модуль REST, добавьте следующие зависимости в файл pom.xml в элементе dependencies:

<dependency>
<groupId>javax.ws.rs</groupId>
<artifactId>jsr311-api</artifactId>
<version>1.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.atlassian.plugins.rest</groupId>
<artifactId>atlassian-rest-common</artifactId>
<version>1.0.2</version>
<scope>provided</scope>
</dependency>

5. Сохраните изменения.

Шаг 4. Создайте спецификацию гаджета

Теперь вы готовы написать код для работы нашего гаджета. Полную информацию о создании спецификации гаджета см. в документации Гаджеты Atlassian .

1. Перейдите в src / main / resources / и создайте спецификатор гаджета gadget.xml.
2. Добавьте в файл следующий код:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="__MSG_gadget.title__" directory_title="__MSG_gadget.title__"
description="__MSG_gadget.description__">
<Optional feature="gadget-directory">
<Param name="categories">
JIRA
</Param>
</Optional>
<Optional feature="atlassian.util" />
<Optional feature="auth-refresh" />
<Require feature="views" />
<Require feature="settitle"/>
<Require feature="oauthpopup" />
#oauth
<Locale messages="__ATLASSIAN_BASE_URL__/download/resources/com.atlassian.plugins.tutorial.jira-gadget-tutorial-plugin/i18n/ALL_ALL.xml"/>
</ModulePrefs>
<Content type="html" view="profile">
<!-- omitted for now -->
</Content>
</Module>

Раздел ModulePrefs - это контейнер метаданных для гаджета: заголовок, название каталога, описание и т. д. Раздел Content содержит HTML и / или JavaScript, которые управляют поведением гаджета. Мы оставили его пустым, пока мы более внимательно посмотрим на ModulePrefs.

Есть несколько важных замечаний:

 

• Свойства __MSG_gadget.title__ и __MSG_gadget.description__ заменяются во время выполнения пакетами гаджета, указанными в элементах Locale. Пакет находится в файле src / main / resources / i18n / ALL_ALL.xml.
• Элемент Locale указывает гаджету, где можно найти пакеты сообщений. Атрибут messages принимает URL-адрес. Мы покажем, как вывести пакет сообщений на следующем шаге.
• Элементы oauthpopup и auth-refresh необходимы для гаджета для аутентификации в Jira. Подробнее об аутентификации гаджета.
• Наконец, обратите внимание на дополнительную функцию гаджета-каталога Optional gadget-directory. Он указывает, что гаджет предназначен для Jira и должен быть помещен в категорию Jira в браузере каталога гаджетов. Без этого гораздо труднее найти и использовать гаджеты из браузера каталога.

Вот сам набор сообщений XML в файле src / main / resources / i18n / ALL_ALL.xml:

<messagebundle>
<msg name="gadget.title">Тестирование  гаджета учебника JIRA</msg>
<msg name="gadget.description">A sample gadget to install into JIRA.</msg>
</messagebundle>

3. Сохраните файл.

Шаг 5. Настройте ресурс REST

Наш гаджет будет потреблять ресурс REST, чтобы показать, как получать динамические данные в гаджете. Полное обсуждение того, как писать ресурс REST, выходит за рамки данного руководства, но для этого есть еще один учебник: Написание служб REST. Мы будем использовать обновленную версию ресурса, разработанную в этом учебнике в нашем приложении. См. Учебник REST, чтобы узнать, как настроить ресурс REST для этого гаджета (или просто скопировать элементы REST из этого примера кода учебника).

Шаг 6. Используйте JavaScript, чтобы получить проекты в гаджет

На этом этапе вы разработаете JavaScript для вызова ресурса REST и отображения информации в гаджете. На этом этапе вам настоятельно рекомендуется прочитать документацию по использованию фреймворка JavaScript для гаджета Atlassian, так как она поможет вам понять код, который вы собираетесь написать.

1. Перейдите в src / main / resources /, откройте файл gadget.xml и давайте посмотрим на раздел Content:

<Content type="html" view="profile">
<![CDATA[
#requireResource("com.atlassian.jira.gadgets:common")
#includeResources()

<h1>Hello from the Atlassian Gadget Tutorial!</h1>

(function () {
var gadget = AJS.Gadget({
baseUrl: "__ATLASSIAN_BASE_URL__",
useOauth: "/rest/gadget/1.0/currentUser",
view: {}
});
})();
</script>
]]>
</Content>

Здесь обратите внимание на следующее:

• #requireResource () / # includeResources (), который подробно описан в документации по Atlasian Gadgets, используется здесь, чтобы внедрить javascript-фреймворк гаджета Jira. Директива #requireResource определяет модуль web-resource внутри приложения, а #includeResources выписывает теги HTML для ресурса на месте. #includeResources достаточно умен, чтобы писать теги style для веб-ресурса CSS, script для ресурса JavaScript и т. д.
• Разве это не WebResourceManager? Если вы ранее писали приложения Confluence или Jira, вы можете распознать эти директивы как методы в WebResourceManager.
• var gadget = AJS.Gadget создает объект гаджета. Этот объект находится из фреймворка JavaScript и документирован в документации по гаджетам Atlassian. В этом разделе мы укажем минимальный размер рабочего гаджета.
  • Гаджет должен знать свой базовый URL для правильной работы. Это обеспечивается тем же системным свойством __ATLASSIAN_BASE_URL__system, которое использовалось в элементе Locale внутри ModulePrefs.
  • Объект view позволяет нам настроить способ отображения гаджета на странице. Он подробно описан в документации Atlassian по гаджетам.

2. Мы будем использовать встроенную поддержку фреймворка JavaScript для Ajax, чтобы получить нужные нам данные из ресурса. Код выглядит так:

(function () {
var gadget = AJS.Gadget({
baseUrl: "__ATLASSIAN_BASE_URL__",
useOauth: "/rest/gadget/1.0/currentUser",
view: {
var gadget = this;
},
key: "projectData",
ajaxOptions: function() {
return {
url: "/rest/tutorial-gadget/1.0/projects.json"
};
}
}]
}
});
})();

• Наиболее важным свойством объекта view является template, который является функцией, которая генерирует HTML-код гаджета. Как вы создаете HTML, зависит от вас, но наиболее распространенным подходом является использование API манипуляции jQuery.
• Сам объект гаджета доступен как this внутри template(), позволяющий использовать API-интерфейс объекта Gadget.
• template () принимает параметр args, который дает доступ к данным, доступным в массиве args view. (В ближайшее время мы будем использовать API манипуляции jQuery и объект гаджета в нашем гаджете.)
• Массив args используется для указания данных, которые должен использовать гаджет. Каждый член массива args является спецификацией для удаленного извлечения данных.
•  key объекта-члена - это имя, которое мы будем использовать для ссылки на элемент после его передачи в template ().
• ajaxOptions - это объект, чьими свойствами являются опции jQuery Ajax. В этом простом случае, когда мы делаем только запрос GET службе REST, свойство url - это все, что требуется.

3. Напишите код, который будет принимать возвращенные данные и отобразить их:

(function () {
var gadget = AJS.Gadget({
baseUrl: "__ATLASSIAN_BASE_URL__",
useOauth: "/rest/gadget/1.0/currentUser",
view: {
template: function(args) {
var gadget = this;

var projectList = AJS.$("<ul/>");

AJS.$(args.projectData.projects).each(function() {
projectList.append(
AJS.$("<li/>").append(
AJS.$("<a/>").attr({
target: "_parent",
title: gadgets.util.escapeString(this.key),
href: "__ATLASSIAN_BASE_URL__" + "/browse/" + this.key
}).text(this.name)
 )
 );
});

gadget.getView().html(projectList);
},
args: [{
key: "projectData",
ajaxOptions: function() {
return {
url: "/rest/tutorial-gadget/1.0/projects.json"
};
}
}]
}
});
})();

4. Сохраните изменения

 

Будьте осторожны с побочными эффектами!

Всякий раз, когда гаджет перезагружается или изменяется на странице, он будет повторно отображен и будет вызван template (). Убедитесь, что у этого нет побочных эффектов.

Шаг 7. Создание, установка и запуск приложения.

На этом этапе вы создадите и установите приложение, чтобы вы могли проверить свой код. Если вы еще не запустили приложение, запустите его сейчас:

1. В окне терминала перейдите в корневую папку приложения (где находится pom.xml).
2. Выполните следующую команду:

atlas-run

(Если вы хотите запустить отладчик в своей среде IDE, вам нужно запустить команду atlas-debug.)

 

3. Перейдите к созданному экземпляру Jira в своем браузере. Приложение гаджета было установлено в приложение, и вы можете проверить свои изменения.

4. Убедитесь, что у вас есть хотя бы один проект в Jira, который доступен для просмотра всем пользователям.

5. Если у вас еще нет созданной панели, выполните следующие действия, чтобы создать ее:
   1. В правом верхнем углу нажмите кнопку «Добавить гаджет».
   2. Найдите в списке гаджет «Тестирование гаджета учебника Jira». Это наш гаджет. Добавьте его в панель инструментов.
6. Вы должны увидеть список проектов, отображаемых всеми пользователями, отображаемыми в гаджете.

С этого момента вы можете использовать QuickReload для переустановки своего приложения за кулисами по мере работы.

 

похожие темы

• Разработка гаджетов

 

По материалам Atlassian JIRA  Server Developer Writing gadgets for Jira