Создание приложения для элемента панели управления

 

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

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

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

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

1. Дескриптор приложения, чтобы включить приложение в Jira.
2. Необходимые модули плагинов, которые определяют элемент панели инструментов.
3. Шаблоны Soy для рендеринга элемента панели инструментов
4. Поставщик контекста для передачи переменных в шаблон Soy.
5. JavaScript-модуль AMD для динамического загрузки контента.

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

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

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

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

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

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

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

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

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

git clone https://bitbucket.org/atlassian_tutorial/dashboard-item-tutorial.git

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

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

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

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

atlas-create-jira-plugin

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

5. Подтвердите свои записи при появлении запроса. SDK создает исходные файлы проекта приложения в каталоге с именем dashboard-item-tutorial.

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

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 находится в корне вашего проекта и объявляет зависимости проекта и другую информацию.

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

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

3. Чтобы добавить осмысленное описание для вашего приложения, обновите элемент description проекта. Например:

<description> Этот плагин добавляет ссылки компании в новое меню в заголовке JIRA. </ description>

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

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

Откройте файл atlassian-plugin.xml.

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

<?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="dashboard-item-tutorial"/>
    <web-resource key="dcd ashboard-item-tutorial-resources" name="dashboard-item-tutorial Web Resources">
        <dependency>com.atlassian.auiplugin:ajs</dependency>
        <resource type="download" name="dashboard-item-tutorial.css" location="/css/dashboard-item-tutorial.css"/>
        <resource type="download" name="dashboard-item-tutorial.js" location="/js/dashboard-item-tutorial.js"/>
        <resource type="download" name="images/" location="/images"/>
        <context>dashboard-item-tutorial</context>
    </web-resource> </atlassian-plugin> 

Шаг 3. Создайте элемент панели управления с отображением на стороне сервера.

На этом этапе вы создадите элемент панели инструментов, который будет использовать поставщик контекста для передачи значения шаблону Soy.

1. Определите новый элемент панели инструментов в файле дескриптора приложения (то есть atlassian-plugin.xml):

<dashboard-item key="new-dashboard-item"
        i18n-name-key="com.example.plugins.tutorial.dashboard.item.title">
    <definition>
        <title key="com.example.plugins.tutorial.dashboard.item.title"/>
        <categories>
            <category>Jira</category>
        </categories>
        <author>
            <name>Author's name</name>
        </author>
        <thumbnail location="/download/resources/${atlassian.plugin.key}:dashboard-item-tutorial-resources/images/pluginLogo.png"/>
    </definition>     
<description key="com.example.plugins.tutorial.dashboard.item.description"/>     
<resource name="view" type="soy" location=":dashboard-item-tutorial-resources/Dashboard.Item.Tutorial.Templates.Static"/>     
<context-provider class="com.example.plugins.tutorial.DashboardItemContextProvider"/>
</dashboard-item> 

• Элемент definition используется для отображения элемента панели управления в каталоге гаджета (то есть, когда пользователи ищут гаджеты).
• Вы можете ссылаться на pluginLogo.png как на эскиз(свёрнутое (в пиктограмму) изображение), потому что SDK включил его в ваш проект и объявил его в элементе web-resources.
• dashboard-item-tutorial-resources - это ключ модуля web-resources.

2. Чтобы использовать шаблон Soy для рендеринга элемента панели управления, обновите элемент веб-ресурсов со следующим:

<web-resource key="dashboard-item-tutorial-resources" name="dashboard-item-tutorial Web Resources">
    <dependency>com.atlassian.auiplugin:ajs</dependency>
    <transformation extension="soy">
        <transformer key="soyTransformer"/>
    </transformation>
    <resource type="download" name="dashboard-item-tutorial.css" location="/css/dashboard-item-tutorial.css"/>
    <resource type="download" name="dashboard-item-tutorial.js" location="/js/dashboard-item-tutorial.js"/>
    <resource type="download" name="images/" location="/images"/>
    <resource type="download" location="soy/dashboard-item.soy" name="soy/dashboard-item.soy.js"/>
    <resource type="soy" location="/soy/dashboard-item.soy" name="Dashboard.Item.Tutorial.Templates.Static"/>
    <context>atl.dashboard</context>
    <context>dashboard-item-tutorial</context>
</web-resource>

Обратите внимание, что мы объявили atl.dashboard, поэтому ресурсы будут включены на странице панели мониторинга.

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

Шаг 4. Создайте шаблон Soy

1. Перейдите в src / main / resources и создайте каталог soy.
2. Создайте файл dashboard-item.soy.
3. Добавьте следующий код в шаблон Soy:

{namespace Dashboard.Item.Tutorial.Templates}
 
    /**
    * @param pluginName
    * @param version
    */
    {template .Static}
     <div>Welcome to <span class="aui-lozenge aui-lozenge-success">{$pluginName}</span> v{$version}!</div>
    {/template}

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

Шаг 5. Добавьте поставщика контекста.

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

1. Перейдите в src / main / java / com / example / plugins / tutorial и создайте новый класс Java DashboardItemContextProvider.
2. Добавьте к нему следующий код:

package com.example.plugins.tutorial;
 
import com.atlassian.plugin.Plugin;
import com.atlassian.plugin.PluginAccessor;
import com.atlassian.plugin.PluginInformation;
import com.atlassian.plugin.PluginParseException;
import com.atlassian.plugin.spring.scanner.annotation.component.Scanned;
import com.atlassian.plugin.spring.scanner.annotation.imports.ComponentImport;
import com.atlassian.plugin.web.ContextProvider;
import com.google.common.collect.Maps;
import java.util.Map;   
@Scanned public class DashboardItemContextProvider implements ContextProvider {     
private final PluginAccessor pluginAccessor;       
public DashboardItemContextProvider(             @ComponentImport PluginAccessor pluginAccessor) 
{         this.pluginAccessor = pluginAccessor;     }       
@Override     public void init(final Map<String, String> params) throws PluginParseException {     }       
@Override     public Map<String, Object> getContextMap(final Map<String, Object> context) 
{
final Map<String, Object> newContext = Maps.newHashMap(context);         
Plugin plugin = pluginAccessor.getEnabledPlugin("com.example.plugins.tutorial.dashboard-item-tutorial");         
newContext.put("version", plugin.getPluginInformation().getVersion());         
newContext.put("pluginName", plugin.getName());         
return newContext;     
} 
} 

Мы использовали Atlassian Spring Scanner для инъекции PluginAccessor из хост-приложения.

3. Поскольку мы объявили ключи i18n в дескрипторе приложения, пришло время обновить элемент dashboard-item-tutorial.properties в файле atlassian-plugin.xml.

com.example.plugins.tutorial.dashboard.item.title=Dashboard tutorial com.example.plugins.tutorial.dashboard.item.description=Writing a dashboard item app tutorial

 Шаг 6. Проверьте свой элемент панели инструментов.

1. В окне терминала запустите следующую команду SDK:

atlas-run

Эта команда запускает экземпляр Jira и загружает ваше приложение. На выходе найдите строку, которая выглядит примерно так:

[INFO] jira started successfully in 134s at http://localhost:2990/jira

Он сообщает вам, что экземпляр Jira запущен и показывает URL-адрес домашней страницы Jira.

2. В браузере перейдите на домашнюю страницу Jira, указанную в выводе терминала.
3. Войдите в систему, используя комбинацию имени пользователя и пароля admin / admin.
4. Создайте новый проект в соответствии с запросом. Jira предлагает создать новый проект только при запуске нового экземпляра.
5. В правом верхнем углу страницы нажмите «Панель управления»> «Управление панелями мониторинга».

6. Создайте новую панель управления и нажмите кнопку «Добавить гаджет». Вот пример того, как должен выглядеть ваш гаджет.

РИСУНОК

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

РИСУНОК

Приложение работает, но пока это мало что делает. Вы улучшите его в следующих шагах.

Оставьте Jira сейчас в браузере.

Шаг 7. Загрузите контент динамически

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

API-интерфейс  элемента панели инструментов позволяет включить JavaScript с использованием модулей AMD.

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

 

1. Откройте файл atlassian-plugin.xml и добавьте следующее во внутрь dashboard-item:

<amd-module>dashboard-items/tutorial</amd-module>

2. Перейдите в src / main / resources / soy и откройте файл dashboard-item.soy.
3. Создайте элемент div для динамического содержимого и добавьте шаблоны - сначала для отображения задач, а второй - для обработки пустого списка.

{namespace Dashboard.Item.Tutorial.Templates}
 
    /**
    * @param pluginName
    * @param version
    */
    {template .Static}
     <div id="dynamic-content"/>
     <div>Welcome to <span class="aui-lozenge aui-lozenge-success">{$pluginName}</span> v{$version}!</div>
    {/template}
 
    /**
    * @param issues
    */
    {template .IssueList}
       <table class="aui">
           <thead>
               <tr>
                   <th id="basic-icon"></th>
                   <th id="basic-fname">Issue key</th>
                   <th id="basic-lname">Due date</th>
               </tr>
           </thead>
                  <tbody>
           {foreach $issue in $issues}
                        <tr>
                            <td headers="basic-number"><img src="{$issue.fields.issuetype.iconUrl}"/></td>
                            <td headers="basic-fname">{$issue.key}</td>
                            <td headers="basic-lname">{$issue.fields.duedate}</td>
                        </tr>
           {/foreach}            
                  </tbody>        
        </table>        
<div class="buttons-container">            
<div class="buttons">                
<input class="button submit" type="submit" value="Refresh">            
</div>        
</div>     
{/template}     
/**     *   Use this template if there is no issues in response     
**/     {template .Empty}        
No issues yet.        
<div class="buttons-container">               
<div class="buttons">                   \
<input class="button submit" type="submit" value="Refresh">               
</div>           
</div>     
{/template} 

4. Перейдите в src / main / resources / js / и откройте файл dashboard-item-tutorial.js.

5. Чтобы определить модуль AMD, добавьте следующий код JavaScript в файл:

 

define('dashboard-items/tutorial', ['underscore', 'jquery', 'wrm/context-path'], function (_, $, contextPath) 
{   var DashboardItem = function (API) 
{  
      this.API = API;
        this.issues = [];
    };
    /**
    * Called to render the view for a fully configured dashboard item.
    *
    * @param context The surrounding <div/> context that this items should render into.
    * @param preferences The user preferences saved for this dashboard item (e.g. filter id, number of results...)
    */
    DashboardItem.prototype.render = function (context, preferences) {
        this.API.showLoadingBar();
        var $element = this.$element = $(context).find("#dynamic-content");
        var self = this;
        this.requestData().done(function (data) {
            self.API.hideLoadingBar();
            self.issues = data.issues;
            if (self.issues === undefined || self.issues.length  === 0) {
                $element.empty().html(Dashboard.Item.Tutorial.Templates.Empty());
            }
            else {
                $element.empty().html(Dashboard.Item.Tutorial.Templates.IssueList({issues: self.issues}));
            }
            self.API.resize();
            $element.find(".submit").click(function (event) {
                event.preventDefault();
                self.render(element, preferences);
            });
        });
 
        this.API.once("afterRender", this.API.resize);
    };
 
    DashboardItem.prototype.requestData = function () {
        return $.ajax({
            method: "GET",
            url: contextPath() + "/rest/api/2/search?jql=due<=3d"
        });
    };
 
    return DashboardItem;
});

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

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

Шаг 8. Проверка динамической нагрузки

1. Чтобы протестировать обновления, перестройте приложение с помощью QuickReload:

atlas-package

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

              РИСУНОК

4. Создайте несколько задач со сроком действия менее чем за 3 дня и нажмите «Обновить».

РИСУНОК

Шаг 9. Добавьте экран конфигурации и протестируйте приложение.

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

1. Откройте файл atlassian-plugin.xml, найдите определение dashboard-item и добавьте атрибут configurable:

<dashboard-item key="new-dashboard-item"
            i18n-name-key="com.example.plugins.tutorial.dashboard.item.title"
            configurable="true">

2. Откройте файл dashboard-item.soy. Чтобы создать другой шаблон Soy для отображения формы конфигурации, добавьте следующее в файл:

/**
    * configuration
    */
    {template .Configuration}
       <form class="aui">
           <div class="field-group">
               <label for="due-date-input">Due Date
                   <span class="aui-icon icon-required">(required)</span></label>
               <input class="text medium-field" type="text"
                      id="due-date-input" name="due-date-input" value="3d">
               <div class="description">Syntax: 3(d|w|m) </div>
           </div>
           <div class="buttons-container">
               <div class="buttons">
                   <input class="button submit" type="submit" value="Save" id="comment-save-button">
                   <a class="cancel" href="#">Cancel</a>
               </div>
           </div>
       </form>
    {/template}

3. Откройте файл dashboard-item-tutorial.js. Поскольку мы добавили атрибут configurable, приборная панель вызывает метод renderEdit, если элемент панели мониторинга еще не настроен.

Добавьте в файл следующий метод renderEdit:

DashboardItem.prototype.renderEdit = function (context, preferences) {
        var $element = this.$element = $(context).find("#dynamic-content");
        $element.empty().html(Dashboard.Item.Tutorial.Templates.Configuration());
        this.API.once("afterRender", this.API.resize);
        var $form = $("form", $element);
        $(".cancel", $form).click(_.bind(function() {
            if(preferences['due-date-input'])
                this.API.closeEdit();
        }, this));
 
        $form.submit(_.bind(function(event) {
            event.preventDefault();
 
            var preferences = getPreferencesFromForm($form);
            var regexp = /^\d+([dwm])$/;
            if(regexp.test(preferences['due-date-input'])) {
                this.API.savePreferences(preferences);
                this.API.showLoadingBar();
            }
        }, this));
    };
 
    function getPreferencesFromForm($form) {
        var preferencesArray = $form.serializeArray();
        var preferencesObject = {};
 
        preferencesArray.forEach(function(element) {
            preferencesObject[element.name] = element.value;
        });
 
        return preferencesObject;
    }

4. Обновите методы рендеринга и requestData для работы с настройками:

DashboardItem.prototype.render = function (context, preferences) {
     this.API.showLoadingBar();
     var $element = this.$element = $(context).find("#dynamic-content");
     var self = this;
     this.requestData(preferences).done(function (data) {
         self.API.hideLoadingBar();
         self.issues = data.issues;
         if (self.issues === undefined || self.issues.length  === 0) {
             $element.empty().html(Dashboard.Item.Tutorial.Templates.Empty());
         }
         else {
             $element.empty().html(Dashboard.Item.Tutorial.Templates.IssueList({issues: self.issues}));
         }
         self.API.resize();
         $element.find(".submit").click(function (event) {
             event.preventDefault();
             self.render(context, preferences);
         });
     });
 
     this.API.once("afterRender", this.API.resize);
 };
 
DashboardItem.prototype.requestData = function (preferences) {
    return $.ajax({
        method: "GET",
        url: contextPath() + "/rest/api/2/search?maxResults=10&jql=due<=" + preferences['due-date-input']
    });
};

5. Сохраните изменения.
6. Перестройте свое приложение и проверьте изменения, ваш экран конфигурации должен выглядеть так:

РИСУНОК

Поздравляю, вот и все!

Имейте удовольствие!

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

Ваш JAR-файл приложения находится в файле target \ dashboard-item-tutorial-1.0-SNAPSHOT.jar.

Вы можете установить приложение, используя Universal Plugin Manager.

 Похожие темы

• Документация AUI
• Модуль элементов панели инструментов
• Создание элемента панели инструментов

По материалам Atlassian JIRA  Server Developer Writing a dashboard item app