cr0ck 17 ноя 2011 в 16:53

Расширение Atlassian Confluence и JIRA при помощи Speakeasy

7 мин

7.2K

Зачем?

Тот, кто когда-нибудь интересовался вопросом “подгонки” JIRA, Confluence или другого продукта Atlassian под себя, знает, что для этих целей существует Atlassian SDK.

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

Особенно обидно, когда в разгар работы над важным проектом, при катастрофической нехватке времени, кто-то из клиентов просит прикрутить какую-то маленькую рюшечку в Confluence или спрятать какую-нибудь ссылочку в JIRA. И клиентов приходится просить подождать, на что те имеют привычку обижаться. А усугубляет проблему тот факт, что у клиента зачастую есть свои штатные программисты, которые, к сожалению, ничем помочь не могут, т.к. не обладают знаниями в разработке плагинов для продуктов Atlassian и приобрести этот опыт за пару дней не выйдет.

Видимо, это понимают и ребята из Atlassian, поэтому и представили на суд пользователей и администраторов технологию Speakeasy. Сама технология уже не нова — представление её ранней беты было приурочено к Codegeist 2011, соревнованию для разработчиков плагинов, но только сейчас, похоже, выходят более-менее стабильные версии, которые можно не побояться установить в production-систему.

Speakeasy, в отличие от Atlassian SDK, позволяет кастомизировать только то, что видит пользователь — изменять страницы, добавляя на них JavaScript, разметку или стили. Но и делается это намного проще, чем с использованием SDK. Что-то подобное делает Firefox-дополнение Greasemonkey, но здесь мы не ограничиваемся одним браузером и не заставляем самого пользователя что-то там еще специально устанавливать.

Кому это нужно?

Хотя так и тянет назвать Speakeasy массовой технологией, которая позволит кастомизировать JIRA и Confluence любому пользователю, очевидно, это не совсем так. В большинстве случаев (но не всегда) понадобятся базовые навыки JavaScript-программирования и верстки HTML+CSS. Но зато для этого не нужно читать доки по Atlassian SDK! А это, на минуточку, сотни интересных и интригующих страниц на английском.

Поэтому в число людей, которые могут получить profit от Speakeasy, я бы причислил:

Разработчиков, а тем более веб-разработчиков. Эти люди практически сразу, без дополнительной подготовки, могут начать делать расширения с помощью Speakeasy.
Администраторов. Администраторы, зачастую, тоже умеют программировать и смогут сделать какое-нибудь расширение для любимых пользователей. А если учитывать, что, при использовании Speakeasy, сами пользователи решают, использовать им какое-либо расширение или нет, то получаем огромное пространство для лавирования между их взаимоисключающими пожеланиями.
Менеджеры теперь не будут грустить после фразы разработчика “Да сделаю такую штуку, но нужно две недели на изучение SDK и еще месяц буду проводить эксперименты”, а с чистой (ну или почти чистой) совестью скажут “Ничего учить не надо! Иди сразу делай, уважаемый!”

И сразу в бой!

Давайте создадим с нуля несколько простых, но полезных расширений. Все примеры приведены для Confluence 3.5, т.к. свежая версия 4.0 еще не так сильно пошла в народ. Но практически все нижесказанное будет адекватно и для 4-й версии. Соответственно, никаких принципиальных отличий не будет и при разработке расширения для JIRA.

Пример 0, который совсем не пример — Установка Speakeasy

Для начала все-таки понадобится администратор, чтобы установить Speakeasy на сервер и раздать нужные права.

Свежие и не очень версии Speakeasy раздают в Plugin Exchange и в соответствующем maven-репозитории.

После того, как плагин установлен, следует определиться, у каких групп пользователей будет право на создание своих расширений, а какие группы пользователей смогут эти расширения для себя включать (Administration — Plugins — Manage Existing — Speakeasy Plugin — Configure).

Следует отдельно отметить, что по умолчанию администратору запрещено включать для себя расширения на Speakeasy. Сделано это, очевидно, в целях безопасности. Но на тестовой системе настройку «Allow administrators to enable extensions» можно и включить.

Пример 1 — Исторический

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

Идем на страницу с расширениями Speakeasy.

Жмем ссылку Install и в появившемся диалоге выберем использование Wizard-а, а в самом Wizard-е введем уникальный идентификатор расширения, его название и описание.

После этого будет создано и установлено расширение с такими «параметрами» и стандартным тестовым наполнением. Кнопочкой «More — Edit» мы попадаем в простенький, но полезный web-редактор, где можем и запрограммировать пару строчек нашего расширения.

Нас интересует файл main.js, ибо в нем и должна находиться основная логика на JavaScript.

/**
* @context page
*/
var $ = require('speakeasy/jquery').jQuery;

$(document).ready(function() {
 var href = $('a#action-view-history-link').attr('href');
 $('a#view-change-link').after(", <a href='"+ href +"'>view history</a>");
});

Для знающего JS и jQuery человека написание таких строк не составит вообще никакого труда, но и те, кто с JavaScript не дружит, смогут написать подобный код при помощи google. Отдельно только упомяну про запись "@context page" в комментарии. Она указывает, на каких контекстах (читай, типах страниц) следует выполнять этот скрипт. Сейчас нас интересуют только wiki-страницы, а перечень контекстов можно найти на этой странице.

А вот что мы получим в результате:

Пример 2 — Информативный

Модифицировать что-то в стандартном UI — это здорово, а еще лучше, когда мы можем наполнить модифицированный UI какой-то новой информацией.

Для получения информации можно использовать все возможности JavaScript/JQuery — REST, SOAP, XML-RPC. Благо у Confluence и JIRA такие интерфейсы есть.

Попробуем воспользоваться самым простым REST-интерфейсом, по которому можно только получать информацию о различных сущностях из Confluence. Запросим дату создания страницы, чтобы органично разместить её в стандартном интерфейсе Confluence рядом с датой последнего редактирования.

Код в этом случае выглядит так:

/**
* @context page
*/
var $ = require('speakeasy/jquery').jQuery;

$(document).ready(function() {
 var pageId = $('input#pageId').attr('value');
 var serviceUrl = '/rest/prototype/1/content/' + pageId + '.json';
 $.getJSON( serviceUrl, function(data) {
   $('li.page-metadata-modification-info a:first').after(" on " + data.createdDate.friendly);
 });
});

А вот и модифицированный UI:

Т.к. все скрипты отрабатывают при загрузке страницы, то пользователь не замечает никаких “мельканий” вроде “даты не было и внезапно появилась”.

Пример 3 — Пунктуальный

В расширениях на Speakeasy доступны и некоторые специфические для продуктов Atlassian вещи. Среди них — работа с WebItem. Говоря по-простому, у вас есть возможность добавить свои пункты меню на страницы, рядом со стандартными пунктами.

Для этого, внутри расширения находится файл web-items.json, в котором описывается нужный вам пункт меню. Перейдем сразу к примеру:

[
   {   "section" : "system.content.action/primary",
       "label"   : "Revert",
       "url"     : "",
       "cssName" : "stiltsoft-web-item",
       "weight"  : 25
   }
]

Здесь создается новый пункт с названием Revert в меню Tools. В параметре URL может задаваться нужный вам адрес, но я поступил немного хитрее и не задал URL, но добавил этому пункту логику на JavaScript (см. далее).

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

/**
* @context atl.general
*/
var $ = require('speakeasy/jquery').jQuery;

$(document).ready(function() {
   var pageId = $('input#pageId').attr('value');
   var revision = $("meta[name='page-version']").attr('content');    
   $('a.revert-web-item').attr('href','/pages/revertpagebacktoversion.action?pageId='+pageId+'&version='+(revision-1));
});

Выглядит этот пункт так:

Пример 4 — Диалоговый

Не забыли разработчики SpeakEasy и о любителях создавать красивые интерфейсы. В сам Speakeasy включена возможность создать красивый диалог, в стиле самого Confluence/JIRA с помощью метода openOnePanelDialog. Вот так это выглядит в коде:

/**
* The main module
*
* @context atl.general
*/
var $ = require('speakeasy/jquery').jQuery;
var dialog = require('speakeasy/dialog');

$(document).ready(function() {
   $('span#title-text').after("<span class='stiltsoft-source'><a href='#' id='stiltsoft-view-source'>View source</a></span>");
 $('a#stiltsoft-view-source').click(function(){
   var url=$('a#action-view-source-link').attr('href');
   $.get(url,function(data){

     dialog.openOnePanelDialog(
     {
       'header':'Page source',
       'content':$(data).find('div#content'),
       'submitLabel':'OK',
       'cancelClass':'stiltsoft-cancel',
       'submit':function(dialog,callback){
         callback.success();
       }
     });    

   }         
 );

   return false;
 });
});

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

Примерно вот так, это выглядит на экране:

Для тех, кому одного диалога не достаточно, стоит обратиться к библиотеке AUI (Atlassian User Interface). Это полностью клиентская JavaScript-библиотека, содержащая все те основные элементы (диалоги, попапы, выпадающие меню и т.п.), из которых собирается интерфейс продуктов Atlassian. Поэтому ваше расширение, использующее AUI, не будет отличаться по внешнему виду от остального интерфейса.

Чтобы сразу “окунуться” в эту технологию, советую посетить AUI Demo, AUI Sandbox и немного поиграться с элементами там присутствующими.

Пример 5 — Волшебный

Самые ленивые из нас могут воспользоваться специальным Firefox-плагином (созданном на основе platypus), который позволяет визуально вносить изменения в страницу, а затем сохранять получившиеся изменения в виде SpeakEasy-расширения.

И, конечно же, лучше один раз увидеть. Видео от разработчиков:

Что дальше?

Технология Speakeasy продолжает развиваться, хотя, надо сказать, ничего сверхъестественного в ней нет. Зато есть удобное и полезное. Станет ли Speakeasy “штатной” для продуктов Atlassian технологией и будет ли идти в стандартной поставке — покажет время и активность расширениеписателей. Но это никак не помешает нам сделать уже сегодня свою жизнь чуточку проще :)

Теги:

Хабы: