What for?

Anyone who has ever been interested in the issue of “fitting” JIRA , Confluence or another Atlassian product to you knows that the Atlassian SDK exists for this purpose.

And the one who has been digging at least once in this SDK represents how much time and small gray cells should be spent in order to penetrate into all this, especially if there is no older comrade who will instruct on the true path.

It is especially offensive when, in the midst of work on an important project, with a catastrophic lack of time, one of the clients asks to fasten some small thingies in Confluence or hide some reference in JIRA. And customers have to ask to wait, what they are accustomed to take offense. And the problem is aggravated by the fact that the client often has its own full-time programmers who, unfortunately, cannot do anything, because do not have knowledge in the development of plug-ins for Atlassian products and will not be able to gain this experience in a couple of days.

Apparently, the Atlassian guys also understand this, which is why Speakeasy technology was presented to users and administrators. The technology itself is no longer new - the presentation of its early beta was timed to Codegeist 2011 , a competition for plug-in developers, but only now it seems that more or less stable versions are coming out that you can not be afraid to install in a production system.

Speakeasy, unlike the Atlassian SDK, allows you to customize only what the user sees — change pages by adding JavaScript, markup, or styles to them. But it makes it much easier than using the SDK. Something like this makes the Firefox add-on Greasemonkey , but here we are not limited to one browser and do not force the user to install something else there.

Who needs it?

Although it calls for Speakeasy to be a mass technology that will allow any user to customize JIRA and Confluence, this is obviously not quite the case. In most cases (but not always) you will need basic JavaScript programming skills and HTML + CSS layout. But for this you do not need to read the docks on the Atlassian SDK! And this, for a moment, hundreds of interesting and intriguing pages in English.

Therefore, in the number of people who can get profit from Speakeasy, I would count:

• Developers, and especially web developers. These people almost immediately, without additional training, can begin to make extensions using Speakeasy.
• Administrators. Administrators, too, often know how to program and will be able to make some extension for their favorite users. And if we take into account that when using Speakeasy, the users themselves decide whether to use any extension for them or not, then we get a huge space for maneuvering between their mutually exclusive wishes.
• Managers will no longer be sad after the phrase of the developer “Yes, I will do such a thing, but I need two weeks to study the SDK and will conduct experiments for another month,” and they will say with a clean (or almost pure) conscience “You don’t need to learn anything! Go do it immediately, dear! ”

And immediately into battle!

Let's create from scratch a few simple but useful extensions. All examples are given for Confluence 3.5, since fresh version 4.0 is not so much gone to the people. But almost all of the below will be adequate for the 4th version. Accordingly, there will be no fundamental differences in the development of extensions for JIRA.

Example 0, which is not an example at all - Speakeasy Setup

To get started, you still need an administrator to install Speakeasy on the server and distribute the necessary rights.

Fresh and not so versions of Speakeasy are distributed in the Plugin Exchange and in the corresponding maven repository .

After the plugin is installed, you should decide which groups of users will have the right to create their extensions, and which groups of users will be able to include these extensions for themselves (Administration - Plugins - Manage Existing - Speakeasy Plugin - Configure).

It should be noted separately that by default the administrator is not allowed to include Speakeasy extensions. This is done, obviously, for security purposes. But on the test system, the “Allow administrators to enable extensions” setting can be enabled.

Example 1 - Historical

In this example, we add a link to the history of the page in a prominent place so as not to climb every time behind it in the drop-down menu.

We go to the page with Speakeasy extensions.

Click the Install link and in the dialog that appears, choose to use the Wizard, and in the Wizard itself we will enter the unique identifier of the extension, its name and description.

After that, an extension with such “parameters” and standard test content will be created and installed. With the “More - Edit” button we find ourselves in a simple but useful web editor where we can program a couple of lines of our extension.

We are interested in the main.js file, because it should contain the main JavaScript logic.

/** * @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>"); }); 

For a person who knows JS and jQuery, writing such strings will not be difficult at all, but those who are not friends with JavaScript will be able to write similar code using google. Separately, I will only mention the entry "@context page" in the comment. It indicates which contexts (read, page types) this script should run. Now we are only interested in wiki-pages, and a list of contexts can be found on this page .

And this is what we get as a result:

Example 2 - Informative

Modifying something in the standard UI is great, and even better when we can fill the modified UI with some new information.

For information you can use all the features of JavaScript / JQuery - REST, SOAP, XML-RPC. Fortunately, Confluence and JIRA have such interfaces .

Let's try to use the simplest REST interface, which can only receive information about various entities from Confluence. We will request the date of the page creation to organically place it in the standard Confluence interface next to the date of the last edit.

The code in this case looks like this:

 /** * @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); }); }); 

And here is the modified UI:

Because all the scripts work out when the page loads, the user does not notice any “flickering” like “there was no date and it suddenly appeared”.

Example 3 - Punctual

Some Atlassian-specific things are available in Speakeasy extensions. Among them - work with WebItem . Speaking in a simple way, you have the opportunity to add your menu items to the pages, next to the standard items.

To do this, inside the extension is a file web-items.json, which describes the menu item you need. Let's go straight to the example:

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

This creates a new item called Revert in the Tools menu. The URL parameter can specify the address you need, but I acted a bit more cunning and did not specify the URL, but added JavaScript to this item (see below).

The item itself is needed to quickly roll back to the previous revision of the page, and the JavaScript code, respectively, calculates the number of this revision:

 /** * @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)); }); 

This item looks like this:

Example 4 - Interactive

SpeakEasy developers and fans of creating beautiful interfaces have not forgotten. Speakeasy itself includes the ability to create a beautiful dialogue, in the style of Confluence / JIRA itself, using the openOnePanelDialog method. This is what the code looks like:

 /** * 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; }); }); 

This code adds a View Source link to the page header, which, in fact, displays a beautiful dialog with the source code of the page. In the extension, there was a little more magic with CSS to hide the extra dialog buttons, but for example this is not the most important.

Something like this, it looks like on the screen:

For those who do not have just one dialogue, it is worth referring to the AUI (Atlassian User Interface) library. This is a fully client-side JavaScript library containing all those main elements (dialogs, popups, drop-down menus, etc.) from which the Atlassian products interface is built. Therefore, your extension using AUI will not differ in appearance from the rest of the interface.

In order to immediately “plunge” into this technology, I advise you to visit AUI Demo , AUI Sandbox and play a bit with the elements there.

Example 5 - Magic

The laziest of us can use a special Firefox-plugin (created on the basis of platypus ), which allows you to visually make changes to the page, and then save the resulting changes in the form of SpeakEasy-extension.

And, of course, it is better to see once. Developer videos:

What's next?

Speakeasy technology continues to evolve, although, I must say, there is nothing supernatural about it. But there is a convenient and useful. Whether Speakeasy will become “standard” for Atlassian products with technology and whether it will come in a standard package will be shown by the time and activity of the expansion of the writers. But it does not hurt us to make our life a little easier today :)