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

    Зачем?





    Тот, кто когда-нибудь интересовался вопросом “подгонки” 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 технологией и будет ли идти в стандартной поставке — покажет время и активность расширениеписателей. Но это никак не помешает нам сделать уже сегодня свою жизнь чуточку проще :)

    Поделиться публикацией
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама

    Комментарии 0

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

    Самое читаемое