Добавление содержимого на страницу «Просмотр задач Jira»

 

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

В этом учебном пособии показано, как добавить контент на страницу «Просмотр задачи» в Jira. В нем показано, как создать приложение, которое добавляет веб-панель на страницу, если задача имеет установленную дату. На веб-панели отображается яркая индикация того, когда возникла задача (или просроченная).

Завершенное приложение состоит из следующих компонентов:

1. Дескриптор приложения (XML-файл), который описывает модуль плагина для Jira.
2. Класс Java DueDateIndicator, который вычисляет дату выполнения задачи и предоставляет ее как объектный контекст, который мы можем использовать в шаблонах Jira UI.
3. Ресурсы для отображения пользовательского интерфейса приложения. Это включает в себя свойства интернационализации tutorial-jira-add-content-to-view-issue-screen.properties и шаблон Velocity (т. е. файл due-date-indicator.vm) для рендеринга модуля плагина веб-панели.

Когда вы закончите, все эти компоненты будут упакованы в один JAR-файл.

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

Вы можете использовать любую поддерживаемую комбинацию операционной системы и IDE для создания этого приложения. Эти инструкции были написаны с использованием IntelliJ IDEA 2017.2 на macOS Sierra. Если вы используете другую операционную систему или комбинацию IDE, вы должны использовать эквивалентные операции для своей конкретной среды. Этот учебник был последний раз проверен с помощью Jira 7.7.1 с использованием Atlassian SDK 6.3.10.

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

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

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

Источник приложения

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

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

git clone https://bitbucket.org/atlassian_tutorial/jira-add-content-to-view-issue-screen

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

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

На этом этапе вы будете использовать две команды atlas для создания кода-заглушки для вашего приложения. atlas-команды являются частью Atlasian Plugin SDK и автоматизируют большую часть разработки приложений для вас.

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

atlas-create-jira-plugin

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

 

5. Подтвердите свои записи при появлении запроса.
6. Перейдите в каталог tutorial-jira-add-content-to-view-issue-screen, созданный на предыдущем шаге.
7. Удалите тестовые каталоги.

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

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

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

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

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

Рекомендуется ознакомиться с файлом конфигурации проекта, известным как POM (то есть, файл определения объектной модели проекта). В этом разделе вы просмотрите и настроите файл pom.xml.

Добавить метаданные приложения к POM

POM находится в корне вашего проекта и объявляет зависимости проекта и другую информацию.

1. В корневой папке приложения откройте файл pom.xml.
2. В элементе organization добавьте название своей компании или организации и URL вашего сайта. Следующий блок кода показывает, как оно выглядит в виде обычного текста:

<organization>
    <name>Example Company</name>
    <url>http://www.example.com/</url>
</organization>

3. Обновите элемент description следующим образом:

<description> Этот плагин отображает дату выпуска проблемы на новой панели на странице «Просмотр проблемы». </ description>

4. Измените элемент name, чтобыон был чем-то более читаемым (необязательно):

<name> Индикатор срока действия на странице «Просмотр задачи» </ name>

Это имя для вашего приложения, которое появится на странице администрирования приложения Jira.

 

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

Просмотрите созданный дескриптор приложения

Ваш код заглушки содержит файл дескриптора приложения atlassian-plugin.xml. Это XML-файл, который идентифицирует приложение для хост-приложения (Jira) и определяет требуемые функциональные возможности приложения.

1. В своей среде IDE перейдите к src / main / resources и откройте файл дескриптора.

Вы должны увидеть что-то вроде этого (комментарии удалены):

<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
        <param name="plugin-icon">images/pluginIcon.png</param>
        <param name="plugin-logo">images/pluginLogo.png</param>
    </plugin-info>
    <resource type="i18n" name="i18n" location="tutorial-jira-add-content-to-view-issue-screen"/>
    <web-resource key="tutorial-jira-add-content-to-view-issue-screen-resources" name="tutorial-jira-add-content-to-view-issue-screen Web Resources">
        <dependency>com.atlassian.auiplugin:ajs</dependency>
        <resource type="download" name="tutorial-jira-add-content-to-view-issue-screen.css" location="/css/tutorial-jira-add-content-to-view-issue-screen.css"/>
        <resource type="download" name="tutorial-jira-add-content-to-view-issue-screen.js" location="/js/tutorial-jira-add-content-to-view-issue-screen.js"/>
        <resource type="download" name="images/" location="/images"/>
        <context>tutorial-jira-add-content-to-view-issue-screen</context>
    </web-resource>
</atlassian-plugin>

Обратите внимание, что часть информации из POM передается в дескриптор приложения с использованием имен переменных, таких как $ {project.name}.

Шаг 3. Добавьте модули плагина

Теперь вы будете использовать генератор модуля плагина (т. е. другую команду atlas) для создания кода-заглушки для модулей, которые необходимы для приложения.

Для этого шага вам понадобится модуль плагина веб-панели. Вы добавите его, используя команду atlas-create-jira-plugin-module. Команда также может генерировать файл свойств i18n для вашего текста пользовательского интерфейса Jira, который мы также добавим.

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

atlas-create-jira-plugin-module

2. Выберите опцию «Веб-панель», а затем добавьте следующую информацию.

Для получения дополнительной информации см. правую часть местоположения страницы« Просмотр задачи».

3. Выберите «y» для подсказки «Показать расширенную настройку».
4. Для следующих пяти опций вы можете принять значение по умолчанию, выбрав enter. Для справки, значения следующие.

5. Выберите «y» для добавления приглашения «Дабавить Ресурс», а затем введите следующую информацию для ресурса.

6. Выберите «N» для добавления подсказки «Добавить параметр ресурса».
7. Выберите «N» для «Добавить ресурс».
8. Выберите «y» для поставщика контекста «Добавить Velocity».
9. Для добавления полного квалификационного контекста поставщика класса введите следующее: com.example.plugins.tutorial.DueDateIndicator.
10. Выберите «N» для «Добавить условия».
11. Выберите «N» для добавления дополнительного модуля плагина.

SDK завершает создание модуля плагинов и возвращает вас в командную строку.

Шаг 4. Добавьте заголовок панели

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

1. Перейдите в src / main / resources и откройте файл atlassian-plugin.xml.
2. Добавьте следующий элемент label в качестве дочернего элемента web-panel:

<web-panel name="DueDateIndicator" ...>
    ...
        <label key="due-date-indicator.title"/>
</web-panel>

                    
<?xml version="1.0" encoding="UTF-8"?>
<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2">
  <plugin-info>
    <description>${project.description}</description>
    <version>${project.version}</version>
    <vendor name="${project.organization.name}" url="${project.organization.url}"/>
    <param name="plugin-icon">images/pluginIcon.png</param>
    <param name="plugin-logo">images/pluginLogo.png</param>
  </plugin-info>
  <resource type="i18n" name="i18n" location="tutorial-jira-add-content-to-view-issue-screen"/>
  <web-resource key="tutorial-jira-add-content-to-view-issue-screen-resources" name="tutorial-jira-add-content-to-view-issue-screen Web Resources">
    <dependency>com.atlassian.auiplugin:ajs</dependency>
    <resource type="download" name="tutorial-jira-add-content-to-view-issue-screen.css" location="/css/tutorial-jira-add-content-to-view-issue-screen.css"/>
    <resource type="download" name="tutorial-jira-add-content-to-view-issue-screen.js" location="/js/tutorial-jira-add-content-to-view-issue-screen.js"/>
    <resource type="download" name="images/" location="/images"/>
    <context>tutorial-jira-add-content-to-view-issue-screen</context>
  </web-resource>
 
  <web-panel name="DueDateIndicator" i18n-name-key="due-date-indicator.name" key="due-date-indicator" location="atl.jira.view.issue.right.context" weight="1000">
    <description key="due-date-indicator.description">The DueDateIndicator Plugin</description>
    <context-provider class="com.example.plugins.tutorial.DueDateIndicator"/>
    <resource name="view" type="velocity" location="templates/due-date-indicator.vm"/>
    <label key="due-date-indicator.title"/>
  </web-panel>
</atlassian-plugin>

3. Сохраните и закройте файл.
4. В том же каталоге откройте файл свойств i18n, называемый tutorial-jira-add-content-to-view-issue-screen.properties.
5. Чтобы указать значение ключа due-date-indicator.title, который вы только что определили в своем дескрипторе приложения, добавьте следующее свойство due-date-indicator.title:

due-date-indicator.title=Due Date Indicator

На странице Просмотр задачи Jira  это значение будет отображаться как название вашей новой веб-панели. Ваш файл свойств i18n должен выглядеть следующим образом:

#put any key/value pairs here
my.plugin.name=MyPlugin
due-date-indicator.name=DueDateIndicator
due-date-indicator.description=The DueDateIndicator Plugin
due-date-indicator.title=Due Date Indicator     

6. Сохраните и закройте файл.

Шаг 5. Напишите свой Java-класс

Пока вы создали фреймворк для своего модуля плагина веб-панели. Теперь мы напишем некоторый Java-код, который делает веб-панель интересной. А именно:

1. Получаемую дату, связанную с текущей задачей.
2. Вычислим разницу между текущими данными и установленной датой.

Мы начнем с небольшого рефакторинга кода, который нам дал SDK.

 

1. Перейдите в каталог src / main / java / com / example / plugins / tutorial, создайте и откройте новый файл DueDateIndicator.java.

package com.example.plugins.tutorial;
import com.atlassian.jira.issue.Issue;
import com.atlassian.jira.plugin.webfragment.contextproviders.AbstractJiraContextProvider;
import com.atlassian.jira.plugin.webfragment.model.JiraHelper;
import com.atlassian.jira.user.ApplicationUser;
 
import java.sql.Timestamp;
import java.time.LocalDate;
import java.util.HashMap;
import java.util.Map;
 
import static java.time.temporal.ChronoUnit.DAYS;
 
public class DueDateIndicator extends AbstractJiraContextProvider {
 
    @Override
    public Map<String, Object> getContextMap(ApplicationUser applicationUser, JiraHelper jiraHelper) {
        return null;
    }
}

Обратите внимание, что теперь он расширяет абстрактный класс AbstractJiraContextProvider и реализует метод getContextMap класса.

 

2. Метод getContextMap, который мы реализовали, должен вернуть объект Map с ключом и значением, которое представляет количество дней между установленной датой и текущей датой, чтобы оно могло использоваться другими частями модуля.

Для этого инициализируйте новый объект HashMap Map в методе contextMap, чтобы сохранить этот ключ и значение.

Map<String, Object> contextMap = new HashMap<>();

3. В методе getContextMap инициализируйте новый объект Issue Jira currentIssue.  Он сохранит текущую проблему Jira как объект, через который вы можете получить доступ к его дате в виде Timestamp Java, используя метод getDueDate ().

Issue currentIssue = (Issue) jiraHelper.getContextParams().get("issue");
Timestamp dueDate = currentIssue.getDueDate();

4. Проверьте, установлена ли дата выполнения текущей задачи, и если да, начните вычислять количество дней между текущей датой и датой выполнения.

Мы используем Java Date / Time API для расчета дней между датой выполнения и текущей датой.

if (dueDate != null) {
    LocalDate currentTimeInDays = LocalDate.now();
    LocalDate dueDateTimeInDays = dueDate.toLocalDateTime().toLocalDate();
}

5. Теперь, когда у нас есть количество дней как для времени даты выполнения (dueDateTimeInDays), так и для текущего времени (currentTimeInDays), нам нужно рассчитать разницу между этими значениями.

Свяжите значение daysAwayFromDueDateCalc с ключевым словом daysAwayFromDueDate, используя объект Map (то есть, contextMap). В инструкции if, упомянутой на предыдущем шаге, добавьте следующие строки кода:

long daysAwayFromDueDateCalc = DAYS.between(currentTimeInDays, dueDateTimeInDays);
contextMap.put("daysAwayFromDueDate", daysAwayFromDueDateCalc);

6. Класс DueDateIndicator должен вернуть объект contextMap Map обратно в модуль плагина веб-панели, чтобы сделать его доступным для других ресурсов вашего приложения (то есть ресурса Template Velocity, который вы определите на следующем шаге). Чтобы вернуть объект, добавьте следующую строку:

return contextMap;

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

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

package com.example.plugins.tutorial;
 
import com.atlassian.jira.issue.Issue;
import com.atlassian.jira.plugin.webfragment.contextproviders.AbstractJiraContextProvider;
import com.atlassian.jira.plugin.webfragment.model.JiraHelper;
import com.atlassian.jira.user.ApplicationUser;
 
import java.sql.Timestamp;
import java.time.LocalDate;
import java.util.HashMap;
import java.util.Map;
 
import static java.time.temporal.ChronoUnit.DAYS;
 
public class DueDateIndicator extends AbstractJiraContextProvider {
 
    @Override
    public Map<String, Object> getContextMap(ApplicationUser applicationUser, JiraHelper jiraHelper) {
        Map<String, Object> contextMap = new HashMap<>();
        Issue currentIssue = (Issue) jiraHelper.getContextParams().get("issue");
        Timestamp dueDate = currentIssue.getDueDate();
        if (dueDate != null) {
            LocalDate currentTimeInDays = LocalDate.now();
            LocalDate dueDateTimeInDays = dueDate.toLocalDateTime().toLocalDate();
            long daysAwayFromDueDateCalc = DAYS.between(currentTimeInDays, dueDateTimeInDays);
            contextMap.put("daysAwayFromDueDate", daysAwayFromDueDateCalc);
        }
        return contextMap;
    }
}

Шаг 6. Напишите свой шаблон  Velocity

До сих пор вы написали Java-класс, который извлекает разницу в днях между текущей датой выполнения и текущей датой. Теперь вы напишете шаблон Velocity, чтобы представить эту информацию в формате HTML.

Модуль плагина веб-панели уже содержит следующий поставщик контекста:

<context-provider class="com.example.plugins.tutorial.DueDateIndicator"/>

Это ваш Java-класс DueDateIndicator. Как уже закодирован, этот класс возвращает объект Map с свойством daysAwayFromDueDate, значением которого является количество дней между датой истечения текущей даты и установленной датой.

Свойство daysAwayFromDueDate доступно для других ресурсов в модуле плагинов, таких как ресурс шаблона Velocity, который вы уже определили в дескрипторе приложения, используя due-date-indicator.vm SDK. Однако, пока мы объявили его в дескрипторе, нам все равно нужно добавить файл.

1. Перейдите в src / main / resources, создайте новый каталог templates и создайте там новый файл due-date-indicator.vm.
2. Добавьте следующий оператор if / then / else:

#set ($overdueDays = $daysAwayFromDueDate * -1)
#if ($daysAwayFromDueDate)
   #if ($daysAwayFromDueDate > 1)
       <span style="font-weight: bold; color: green;">This issue is due in $daysAwayFromDueDate days.</span>
   #elseif ($daysAwayFromDueDate == 1)
       <span style="font-weight: bold; color: blue;">This is issue is due tomorrow.</span>
   #elseif ($daysAwayFromDueDate == 0)
       <span style="font-weight: bold; color: purple;">This issue is due today.</span>
   #elseif ($daysAwayFromDueDate == -1)
       <span style="font-weight: bold; color: #ff4500;">This issue was due yesterday!</span>
   #elseif ($daysAwayFromDueDate < -1)
       <span style="font-weight: bold; color: red;">This issue is overdue by $overdueDays days!</span>
   #end
#end

Это заявление представляет собой красочный визуальный индикатор того, когда возникает текущая задача.

Обратите внимание, что мы определили новую переменную с именем $overdueDays. Поскольку свойство daysAwayFromDueDate, возвращаемое нашим Java-классом, содержит отрицательное значение всякий раз, когда задача просрочена (это то, на чем опирается наша серия операторов if / then / else), мы создали эту новую переменную, чтобы представить значение dayAwayFromDueDate как положительное номер. Также обратите внимание, что это темно-красный оранжевый цвет.

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

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

Теперь вы готовы проверить свое приложение.

1. В новом окне терминала перейдите в корневой каталог проекта.
2. Запустите следующую команду Atlasian Plugin SDK:

atlas-run

Это создает код приложения, запускает экземпляр Jira и устанавливает ваше приложение. Это может занять несколько минут.

3. Перейдите в localhost: 2990 / jira в своем браузере.
4. Войдите в систему, используя admin / admin по умолчанию.
5. Если вы используете недавнюю версию Jira, вы увидите мастер для создания нового проекта Jira. Выполните шаги для его создания.
6. Создайте новую задачу, добавьте к ней дату выполнения и сохраните ее.

7. Идите к своей новой задаче, и вуаля! Вы увидите веб-панель индикатора вашей даты выполнения.

РИСУНОК

Поздравляю, вот и все!Имейте удовольствие!

Следующие шаги

Чтобы узнать больше о задачах Jira, перейдите на следующие страницы:

• Добавление пунктов меню в Jira.
• Создание сервлета CRUD задач Jira и  поиска задач.
• Выполнение операций задач.

По материалам Atlassian JIRA  Server Developer Adding content to the Jira View Issue page