Создание пользовательского типа поля

Уровень опыта	Начинающий
Временная оценка	Для завершения этого урока вам потребуется около 30 минут.
Применимость	Это руководство применяется к Jira 7.1.0 и выше.

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

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

Чтобы отобразить ваше поле и контролировать, кто может редактировать или просматривать его, вы будете использовать шаблон Velocity. Это формат, объединяющий Java и HTML. Чтобы связать ваш Java-класс и шаблон вместе, вы определите их как в одном модуле плагина customfield-type в файле дескриптора atlassian-plugin.xml.

В этом учебном пособии рассматриваются следующие темы:

Обзор пользовательских полей и файлов, входящих в состав приложения.
Расширение пользовательского типа поля класса GenericTextCFType для вашего приложения.
Использование типа модуля плагина customfield-type для Jira.

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

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

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

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

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

Понимать основы разработки Java: классы, интерфейсы, методы, использование компилятора и т. д.
Знать основы использования и администрирования Jira.

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

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

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

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


git clone https://bitbucket.org/atlassian_tutorial/jira-custom-field-tutorial.git

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

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

На этом этапе вы создадите скелет приложения Jira. Вы будете использовать atlas-команды для автоматизации создания приложения. Вам не понадобятся файлы, которые автоматически генерируются SDK, поэтому вы удалите их на этом этапе.

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


atlas-create-jira-plugin

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

group-id	com.example.plugins.tutorial.customfields
artifact-id	jira-custom-field-example
version	1.0-SNAPSHOT
package	com.example.plugins.tutorial.customfields

При появлении запроса подтвердите свои записи с помощью Y или y.
Перейдите в каталог jira-custom-field-example, созданный на предыдущем шаге.


cd jira-custom-field-example

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


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

Удалите ненужные файлы Java.


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

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

Импортируйте проект в свою любимую среду IDE.

Шаг 2. Создайте свой класс JiraCustomField.

Ваше пользовательское поле расширяет класс Jira GenericTextCFType.

GenericTextCFType является одним из многих пользовательских Java-классов и интерфейсов. Другие примеры включают:

DateCFType для установки дат.
UserCFTPE для выбора пользователей.
SelectCFType, чтобы выбрать одну опцию из списка.

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

Создайте новый класс JiraCustomField, который расширяет GenericTextCFType с помощью следующего кода-заглушки:


package com.example.plugins.tutorial.customfields;
 
import com.atlassian.jira.issue.customfields.impl.GenericTextCFType;
import com.atlassian.jira.issue.customfields.manager.GenericConfigManager;
import com.atlassian.jira.issue.customfields.persistence.CustomFieldValuePersister;
import com.atlassian.jira.issue.fields.TextFieldCharacterLengthValidator;
import com.atlassian.jira.security.JiraAuthenticationContext;
import com.atlassian.plugin.spring.scanner.annotation.component.Scanned;
import com.atlassian.plugin.spring.scanner.annotation.imports.JiraImport;
 
@Scanned
public class JiraCustomField extends GenericTextCFType {
 
    public JiraCustomField(
            @JiraImport CustomFieldValuePersister customFieldValuePersister,
            @JiraImport GenericConfigManager genericConfigManager,
            @JiraImport TextFieldCharacterLengthValidator textFieldCharacterLengthValidator,
            @JiraImport JiraAuthenticationContext jiraAuthenticationContext) {
        super(customFieldValuePersister, genericConfigManager, textFieldCharacterLengthValidator , jiraAuthenticationContext);
    }
}

@JiraImport и @Scanned - аннотации Atlassian Spring Scanner.

Шаг 3. Создайте шаблон Velocity для форматирования вашего пользовательского поля.

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

Вы создадите условие, чтобы проверить, включает ли имя группы пользователей 'jira-administrators'. Если пользователи соответствуют критериям, они смогут редактировать значение поля. Все остальные пользователи смогут увидеть введенное значение, но они не смогут его изменить.

Вы также создадите условие else, которое, если значение не было задано для поля, Jira будет отображать «N / A» в качестве значения по умолчанию.

В разделе src / main / resources создайте каталог шаблонов.


mkdir src/main/resources/templates

В вашем новом каталоге шаблонов создайте файл edit.vm со следующим кодом:


#controlHeader ($action $customField.id $customField.name $fieldLayoutItem.required $displayParameters.noHeader)
   #if ($jiraUserUtils.getGroupNamesForUser($authcontext.loggedInUser.name).contains('jira-administrators'))
   <input type="text"
          name="$customField.id"
          value="$!value" />
   #else
       #if($value && ! $value.equals(""))
           #set ($displayValue = ${value})
       #else
           #set ($displayValue = 'N/A')
       #end
   <span title="This field is editable only by JIRA administrators">$!displayValue</span>
   <input type="hidden"
          name="$customField.id"
          value="$!value" />
   #end
   #controlFooter ($action $fieldLayoutItem.fieldDescription $displayParameters.noHeader)

Здесь мы добавляем условную проверку, чтобы узнать, является ли пользователь администратором. Если значения не существует, пользователь увидит «N / A».

Шаг 4. Добавьте в файл customfield-type модуль плагина

На этом этапе вы завершите свой код приложения с добавлением customfield-type модуля плагина. Вы добавите этот модуль в файл дескриптора atlassian-plugin.xml. Файл дескриптора автоматически генерируется при создании скелета приложения. Он описывает модули и ресурсы, предоставляемые вашим плагином, в систему Atlassian.

Вставка customfield-type модуля плагина позволяет добавить пользовательское поле в Jira. Для этого модуля требуется Java-класс для реализации и уникальный идентификатор ключа.

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

Тип просмотра	Детали
view	Предоставляет базовое представление только для чтения значения поля.
column-view	Просмотр только для отображения в навигаторе задач. Навигатор задач отобразит значение представления, если оно опущено.
edit	Отображает виджет редактирования в создании задач, редактировании задач и редактировании значений по умолчанию. Это значение, которое вы замените своим настраиваемым шаблоном Velocity.
xml	Показывает значение в формате XML для экспорта RSS или XML.

* типы просмотра, редактирования и просмотра xml требуются.

Вы будете использовать два встроенных шаблона Velocity в Jira для типов представлений вида и xml и свой пользовательский шаблон для значения редактирования.

Перейдите в src / main / resources и откройте файл atlassian-plugin.xml. Перед закрывающим тегом </ atlassian-plugin> добавьте следующий блок:


<customfield-type name="Jira Custom Field" i18n-name-key="jira-custom-field.name" key="admintextfield" class="com.example.plugins.tutorial.customfields.JiraCustomField">
</customfield-type>

Вы дадите своему пользовательскому полю уникальный ключ, имя и определите JiraCustomField как реализующий Java-класс.

Внутри первого тега customfield-type добавьте следующее описание.


<description> Текстовое поле, доступное только для тех, у кого есть разрешения администратора </ description>

Это описание появляется в Jira, когда вы применяете пользовательский тип поля из страниц администратора.

Вы также можете указать категорию для своего настраиваемого типа поля. Доступные значения: STANDART и ADVANCED, по умолчанию ADVANCED.

Определите, какие шаблоны Velocity будут использоваться для каждого типа вида:


<resource type="velocity" name="view" location="templates/plugins/fields/view/view-basictext.vm"/>
    <resource type="velocity" name="edit" location="templates/edit.vm"/>
    <resource type="velocity" name="xml" location="templates/plugins/fields/xml/xml-basictext.vm"/>

Сохраните и закройте файл дескриптора.

Вот полный файл дескриптора atlassian-plugin.xml.


<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>
    <!-- add our i18n resource -->
    <resource type="i18n" name="i18n" location="jira-custom-field-example"/>
    <!-- add our web resources -->
    <web-resource key="jira-custom-field-example-resources" name="jira-custom-field-example Web Resources">
        <dependency>com.atlassian.auiplugin:ajs</dependency>
        <resource type="download" name="jira-custom-field-example.css" location="/css/jira-custom-field-example.css"/>
        <resource type="download" name="jira-custom-field-example.js" location="/js/jira-custom-field-example.js"/>
        <resource type="download" name="images/" location="/images"/>
        <context>jira-custom-field-example</context>
    </web-resource>
    <customfield-type name="Jira Custom Field" i18n-name-key="jira-custom-field.name" key="admintextfield" class="com.example.plugins.tutorial.customfields.JiraCustomField">
        <description>A text field only editable by those with admin permissions</description>
        <resource name="view" type="velocity" location="templates/plugins/fields/view/view-basictext.vm"/>
        <resource name="edit" type="velocity" location="/templates/edit.vm"/>
        <resource name="xml" type="velocity" location="templates/plugins/fields/xml/xml-basictext.vm"/>
    </customfield-type>
</atlassian-plugin>

Чтобы поддержать интернационализацию, добавьте следующую строку в jira-custom-field-example.properties:

jira-custom-field.name=Admin Editable Text Field

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

На этом этапе вы установите приложение и запустите Jira. Вы войдете в свой экземпляр Jira в качестве администратора и настройте видимость для своего пользовательского поля.

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


atlas-run

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

Найдите URL для Jira.

Ваш терминал выводит местоположение вашего локального экземпляра Jira, по умолчанию - localhost: 2990 / jira.


[INFO] jira успешно стартовала в 1942 году по адресу http: // localhost: 2990 / jira
[INFO] Наберите Ctrl-D для корректного завершения
[INFO] Наберите Ctrl-C для выхода

Откройте экземпляр Jira в окне браузера.Мы рекомендуем использовать Google Chrome или Mozilla Firefox для обеспечения согласованности.
Войдите в систему с учетными данными администратора / администратора.
Перейдите в значок cog> Задачи> Пользовательские поля.
Нажмите «Добавить пользовательское поле», а затем «Дополнительно».
Выберите «Админ редактируемого текстового поля» в списке и нажмите «Далее».

РИСУНОК

Свяжите поле со всеми экранами и нажмите «Далее».

РИСУНОК

Шаг 6. Создайте тестового пользователя и протестируйте свой пользовательский тип поля

Теперь, когда вы добавили свое пользовательское поле, давайте проверим его. Чтобы проверить ваши настройки поля, вы создадите нового пользователя без прав администратора.

На любой странице вашего локального экземпляра Jira нажмите «Управление пользователями».
Нажмите «Создать пользователя» и введите данные для тестового пользователя.

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

РИСУНОК

Нажмите «Проекты»> «Создать проект».

Теперь вы сможете создать задачу для тестирования своего поля.

Выберите любой шаблон и нажмите «Далее».
Введите имя (например, «Тест») и нажмите «Отправить».
Нажмите «Создать задачу» и убедитесь, что вы можете вводить текст в свой пользовательский тип поля в качестве администратора.

РИСУНОК

Выйдите из системы и войдите в систему с учетными данными вашего тестового пользователя.
Создайте задачу в качестве тестового пользователя.

Убедитесь, что вы не можете изменить настроенное вами поле.

РИСУНОК

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

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

Создание пользовательского поля в Jira.
Пользовательское поле.

По материалам Atlassian JIRA Server Developer Creating a custom field type