1. Главная
  2. ИЗУЧЕНИЕ
  3. Руководства
  4. Использование JavaScript- API боковой панели для проектно-ориентированного представления JIRA

Использование JavaScript- API боковой панели для проектно-ориентированного представления JIRA

В этом документе будет показано, как разрабатывать новую боковую панель JIRA с помощью JavaScript API.

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

 

Доступ к боковой панели

API боковой панели - это одноэкранный объект, открытый под глобальной переменной JIRA.API.Sidebar. Обратите внимание, что эта глобальная переменная загружается асинхронно.

Если вам нужно знать, когда боковая панель готова к использованию, используйте JIRA.API.getSidebar (). Этот метод вернет обещание, которое в конечном итоге будет разрешено, когда боковая панель готова. Например:


JIRA.API.getSidebar().done(function(Sidebar)) {
    // Using local reference
    Sidebar.getGroup('workflow');
 
    // Using global reference
    JIRA.API.Sidebar.getGroup('workflow');
})

Выбор элементов

Группы навигации

Боковая панель представляет собой набор NavigationGroup. Группа NavigationGroup определяется элементом HTML с классом aui-sidebar-group. Каждая NavigationGroup может иметь необязательный идентификатор, определяемый атрибутом идентификатора данных  data-id (основная группа имеет идентификатор «по умолчанию»). Если группа не найдена, метод get возвращает undefined. Если есть две группы с одинаковым идентификатором, боковая панель регистрирует предупреждение в консоли JavaScript. Когда группа выбрана, вы можете использовать group.id для получения идентификатора группы.


<div class="aui-navgroup-inner">

    <div class="aui-sidebar-group" data-id="sidebar-navigation-panel">...</div>
    <div class="aui-sidebar-group" data-id="workflow">...</div>
    <div class="aui-sidebar-group">...</div>

</div>



// Get group by ID:
JIRA.API.Sidebar.getGroup('workflow'); 
 
// Get group by index:
JIRA.API.Sidebar.getGroupAt(1);        

// Get the default group, these methods are equivalent:
JIRA.API.Sidebar.getDefaultGroup(); 
JIRA.API.Sidebar.getGroup('sidebar-navigation-panel'); 
JIRA.API.Sidebar.getGroupAt(0); 


// Get the ID of the group
console.log(JIRA.API.Sidebar.getGroupAt(1).id) //"workflow"

Элементы навигации

Каждая группа представляет собой набор элементов NavigationItems. Элемент навигации определяется элементом списка (<LI> внутри <UL>), который содержит тег <A>. Элемент навигации может содержать необязательный идентификатор, определенный атрибутом data-link.id. Если есть два элемента с одинаковым идентификатором, боковая панель регистрирует предупреждение в консоли. Если пользователь вызывает getItem () / getItemAt () непосредственно на боковой панели, он будет искать элемент в группе по умолчанию. Подобно getGroup () / getGroupAt (), если элемент не существует, он возвращается неопределенным undefined. Когда элемент выбран, вы можете использовать item.id для получения идентификатора элемента.


<div class="aui-sidebar-group" data-id="sidebar-navigation-panel">
    <ul>
        <li><a href="/plan" data-link-id="plan">Plan</a></li>
        <li><a href="/work" data-link-id="work">Work</a></li>
        <li><a href="/report">Report</a></li>
    </ul>
</div>



// Get group by ID, two ways of getting the 'plan' item.
JIRA.API.Sidebar.getDefaultGroup().getItem('plan'); 
JIRA.API.Sidebar.getItem('plan');
 
// Get group by index, two ways of getting the 'report' item.
JIRA.API.Sidebar.getDefaultGroup().getItemAt(2); 
JIRA.API.Sidebar.getItemAt(2); 
 
// Get the ID of the item
console.log(JIRA.API.Sidebar.getItemAt(1).id) //"work"

Навигационные подгруппы

Подгруппа навигации является вложенной группой внутри NavigationSubgroup. Она определяется вложенным списком <UL> / <LI> внутри элемента навигации. Чтобы выбрать его, пользователь может использовать getItem () / getItemAt (). Группа NavigationSubgroup  ведет себя как NavigationGroup, пользователь может использовать getItem () / getItemAt () для выбора элементов внутри NavigationSubgroup. Как обычно, если NavigationSubgroup не существует, она будет возвращена undefined. Когда подгруппа выбрана, вы можете использовать subgroup.id для получения идентификатора подгруппы.


<div class="aui-sidebar-group" data-id="sidebar-navigation-panel">
    <ul>
        <li>
            <a href="#" data-link-id="releases">Releases</a>
            <ul>
                <li><a href="#">Release #1</a></li>
                <li><a href="#">Release #2</a></li>
                <li><a href="#" data-link-id="all">All</a></li>
        </li>
    </ul>
</div>



// Get the navigation subgroup.
JIRA.API.Sidebar.getItem('releases');
JIRA.API.Sidebar.getItemAt(0);
 
// Get the items inside the navigation subgroup.
JIRA.API.Sidebar.getItem('releases').getItemAt(0);
JIRA.API.Sidebar.getItem('releases').getItem('all');
 
// Get the ID of the subgroup
console.log(JIRA.API.Sidebar.getItemAt(0).id) //"releases"

Реакция на действия пользователя

Кликанье по ссылке

Когда пользователь нажимает на NavigationItem, боковая панель бросает события, чтобы программно реагировать на действие клика. По умолчанию она будет следовать ссылке, указанной в атрибуте href.

Эти три события запускаются по порядку:

  • before:select
  • select
  • before:navigate

Обратите внимание: эти события не запускаются для ссылок, которые открываются на новой вкладке (т. е. С target = "_ blank" или нажатой клавишей ctrl / cmd).

перед тем: выбрать  before:select

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


// When the user clicks on the Releases > All link...
JIRA.API.Sidebar.getItem('releases').getItem('all').on('before:select', function(event) {
    // Avoid item to be selected.
    event.preventDefault();
    
    // Notify the user.
    alert('All releases functionality is not ready yet :(');
});

Выбрать select

Это похоже на событие before: select, но это означает, что боковая панель отмечена как выбранный элемент (то есть, это происходит before:select). Это событие невозможно предотвратить.

перед тем: перейти before:navigate

Это событие означает, что боковая панель (более конкретно: браузер) собирается перейти к URL-адресу, указанному в элементе. Это событие можно предотвратить. Если это не предотвращено, браузер загрузит другую страницу. Используйте это событие, если вы хотите избежать загрузки страницы, но по-прежнему хотите, чтобы элемент был помечен как выбранный.


// When the user clicks on the Releases > All link...
JIRA.API.Sidebar.getItem('releases').getItem('all').on('before:navigate', function(event) {
    // Stop navigation
    event.preventDefault();
    
    // Load the releases
    JAG.ReleaseManager.render('all');
});

Отмена выбора ссылки Deselecting a link

Когда пользователь нажимает ссылку, боковая панель отменяет выбранную ссылку (если она есть). Это действие также вызывает два события:

  • before:deselect
  • deselect

Эти события аналогичны событиям: before:select  и select. Например, пользователь может предотвратить before:deselect, чтобы остановить выбор пункта от снятия выделения (и нового элемента от выделения), и попросить пользователя подтвердить его перед окончанием.


// For example, use keyboard shortcuts to select an item
JIRA.API.Sidebar.getItem('releases').getItem('all').on('before:deselect', function(event) {
    var wantToLeave = confirm("Are you sure you want to leave this awesome page?");
    if (!wantToLeave) event.preventDefault();
});

Пример рабочего процесса - изменение выбора

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

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

  1. Запуск before: select на B. Если это предотвращено, остановитесь сейчас
  2. Запуск before: deselect на A. Если это предотвращено, остановитесь сейчас.
  3. Отменить выбор элемента A.
  4. Запуск deselect на A.
  5. Выбор пункта B
  6. Запуск select на B.
  7. Запуск before: navigate на B. Если это предотвращено, остановитесь сейчас.
  8. Перейдите к ссылке B.

 

Моделирование действий пользователя

Имитация действий пользователяAPI предоставляет два метода для имитации действий пользователя, select () и navigate():

select ()

Этот метод выделит выбранный элемент, но он не будет выполнять навигацию. Он активирует события before: select и select. Это следует использовать, когда плагин изменил страницу и вы хотите сообщить пользователю о новой странице.


switch(GH.RapidBoard.ViewController.getMode()) {
    case 'plan':
        JIRA.API.Sidebar.getGroup('sidebar-workflow-panel').getItem('com.pyxis.greenhopper.jira:project-sidebar-plan').select();
        break;
    case 'work':
        JIRA.API.Sidebar.getGroup('sidebar-workflow-panel').getItem('com.pyxis.greenhopper.jira:project-sidebar-work').select();
        break;
    case 'report':
        JIRA.API.Sidebar.getGroup('sidebar-workflow-panel').getItem('com.atlassian.jira.jira-projects-plugin:report-page').select();
        break;
}

Вы можете использовать этот метод в следующих сценариях:

  • Начальная загрузка плагина
  • Изменение страницы плагина с помощью сочетаний клавиш
  • Изменение страницы с использованием внутренних ссылок в плагине

navigate()

Этот метод будет следовать ссылке, указанной в HREF. Это приведет к предупреждению события before:navigate. Плагины могут использовать этот метод для перезапуска, так как вызов navigate () приведет к загрузке новой страницы. Например:


// For example, use keyboard shortcuts to go to an item
AJS.whenIType('1').execute(function(){
    JIRA.API.Sidebar.getItem('plan').navigate();
});

Прослушивание нескольких элементов

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

Чтобы помочь в этом случае, все события (before:select, select, before:navigate, before:deselect и deselect) будет «пузыриться» из элемента вплоть до компонента боковой панели, включая любую группу или подгруппу. Пользователь может прослушивать события в любой из групп и использовать event.emitter для доступа к фактическому элементу, который вызвал событие.


// When 'Releases > All' is selected, all these handlers will be triggered:
// JIRA.API.Sidebar.getGroup('workflow').getItem('releases').getItem('all').on(<event>, <handler>);
// JIRA.API.Sidebar.getGroup('workflow').getItem('releases').on(<event>, <handler>);
// JIRA.API.Sidebar.getGroup('workflow').on(<event>, <handler>);
// JIRA.API.Sidebar.on(<event>, <handler>);
 
// Example
JIRA.API.Sidebar.getGroup('workflow').on('before:navigate', function(event) {
    event.preventDefault();
 
    // Which element was selected?
    switch (event.emitter.id) {
        case "plan": JAG.PlanView.render(); break;
        case "workflow": JAG.WorkflowView.render(); break;
        case "report": JAG.ReportsView.render(); break; 
    }
});

О порядке событий

Порядок, в котором запускается событие с пузырьками, не является надежным: некоторые события запускают событие на элементе сначала, а затем в родительских группах, в то время как другие события делают обратное. Этот порядок глубоко зарывается в библиотеки, которые использовались для реализации боковой панели, и это явно не документировано. Это означает, что он может меняться без предупреждения. Следовательно, вы не должны предполагать, что JIRA.API.Sidebar.on ('select', ...) будет выполнен после JIRA.API.Sidebar.getItem ('release'). on ('select', ...)

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

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

  • Отправьте свой вопрос на наши форумы: Ответы Atlassian. Это, вероятно, самый быстрый способ получить помощь, так как многие наши клиенты и сотрудники активны в ответах Atlassian.
  • Свяжитесь с командой разработчиков: https://developer.atlassian.com/help#contact-us. Обратите внимание: вам нужно будет создать учетную запись developer.atlassian.com, если у вас ее еще нет.

По материалам Atlassian JIRA  Server Developer Using the sidebar JavaScript API for the JIRA project-centric view