Level of experience: Beginner
This tutorial's level of difficulty is at 'beginner' level, so you can follow it even if you have never developed a plugin before. Our tutorials are classified as 'beginner', 'intermediate' and 'advanced'.
On this page:

Overview

This tutorial shows you how to use a Keyboard Shortcut Module in your plugin to add keyboard shortcuts to different parts of the Confluence UI and navigation between pages.

http://www.youtube.com/watch?feature=player_embedded&v=DrIm1zrQ8fQ

In order to do this, you will create a very simple Confluence plugin. Your plugin consists of the following components:

• Plugin descriptor – to enable the plugin module in Confluence.
• An internationalisation properties file – for multi-language support.
• A JavaScript resource – to work around a current bug in the keyboard shortcuts module.

All these components will be contained within a single JAR file. Each component is further discussed in the examples below.

This plugin is designed to show two ways of adding new keyboard shortcuts to Confluence:

1. Navigates to a different page.
2. Scrolls the window to an element and clicks that element.

Source code

The source code of the plugin used in this tutorial is available in Bitbucket. You can browse the source code here: confluence-tutorial-keyboard-shortcuts.

Step 1. Create the plugin project

On the command line type: atlas-create-confluence-plugin

You'll be prompted to enter two values, the group ID and artifact ID. For this tutorial, we used the following values:

• Group ID: com.appfusions.confluence.plugins
• Artifact ID: confluence-tutorial-keyboard-shortcuts

This will create a basic plugin with some Java code and tests. In the sample code, all Java code including tests have been removed as they are not needed for the plugin.

Step 2. Edit the atlassian-plugin.xml file

In this step, you must now register the plugin module in your plugin descriptor, atlassian-plugin.xml. In other words, add the following code to your atlassian-plugin.xml file between the >atlassian-plugin/> tags, but below the >plugin-info/> tag group.

<keyboard-shortcut key="goto.four.oh.four" i18n-name-key="keyboard.shortcut.four.oh.four" name="Page not found">

  <order>200</order>

  <description key="keyboard.shortcut.four.oh.four.desc">Page not found</description>

  <shortcut>404</shortcut>

  <operation type="goTo">/four-oh-four</operation>

  <context>global</context>

</keyboard-shortcut>

Let's break down that XML code. In this example we are creating a keyboard shortcut which when triggered navigates to, for example, http://localhost:1990/confluence/four-oh-four in the development system – a page which does not exist. Admittedly, this is likely to be of limited practical use – unless you are a lover of 404 pages – but it demonstrates the potential of keyboard shortcuts.

To do this, we've done a number of things.

The Keyboard Shortcut module

In the code above, this line involves 3 attributes:

<keyboard-shortcut key="goto.four.oh.four" i18n-name-key="keyboard.shortcut.four.oh.four" name="Page not found">

• The first, key="goto.four.oh.four" sets an internal name for the new item.
• The second, i18n-name-key="keyboard.shortcut.four.oh.four" is the internationalisation key for the item – this is displayed in the admin section as the name of the module in the plugin.
• The third, name="Page not found" defines the default name of the item.

Controlling where the keyboard shortcut is displayed

Examine these line of code:

<order>200</order>

<description key="keyboard.shortcut.four.oh.four.desc">Page not found</description>

Each item has a a value for order between 10 and 100. A smaller value means the label for your keyboard shortcut appears higher in the list. A value of 200 means that the item will almost certainly be placed at the bottom of the list.

The description contains an attribute key. This is the internationalisation key contained in a properties file (explained later in the tutorial). The value of this element defines the label for the keyboard shortcut in this dialog box.

Controlling how the keyboard shortcut is triggered

This line defines how the keyboard shortcut is triggered:  

keyboard.shortcut.four.oh.four = Page Not Found

keyboard.shortcut.four.oh.four.desc = Display 404 page:

<resource type="i18n" name="i18n" location="confluence-tutorial-keyboard-shortcuts"  />

http://localhost:1990/confluence/

AJS.toInit(function($) {

    AJS.I18n.get("com.appfusions.confluence.plugins.confluence-tutorial-keyboard-shortcuts");

});

<web-resource key="keyboard.shortcut.CONF-24450-workaround" name="Keyboard Shortcuts" i18n-name-key="keyboard.shortcut.CONF-24450-workaround">

  <resource name="CONF-24450-workaround.js" type="download" location="js/CONF-24450-workaround.js"/>

  <context>main</context>

  <context>admin</context>

</web-resource>

<keyboard-shortcut key="moveToAndClick.toggle.browse" i18n-name-key="keyboard.shortcut.toggle.browse" name="Toggle Browse Menu">

  <order>200</order>

  <description key="keyboard.shortcut.toggle.browse.desc">Toggle Browse Menu</description>

  <shortcut>[Ctrl+B]</shortcut>

  <operation type="moveToAndClick">#browse-menu-link</operation>

  <context>global</context>

</keyboard-shortcut>