Разработка для проектно-ориентированного представления в JIRA

На этой странице вы найдете рекомендации по разработке для добавления вашей надстройки к новому проектно-ориентированному представлению в JIRA.

Прочитайте руководство по дизайну - проектно-ориентированному представлению JIRA, прежде чем читать эту страницу. Руководство по проектированию поможет вам обеспечить лучший пользовательский опыт для вашей надстройки в проектно-ориентированном представлении.

Обзор

Проект-ориентированное представление будет представлено в JIRA 6.4, но может быть отключено администратором как на уровне пользователя, так и на глобальном уровне.

Для облака JIRA Cloud и сервера JIRA Server отдельные пользователи смогут включать и выключать его. Администраторы также смогут переопределить эту настройку (например, включить / отключить для всех пользователей). Это означает, что из JIRA 6.4 ваша надстройка должна обслуживать экземпляры, в которых разрешено проектное-ориентированное представление, а также случаи, когда она отключена.

В проектно-ориентированном представлении представлены следующие компоненты:

Заголовок боковой панели
Раздел содержимого боковой панели, включая навигацию по проекту, ссылки на проект и избранные фильтры для пользователя
Ссылка администрирования боковой панели (если текущий зарегистрированный пользователь является администратором проекта)
Область содержимого страницы

Скриншот: Пример JIRA-ориентированного на проект предоставления

РИСУНОК

Методические рекомендации

Большинство надстроек просто нужно будет добавить ссылки на свой контент, связанный с проектом, на боковую панель. Если вы хотите это сделать, прочитайте раздел «Основные реализации» ниже.

Если вам нужна более индивидуальная реализация, например. вы хотите, чтобы связанная боковая панель ваших дополнительных надстроек открыла конкретную доску в проекте, прочтите раздел «Расширенная реализация» ниже.

Основная реализация

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

Шаг 1. Добавьте ссылку на боковую панель в виде веб-элемента

Добавьте свою ссылку в качестве веб-элемента в веб-раздел jira.project.sidebar.plugins.navigation.
Следующие параметры контекста доступны для вашего веб-элемента. Укажите необходимые параметры.

Параметр	Описание
project	Текущий объект проекта
projectKey	Текущий ключ проекта
pathEncodedProjectKey	Ключ проекта с кодировкой URL-адреса
queryEncodedProjectKey	Зашифрованный ключ проекта с параметром URL-запроса
Параметры фильтра подключаемого диапазона	См. Раздел «Фильтры области» ниже

Для получения дополнительной информации см. ProjectContextPopulator в плагине jira-projects.

Например, здесь приведено определение веб-элемента для ссылки «Релизы», показанное в *Пример JIRA, проектно-ориентированного представления*, на скриншоте выше:


<web-item key="release-page" i18n-name-key="version.release" section="jira.project.sidebar.plugins.navigation" weight="300">
    <label key="project.page.release.title"/>
    <link>/projects/$pathEncodedProjectKey?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page</link>
    <param name="iconClass" value="aui-icon-large icon-sidebar-release"/>
    <condition class="com.atlassian.jira.projects.page.release.VersionsDefinedAndVisibleCondition"/>
</web-item>

Шаг 2. Предоставление контента

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

Например, вот определения веб-элементов и веб-панелей для ссылки «Релизы», показанные в приведенном выше скриншоте *«Пример JIRA, проектно-ориентированного представления».*


<web-item key="release-page" i18n-name-key="version.release" section="jira.project.sidebar.plugins.navigation" weight="300">
    <label key="project.page.release.title"/>
    <link>/projects/$pathEncodedProjectKey?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page</link>
    <param name="iconClass" value="aui-icon-large icon-sidebar-release"/>
    <condition class="com.atlassian.jira.projects.page.release.VersionsDefinedAndVisibleCondition"/>
</web-item>
 
<web-panel key="release-page-key" location="com.atlassian.jira.jira-projects-plugin:release-page">
    <resource name="view" type="soy" location=":project-subpages-soy/JIRA.Projects.Release.Templates.page"/>
    <context-provider class="com.atlassian.jira.projects.page.release.ReleasePageContextProvider"/>
    <condition class="com.atlassian.jira.projects.page.release.VersionsDefinedAndVisibleCondition"/>
</web-panel>

Обратите внимание, как свойство ссылки в веб-элементе release-page ссылается на свойство местоположения location на веб-панели с release-page-key ключом страницы релиза. ProjectPageServlet позаботится о подключении selectedItem с расположением веб-панели и отображением панели при запросе URL-адреса веб-элемента. Дополнительные веб-ресурсы (JS, CSS) также могут быть включены на страницу, добавив их в jira.project.sidebar <context />.

Этот механизм одинаковый для надстроек atlassian-connect. Например, следующий дескриптор соединения atlassian будет отображать ссылку на боковую панель и содержимое при ее выборе.


{
     "name": "Hello World",
     "description": "Atlassian Connect add-on",
     "key": "com.example.myaddon",
     "baseUrl": "http://localhost:8000",
     "vendor": {
         "name": "Example, Inc.",
         "url": "http://example.com"
     },
     "authentication": {
         "type": "none"
     },
     "apiVersion": 1,
     "modules": {         
        "webItems": [
            {
                "location": "jira.project.sidebar.plugins.navigation",
                "key": "connect-provided-link-to-panel",
                "url": "/projects/{project.key}?selectedItem=com.example.myaddon__connect-provided-link-to-panel",
                "context": "product",
                "name": {
                    "value": "My Web Item"
                }
            }
        ],
        "webPanels" : [
            {
                "key": "connect-provided-web-panel",
                "url": "/helloworld.html?pkey={project.key}",
                "location": "com.example.myaddon__connect-provided-link-to-panel",                
                "name": {
                    "value": "My Web Panel"
                }
            }
        ]        
     }
 }

Расширенная реализация

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

Расширение боковой панели

Если вы хотите настроить боковую панель для своей надстройки, ее можно расширить более продвинутыми способами с помощью фильтров областей, API JavaScript или API-интерфейсов Serverside Rendering. Боковая панель визуализируется и предоставляется новым плагином jira-projects. Следовательно, чтобы использовать любой из продвинутых методов для расширения боковой панели, вам нужно будет включить jira-projects-api jar в ваших зависимостях надстройки:


<dependency>
    <groupId>com.atlassian.jira</groupId>
    <artifactId>jira-projects-api</artifactId>
    <version>${latest.jira.projects.plugin.version}</version>
    <scope>provided</scope>
</dependency>

Расширенные методы для расширения боковой панели:

Фильтры области

Проекты JIRA предоставляют дополнительный фильтр области, позволяющий пользователям выбирать специфичную для проекта доску Agile. Фильтры области могут добавить дополнительный контекст, используемый для рендеринга веб-элементов и содержимого страницы через новый модуль плагина project-scope-filter-context-provider. Это полезно, если веб-элементы на боковой панели требуют дополнительного контекста, по которому была выбрана гибкая плата.

Пример:

В примере JIRA Agile следующий поставщик контекста фильтра области предоставляет дополнительные параметры для веб-элементов, определенных в JIRA Agile, которые подключаются к боковой панели:


<project-scope-filter-context-provider key="board-scope-filter" class="com.atlassian.greenhopper.web.sidebar.AgileBoardScopeFilterContextProvider" />

Это просто реализует следующий интерфейс, предоставляемый jira-projects-api:


/**
 * Provides a context map with scope filter params that may be needed to render project links and pages.  For example
 * JIRA may decide to put the currently selected board into the context which will then be used to add
 * Agile reports to the reports page.
 *
 * @since v1.6.0
 */
public interface ProjectScopeFilterContextProvider
{
    /**
     * Given a project, return context with scope filter params.
     *
     * @param project the currently selected project
     * @return context param map
     */
    Map<String, Object> getContext(final Project project);
}

Дополнительный контекст, предоставляемый этим механизмом, может затем использоваться при визуализации ссылок. Например, используя дополнительный параметр selectedBoardId в URL-адресе следующим образом:


<web-item key="project-sidebar-work-scrum" name="Scrum Work Mode Button in the Project Sidebar" section="jira.project.sidebar.plugins.navigation" weight="8">
    <label key="gh.rapid.pool.link.scrum.label"/>
    <link>/secure/RapidBoard.jspa?projectKey=$pathEncodedProjectKey&rapidView=$selectedBoardId</link>
    <param name="iconClass" value="aui-icon-large agile-icon-work"/>
    <condition class="com.atlassian.greenhopper.web.sidebar.IsScrumBoardCondition"/>
</web-item>

JavaScript API

Боковая панель также предоставляет богатый javascript API, позволяющий надстройкам, если это необходимо, переопределять поведение по умолчанию на клиентской стороне. Для получения дополнительной информации см. JavaScript API боковой панели для JIRA-проектно-ориентированного представления.

API рендеринга Serverside

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

РИСУНОК

Основная точка входа для создания ориентированной на проект боковой панели обеспечивается компонентом ProjectSidebarRenderer и его методом render (projectKey, selectedItemId).

Расширение содержимого страницы

Полный контроль рендеринга

Вы должны использовать эту опцию только для дополнительных надстроек, где вам необходим полный контроль над состоянием URL. Примером этого является гибкая доска JIRA, где боковая панель позволяет пользователям переключаться между Backlog, Active Sprints и Reports с помощью боковых ссылок на стороне клиента.

Этот подход позволяет реализовать расширенную навигацию, такую как поднавигация на странице. Однако во многих случаях лучше реализовать основную веб-панель (описанную выше) - вот некоторые из причин:

Веб-панель проще реализовать, особенно если у вас есть простая (статическая) надстройка.
Боковая панель отображается для вас. Кроме того, контекст для вашей веб-панели заполняется теми же параметрами проекта и параметрами scopefilter, что и для веб-элементов.

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

Веб-ресурсы клиентской стороны на боковой панели уже включены.

Если вы решите реализовать полный контроль над рендерингом, надстройка должна включать веб-ресурсы клиентской стороны боковой панели в контексте jira.project.sidebar.

ProjectPageServlet в плагине jira-projects выбирает правильный элемент на боковой панели на основе selectedItem параметра URL-адреса.

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

Чтобы реализовать полный контроль над рендерингом для содержимого вашей страницы надстройки:

Выделите всю страницу, включая декоратор sitemesh, используя существующий механизм плагинов (скорее всего, сервлет или действие веб-сайта).
В этом действии сервлета или веб-сайта запустите компонент ProjectSidebarRenderer и вы получите HTML-код боковой панели с использованием соответствующей структуры страницы AUI. Плагин jira-projects предоставляет шаблон soy JIRA.Projects.Templates.page, чтобы сделать это проще
Требовать все веб-ресурсы в контексте веб-ресурса jira.project.sidebar.

Компонент суб-навигации контента(содержимого)

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

Плагин jira-projects предоставляет субнавигатор содержимого как компонент многократного использования. Поднавигатор - это компонент, который визуализируется на стороне клиента, используя код JavaScript. Чтобы использовать этот компонент, ваш плагин должен объявить зависимость с com.atlassian.jira.jira-projects-plugin: subnavigator, так что необходимые ресурсы JavaScript будут загружены и доступны в браузере.

РИСУНОК

Процедуру реализации этого компонента лучше всего объяснить на примере: рассмотрите страницу отчетов, показанную на скриншоте справа. Это то, как он приносит ресурсы, необходимые для использования субнавигатора subnavigator на стороне клиента:


 <web-resource key="reports-page-subnavigator">
     <context>com.atlassian.jira.project.reports.page</context>
     <dependency>com.atlassian.jira.jira-projects-plugin:sidebar</dependency>
     <dependency>com.atlassian.jira.jira-projects-plugin:subnavigator</dependency>
     <resource location="/page/project/report/subnavigator-init.js" name="reports-subnavigator-init.js" type="download"/>
     <transformation extension="js">
         <transformer key="jsI18n"/>
     </transformation>
 </web-resource>

Как вы можете видеть, на веб-ресурсе reports.page есть зависимость, так что всякий раз, когда загружается страница, загружаются ресурсы субнавигатора.

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


var subnavigator = new JIRA.Projects.Subnavigator({
    id: "reports",                                       // identifier for the subnavigator component 
    triggerPlaceholder: triggerPlaceholder,              // css selector where the trigger of the the component will be rendered
    contentPlaceholder: contentPlaceholder,              // css selector where the options of the component will be rendered
    itemGroups: [{                                       // array of arrays, each of one containing a list of items to be displayed by the container
        id: "report-id",                                 
        label: "report-label",                           // text that will be displayed for the item
        description: "report-description",                // text that will be displayed on a tooltip when the mouse is over the item
        link: "report-url"                               // link to follow when the item is selected
    }],
    selectedItem: "selected-report-id"                   // id of the initially selected item
});
subnavigator.show();
 
subnavigator.on("itemSelected", function(event) {        // listening for changes on the selected item
    event.preventDefault();         
    console.log(event.item);                             // the event will give you access to the selected item
});

Наиболее подробную и актуальную документацию по этому компоненту можно найти в исходном коде src / main / resources / static / components / subnavigator / Subnavigator.js

Объекты jira-projects-page-objects также предоставляют Subnavigator.java, которые вы можете использовать в качестве объекта PageObject для компонента в тестах веб-драйверов.

Нужна помощь?

Попробуйте следующие ресурсы:

Отправьте свой вопрос на наши форумы: Atlassian Answers. Это, вероятно, самый быстрый способ получить помощь, так как многие наши клиенты и сотрудники активны в ответах Atlassian.

По материалам Atlassian JIRA Server Developer Developing for the JIRA project-centric view