Extending Autoconvert - takumi-memo @ ウィキ

Overview of the Tutorial

このチュートリアルは、特定のコンテントのURLを書き直すためのConfluence Autoconvertの拡張をどのようにするかについて触れる。
次のコンポーネントを構成するプラグインを作成する。

• A JavaScript file providing an Autoconvert handler.
• A plugin descriptor (XML file) to enable the plugin module in the Atlassian application.

これらのコンポーネントは全て、単一のJAR Fileに含まれている。

Required Knowledge

このチュートリアルを完全なものにするために, JavaScript developmentの基礎についての知識が必要である。

• How to create an Atlassian plugin project using the Atlassian Plugin SDK.

Step 1. Create the Plugin Project

まずはプラグインプロジェクトを作成する。

• group-id: com.example.plugins.tutorial
• artifact-id: autoconvert-dev-docs

Step 2. Add Plugin Metadata to the POM

プラグインなどの情報に関するmetadataを加えるために、POM fileを編集する。

• 1.Edit the pom.xml file in the root folder of your plugin.
• 2.Update the <confluence.version element to at least Confluence 4.1:

   <confluence.version>4.1</confluence.version> 

3.Add your company or organisation name and your website to the <organization> element:

   <organization>     <name>Example Company</name>     <url></url> </organization> 

4.Update the <description> element:

   <description>Changes link text on URLs pasted from developer.atlassian.com.</description> 

5.Save the file.

Step 3. Add a Plugin Module to the Plugin Descriptor

src/main/resources/atlassian-plugin.xmlのプラグイン・ディスクリプタにプラグイン・モジュールを追加する。

The extension point for Autoconvert is through JavaScript, so you'll need to add a JavaScript Web Resource Module.

Your web resource module needs to specify the location of a js file that will create your autoconvert handler. The things that separate it from other Web Resource Modules are:

■It should depend on the core autoconvert plugin so that it will always be loaded after it, and will not be loaded if that plugin is missing.
■It should be loaded whenever the editor is loaded, by specifying the editor context.
Here's one I prepared earlier:

?
<!-- Add this to your atlassian-plugin.xml --> <web-resource key="autoconvert-dev-docs" name="Autoconvert developer.atlassian.com example handler"> <description>Changes link text for URLs pasted from </description> <resource type="download" name="autoconvert-dev-docs.js" location="js/autoconvert-dev-docs.js"/> <!-- This will ensure the resource is loaded after autoconvert, and only if autoconvert is enabled. --> <dependency>com.atlassian.confluence.plugins.confluence-paste:autoconvert-core</dependency> <!-- Assuming the dependency above is met, this context means that whenever the editor is loaded, so is your autoconvert handler. --> <context>editor</context> </web-resource>
Step 4. Write the Code for your Autoconvert Handler
Create a js directory in src/main/resources and create a new file called autoconvert-dev-docs.js file in that directory. Note that this matches the location in the resource in the XML descriptor.

The simplest possible Autoconvert handler looks like this:

?
(function(){ AJS.toInit(function($){ // Create a handler that does nothing but call the continuation: done() var pasteHandler = function(uri, node, done){ done(); }; // Register the handler tinymce.plugins.Autoconvert.autoConvert.addHandler(pasteHandler); }); })();
Focus on the pasteHandler function. The arguments passed to it are:

■uri - a uri object as produced by the parseUri library.
■node - a jquery object for the pasted anchor node.
■done - a continuation function for the pasteHandler to call when it's done. Call it with no arguments when you do not want to change the link, or pass it the replacement or modified node when you do have changes. It should always be called exactly once in all possible code paths.
The continuation done may seem very complicated now, but it's helpful for asynchronous conversions, which we won't discuss in this tutorial.

Take a look at a simple developer.atlassian.com ("DAC") address, such as https://developer.atlassian.com/display/CONFDEV/Confluence+Developer+Documentation.
The parseUri library has a demo page at http://stevenlevithan.com/demo/parseuri/js/. If you paste https://developer.atlassian.com/display/CONFDEV/Confluence+Developer+Documentation into its Input field you will see various uri parts available from the uri object.

In this case the following parts are important:

■host should be "developer.atlassian.com"
■directory should start with "/display/"
■directory should then contain a space key and a page title
■anchor should be blank for now. Converting links to headings is out of scope for this tutorial.
You can split the directory part easily enough using the built-in split function. Note that the directory starts with a slash and split will thus give an array of ["", "display", "CONFDEV", "Confluence+Developer+Documentation"]

So start by writing a condition for when you want to do a conversion:

?
if (uri.host == "developer.atlassian.com" && directoryParts.length == 4 && directoryParts[0] == "" && directoryParts[1] == "display" && uri.anchor == "") {
Then think about what you want to do when we find such a link. The existing URL is fine, you don't need to change anything about the destination, but you do want to change the text of the link. There are a few things you could change it to. You might want to include the spacekey (directoryParts[2]) or an identifier to say that it's on developer.atlassian.com. Eg:

?

But it's probably nicer most of the time to leave it out and just go with the page name. There's also some tidying we have to do. You need to decode any special characters in the path using the built-in decodeURIComponent function, and that still won't turn plus characters into spaces, so you have to do that too using replace:

?
var pageName = decodeURIComponent(directoryParts[3]).replace(/\+/g, " "); node.text(pageName);
Then we have to tell the controlling code, via the continuation, that we do want to replace the node.

?
done(node);
Once the conversion is done, all the handlers will be retried, so the handler has to ensure it doesn't just keep matching forever. The easiest way to do that is add an extra check to the condition, that node.text() == uri.source. All together it looks like this:

?
(function(){ AJS.toInit(function($){ var pasteHandler = function(uri, node, done){ var directoryParts = uri.directory.split('/'), pageName; if (uri.host == "developer.atlassian.com" && directoryParts.length == 4 && directoryParts[0] == "" && directoryParts[1] == "display" && uri.anchor == "" && node.text() == uri.source) { pageName = decodeURIComponent(directoryParts[3]).replace(/\+/g, " "); node.text(pageName); done(node); } else { done(); } }; tinymce.plugins.Autoconvert.autoConvert.addHandler(pasteHandler); }); })();
Step 5. Build, Install and Run the Plugin
Follow these steps to build and install your plugin, so that you can test your code. If you have not already started the application, start it now:

■Open a command window and go to the plugin root folder (where the pom.xml is located).
■Run atlas-run (or atlas-debug if you might want to launch the debugger in your IDE).
From this point onwards, you can use FastDev to reinstall your plugin behind the scenes as you work.

Use the FastDev servlet to trigger the reload:

1.Make the changes to your plugin module.
2.Go to your browser and navigate to the FastDev servlet:
http://localhost:1990/confluence/plugins/servlet/fastdev.
3.Do a hard refresh of the page:
■Shift+Reload in most browsers.
■Ctrl+Reload on Windows or in Internet Explorer.
■In Safari 5, you will need to hold down the Shift key while clicking the Reload icon in the Location bar.
4.Go back to step 1.
As an alternative to FastDev, you can keep the application running in one command window and use the CLI (command line interface) in another window to dynamically re-install your plugin after each change.

1.Open a new command window and go to the plugin's root folder (where the pom.xml is located).
2.Run atlas-cli to start the CLI.
3.Wait until you see a message, Waiting for commands.
4.Run pi (plugin install) to compile, package and install the plugin.
5.Go back to your browser. The updated plugin will have been installed into the application, and you can test your changes. (You may need to refresh the browser page first.)
6.Make your changes in your IDE.
7.Go back to step 1.
The full instructions are in the SDK guide.

Step 6. Try it out.
Try copying the URL of this page and pasting it into the editor. The text of the link should change so that it looks like Plugin Tutorial - Extending Autoconvert rather than just the URL.

Step 7. Play! Write your own extensions.
This is about the simplest autoconvert extension possible, but there are more things you can do. Just quickly, here are a few How-to examples:

Inserting an image
If you want to change the link into an image:

?
var imageUrl = "the url of the image, maybe uri.source, or maybe a modified form of that". done($('<img class="confluence-embedded-image confluence-external-resource" src="' + imageUrl + '" data-image-src="' + imageUrl + '"/>')[0]);
Inserting a macro
If you want to change the link into a Confluence macro (must be a 4.0+ style xhtml macro):

?

Inserting arbitrary converted wiki content
Sometimes the easiest way to write editor format html is to ask Confluence to produce it from wiki markup.

?