Rate this page:
|Applicable:||This tutorial applies to Confluence 5.9.1 and higher|
|Level of experience:||Beginner|
|Time estimate||It should take you less than 1 hour to complete this tutorial.|
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:
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:
To complete this tutorial, you should work through the Atlassian plugin SDK tutorial first.
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:
git clone firstname.lastname@example.org:atlassian_tutorial/adding-confluence-keyboard-shortcuts.git
In this step, you'll create a plugin skeleton using commands. Because you won't need some of the files created in the skeleton, you'll also delete them in this step.
Open a Terminal and navigate to your workspace directory.
To create a Confluence plugin skeleton, run the following command:
To identify your plugin, enter the following information.
Confirm your entries with or .
Navigate to the project directory created in the previous step.
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:
rm -rf ./src/test/java rm -rf ./src/test/resources/
Delete the unneeded Java class files.
rm -rf ./src/main/java/com/example/plugins/tutorial/confluence/*
In this step, you register the plugin module in your plugin descriptor, that is file.
1 2 3 4 5 6 7
<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.
In the previous code sample, this line involves 2 attributes:
<keyboard-shortcut key="about-confluence-page" i18n-name-key="keyboard.shortcut.go.to.about.page">
Examine these lines of code:
<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 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 . 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.
This line defines how the keyboard shortcut is triggered:
This example is triggered by pressing the keys in this order: "g", and then "a".
This line defines what the keyboard shortcut does:
In this case, the 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.
In this line, we allow the keyboard shortcuts to be triggered globally within Confluence: .
The context tag also accepts the page or content values for other situations.
We will want to specify a text label to display in our Confluence keyboard shortcuts. You could just hard-code this information into your 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 file:
keyboard.shortcut.go.to.about.page = About page keyboard shortcut keyboard.shortcut.go.to.about.page.desc = Navigate to About page
The first line – – describes the module name in Cog wheel > Add-ons.
The second line – – is the label for the keyboard shortcut in the Keyboard Shortcut dialog displayed earlier.
SDK automatically generates a reference to the resource file () in our file:
<resource type="i18n" name="i18n" location="adding-confluence-keyboard-shortcuts.properties" />
To know more about internationalization, see our Confluence documentation on the topic.
To compile the plugin project, and then launch a local instance of Confluence, run the following command:
After Confluence loads, go to the local instance with this URL:
Log in with username "admin" and password "admin".
Type "g", and then "a". Your browser displays the following.
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.
<img src="/server/confluence/images/keyboard-shortcut-with-plugin-installed.png" width="650" />
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.
In your file, add a new code block as follows:
1 2 3 4 5 6 7
<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:
To rebuild your plugin, run command, and QuickReload automatically reloads your plugin for you.
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.
Rate this page: