Adding Confluence keyboard shortcuts

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. To do this, you create a very simple Confluence plugin consisting of the following components:

• Plugin descriptor – to enable the plugin module in Confluence.
• Internationalization properties file – for multi-language support.

A single JAR file contains all the components. Each component is further discussed in the examples later on this page.

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

• Navigate to a different page.
• Scroll the window to an element, and then click that element.

Before you begin

To complete this tutorial, you should work through the Atlassian plugin SDK tutorial first.

Plugin source

We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, you can find the plugin source code on Atlassian Bitbucket. Alternatively, you can  download the source as a ZIP archive. 

To clone the repository, run the following command:

1
2
git clone git@bitbucket.org:atlassian_tutorial/adding-confluence-keyboard-shortcuts.git

Step 1. Create a plugin project

In this step, you'll create a plugin skeleton using atlas- commands. Because you won't need some of the files created in the skeleton, you'll also delete them in this step.

1. Open a Terminal and navigate to your workspace directory.

2. To create a Confluence plugin skeleton, run the following command:

   1
   2
   atlas-create-confluence-plugin
   

3. To identify your plugin, enter the following information.

   group-id	com.example.plugins.tutorial.confluence
   artifact-id	adding-confluence-keyboard-shortcuts
   version	1.0-SNAPSHOT
   package	com.example.plugins.tutorial.confluence

4. Confirm your entries with Y or y.

5. Navigate to the project directory created in the previous step.

   1
   2
   cd adding-confluence-keyboard-shortcuts/
   

6. Delete the test directories.

   Setting up testing for your plugin isn't part of this tutorial. Run the following commands to delete the generated test skeleton:

   1
   2
   rm -rf ./src/test/java
   rm -rf ./src/test/resources/
   

7. Delete the unneeded Java class files.

   1
   2
   rm -rf ./src/main/java/com/example/plugins/tutorial/confluence/*
   

Step 2. Edit the atlassian-plugin.xml file

In this step, you register the plugin module in your plugin descriptor, that is atlassian-plugin.xml file.

1. In atlassian-plugin.xml file, add the following code to your between the <atlassian-plugin>  tags, but below the <plugin-info> tag group.

1
2
<keyboard-shortcut key="about-confluence-page" i18n-name-key="keyboard.shortcut.go.to.about.page">
     <order>200</order>
     <description key="keyboard.shortcut.go.to.about.page.desc"/>
     <shortcut>ga</shortcut>
     <operation type="goTo">/aboutconfluencepage.action</operation>
     <context>global</context>
</keyboard-shortcut>

Let's break down that XML code. In this example we create a keyboard shortcut that navigates to Confluence About page when triggered.

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

The Keyboard Shortcut module

In the previous code sample, this line involves 2 attributes:

1
2
<keyboard-shortcut key="about-confluence-page" i18n-name-key="keyboard.shortcut.go.to.about.page">

1. key="about-confluence-page" sets an internal name for the new item.
2. i18n-name-key="keyboard.shortcut.go.to.about.page" is the internationalization key for the item. It is displayed in the admin section as the name of the module in the plugin.

Controlling where the keyboard shortcut is displayed

Examine these lines of code:

1
2
<order>200</order>
<description key="keyboard.shortcut.go.to.about.page.desc"/>

In Confluence, if you go to the Help menu, and then select Keyboard Shortcuts, you will see a dialog box with list of keyboard shortcuts.

Each item has 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 is almost certainly placed at the bottom of the list.

The description contains an attribute key. This is the internationalization key that you can find 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:  <shortcut>ga</shortcut>

This example is triggered by pressing the keys in this order: "g", and then "a".

Defining what the keyboard shortcut does

This line defines what the keyboard shortcut does: <operation type="goTo">/aboutconfluencepage.action</operation>

In this case, the window.location is changed to a path below the server base URL. So, for a Confluence installation at http://locahost:1990/confluence, this will correspond to http://localhost:1990/confluence/aboutconfluencepage.action Find more descriptions of operation types on Keyboard Shortcut Module page.

Controlling when the keyboard shortcut can be triggered

In this line, we allow the keyboard shortcuts to be triggered globally within Confluence: <context>global</context>.

The context tag also accepts the page or content values for other situations.

Adding new resource files and internationalization

We will want to specify a text label to display in our Confluence keyboard shortcuts. You could just hard-code this information into your atlassian-plugin.xml file. However, by adding it in a new resource file, we can make our plugin compatible with internationalization.

To do so, simply add a following lines into adding-confluence-keyboard-shortcuts.properties file:

1
2
keyboard.shortcut.go.to.about.page = About page keyboard shortcut
keyboard.shortcut.go.to.about.page.desc = Navigate to About page

The first line – keyboard.shortcut.go.to.about.page – describes the module name in Cog wheel > Add-ons.

The second line – keyboard.shortcut.go.to.about.page.desc – is the label for the keyboard shortcut in the Keyboard Shortcut dialog displayed earlier.

SDK automatically generates a reference to the resource file (adding-confluence-keyboard-shortcuts.properties) in our atlassian-plugin.xml file:

1
2
<resource type="i18n" name="i18n" location="adding-confluence-keyboard-shortcuts.properties"  />

To know more about internationalization, see our  Confluence documentation on the topic.

Step 3. Build, install and run the plugin

1. To compile the plugin project, and then launch a local instance of Confluence, run the following command:

   1
   2
   atlas-run
   

2. After Confluence loads, go to the local instance with this URL:

   1
   2
   http://localhost:1990/confluence/
   

3. Log in with username "admin" and password "admin".

4. Type "g", and then "a". Your browser displays the following.

   

5. Go back to Dashboard, and then select Keyboard Shortcuts from the Help menu (or just enter "?"). You'll see your new keyboard shortcut has been added.  

   

Step 4. For extra points

In this step, you add a new keyboard shortcut that triggers the User Menu to be toggled open or closed when you press Alt+U.

1. In your atlassian-plugin.xml file, add a new keyboard-shortcut code block as follows:

   1
   2
   <keyboard-shortcut key="scroll-and-toggle-user-menu" i18n-name-key="keyboard.shortcut.toggle.user.menu">
         <order>200</order>
         <description key="keyboard.shortcut.toggle.user.menu.desc"/>
         <shortcut>[Alt+U]</shortcut>
         <operation type="moveToAndClick">#user-menu-link</operation>
         <context>global</context>
     </keyboard-shortcut>
   

   This is very similar to code block in step 2, except for two key points:

   • The shortcut now triggers when two keys are pressed simultaneously. 
   • The operation type is now moveToAndClick that should be fairly self explanatory.
     • It moves the web browser window so that the User menu is visible.
     • The value #user-menu-link is a CSS selector for the id attribute on the User menu anchor element.

2. To rebuild your plugin, run atlas-package command, and QuickReload automatically reloads your plugin for you.

3. Go to your local Confluence installation and press Alt+U several times. You should see the User drop-down opening and closing.

This example shows how you can quickly add your own keyboard shortcuts to enhance productivity or accessibility.