Keyboard Shortcut Module

Purpose of this Module Type

A Keyboard Shortcut plugin module defines a keyboard shortcut within Bitbucket Server. A Bitbucket Server keyboard shortcut allows you to perform potentially any action in Bitbucket Server using one or more keyboard strokes – for example, navigating to a repository, viewing commits or browsing files.

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 The identifier of the plugin module. This key must be unique within the plugin where it is defined.

Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the complete module key. A module with key fred in a plugin with key com.example.modules will have a complete key of com.example.modules:fred.

N/A
i18n-name 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.

Despite not appearing in the dialog box, hidden keyboard shortcuts can still be accessed via the relevant keystrokes.

false

Elements

Name Required Description
order 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.

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 A human-readable description of this Keyboard Shortcut module.
shortcut 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 Defines the action to take when this shortcut is activated. The available actions come from AJS.whenIType. The action is specified through the `type` attribute of the operation element. The text content of this element is used as a parameter to the AJS.whenIType function being called. Usually the parameter is a jQuery selector that specifies the target of the keyboard shortcut. Some actions take an optional second parameter. If you require specifying multiple parameters, you may use a strict JSON array as the operation element's text content, and this will be used as the `arguments` of the function. Available types are:
  • click
    Clicks an element identified by a jQuery selector
  • execute
    Executes JavaScript in a scoped context (any vars you create will not be available to other code).
  • 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 an element specified by a jQuery selector and focuses that element.
  • moveToNextItem
    Scrolls to and adds a "focused" class to the next item in the jQuery collection
  • moveToPrevItem
    Scrolls to and adds a "focused" class to the previous item in the jQuery collection
context The context defines which pages the shortcut will be active on.
  • If this element contains global the keyboard shortcut will be active on all Bitbucket Server pages. The shortcut will also appear in the 'Global Shortcuts' sub-section of the Keyboard Shortcuts dialog box. Other built-in contexts are branch (for branch/tag specific pages within a repository), commit (when viewing a single commit), commits (when viewing the list of commits), filebrowser (when viewing a directory within a repository), and sourceview (when viewing a single file's source or diff). You may specify your own arbitrary contexts, but you will have to manually enable that context on any page where you'd like your shortcuts to run. Note that the string you use for your custom context will also be used as its header text within the shortcut help dialog. E.g., "my context" will be displayed under the header "My Context" in the dialog.

Examples

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

...
    <keyboard-shortcut key="shortcut-branch-selector" i18n-name="bitbucket.web.keyboardshortcut.branch.selector" name="Open Branch Selector">
        <description key="bitbucket.web.keyboardshortcut.branch.selector.desc">Change branch/tag</description>
        <shortcut>b</shortcut>
        <operation type="click">#repository-layout-revision-selector</operation>
        <context>branch</context>
    </keyboard-shortcut>
...

...
    <keyboard-shortcut key="shortcut-commit-move-to-next-file" i18n-name="bitbucket.web.keyboardshortcut.commit.next.file" name="Commit - Open next file">
        <description key="bitbucket.web.keyboardshortcut.commit.next.file.desc">Next file</description>
        <shortcut>j</shortcut>
        <operation type="evaluate">require('util/shortcuts').setup('requestMoveToNextHandler', this, 'j');</operation>
        <context>commit</context>
    </keyboard-shortcut>
...

Enabling Custom Contexts

Enabling a custom context requires handling of the "register-contexts.keyboardshortcuts" AJS event from JavaScript. In Bitbucket Server, this is also exposed as an event on 'util/events' if you prefer that API.

AJS.bind("register-contexts.keyboardshortcuts", function(e, data) {
    data.shortcutRegistry.enableContext('my context');
});

or

require('util/events').on('stash.widget.keyboard-shortcuts.register-contexts', function(registry) {
    registry.enableContext('my context');
});