Keyboard Shortcut Module

Available:

Confluence 3.4 and later

Purpose of this Module Type

A Keyboard Shortcut plugin module defines a keyboard shortcut within Confluence. A Confluence keyboard shortcut allows you to perform potentially any action in Confluence using one or more keyboard strokes – for example, going to the dashboard, editing a page, adding a comment, formatting text while using the editor, and so on.

Configuration

The root element for the Keyboard Shortcut plugin module is keyboard-shortcut. It allows the following attributes and child elements for configuration:

Attributes

Name

Required

Description

Default

key

(tick)

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.

<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>

In the example, appProps is the key for this particular module declaration, for component-import, in this case.

N/A

i18n-name-key

The localisation key for the human-readable name of the plugin module.

name

The human-readable name of the plugin module.

The plugin key.

hidden

When hidden='true', the keyboard shortcut will not appear in the Keyboard Shortcuts dialog box.
(info) Despite not appearing in the dialog box, hidden keyboard shortcuts can still be accessed via the relevant keystrokes.

false

There is a known issue with the i18n-name-key. Please see CONF-24450.

Elements

Name

Required

Description

order

(tick)

A value that determines the order in which the shortcut appears on the Keyboard Shortcuts dialog box, with respect to other keyboard-shortcut plugin modules. This element is also used to override existing shortcuts displayed on the Keyboard Shortcuts dialog box (see below).
(info) For each keyboard-shortcut plugin module, we recommend using gaps in order values (for example, 10, 20, 30, etc.) rather than consecutive values. This will allow you to insert new keyboard shortcuts more easily into the keyboard shortcuts dialog box.

description

(tick)

A human-readable description of this Keyboard Shortcut module.
(info) Please see CONF-24450 if you are having problems with internationalisation.

shortcut

(tick)

The sequence of keystrokes required to activate the keyboard shortcut. These should be presented in the order that the keys are pressed on a keyboard. For example, gb represents a keyboard shortcut activated by pressing 'g' then 'b' on the keyboard.

operation

(tick)

A jQuery selector that specifies the target of the keyboard shortcut. The target is typically a component of the current page that performs an action. The operation element is accompanied by a type attribute that specifies the type of keyboard shortcut operation. Available types are:

  • click
    Clicks an element identified by a jQuery selector
  • execute
    Executes a JavaScript function specified by the operation parameter
  • followLink
    Sets the window.location to the href value of the link specified by the jQuery selector.
  • goTo
    Changes the window.location to go to a specified location
  • moveToAndClick
    Scrolls the window to an element and clicks that element using a jQuery selector
  • moveToAndFocus
    Scrolls the window to a specific element and focuses that element using a jQuery selector
  • moveToNextItem
    Scrolls to and adds focused class to the next item in the jQuery collection
  • moveToPrevItem
    Scrolls to and adds focused class to the previous item in the jQuery collection

context

(tick)

The context defines which pages the shortcut will be active on.

  • If this element contains global the keyboard shortcut will be active on all Confluence pages. The shortcut will also appear in the 'Global Shortcuts' sub-section of the Keyboard Shortcuts dialog box under the 'General' tab.
  • If this element contains viewcontent the keyboard shortcut will be active when viewing a page or blog post. The shortcut will also appear in the 'Page / Blog Post Actions' sub-section of the Keyboard Shortcuts dialog box under the 'General' tab.
  • If this element contains viewinfo the keyboard shortcut will be active when viewing the info for a page. The shortcut will also appear in the 'Page / Blog Post Actions' sub-section of the Keyboard Shortcuts dialog box under the 'General' tab.

Overriding Existing Keyboard Shortcuts

You can override an existing keyboard shortcut defined either within Confluence itself or in another plugin.

To do this create a keyboard-shortcut plugin module with exactly the same shortcut element's keystroke sequence as that of the keyboard shortcut you want to override. Then, ensure that an order element is added, whose value is greater than that defined in the keyboard shortcut being overridden.

(info) The order element will affect the position of your overriding keyboard shortcut on the Keyboard Shortcuts dialog box. It will also prevent the overridden keyboard shortcut from being accessed via the keyboard.

Internationalisation

You may need to push your i18n resource to the front end for the shortcut description to be displayed correctly. See CONF-24450 for instructions on how to do this.

Examples

These examples are taken from Confluence's pre-defined keyboard shortcuts:

...
    <keyboard-shortcut key="goto.space" i18n-name="admin.keyboard.shortcut.goto.space.name" name="Browse Space">
        <order>20</order>
        <description key="admin.keyboard.shortcut.goto.space.desc">Browse Space</description>
        <shortcut>gs</shortcut>
        <operation type="followLink">#space-pages-link</operation>
        <context>global</context>
    </keyboard-shortcut>
...

...
    <keyboard-shortcut key="managewatchers" i18n-name="admin.keyboard.shortcut.managewatchers.name" name="Manage Watchers">
        <order>60</order>
        <description key="admin.keyboard.shortcut.managewatchers.desc">Manage Watchers</description>
        <shortcut>w</shortcut>
        <operation type="click">#manage-watchers-menu-item</operation>
        <context>viewcontent</context>
    </keyboard-shortcut>
...

...
    <keyboard-shortcut key="quicksearch" i18n-name="admin.keyboard.shortcut.quicksearch.name" name="Quick Search">
        <order>40</order>
        <description key="admin.keyboard.shortcut.quicksearch.desc">Quick Search</description>
        <shortcut>/</shortcut>
        <operation type="moveToAndFocus">#quick-search-query</operation>
        <context>global</context>
    </keyboard-shortcut>
...
RELATED TOPICS

Writing Confluence Plugins
Installing a Plugin

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport