# 3.4 Creating custom shortcuts

## Available Actions

| Action              | Default shortcut | What it does                                |
| ------------------- | :--------------: | ------------------------------------------- |
| `toggleSearchPanel` |      `alt-q`     | Opens/closes the Search Panel               |
| `toggleQuickCopy`   |        ---       | Enables/disables Quick Copy mode            |
|                     |                  | **When the Search Panel is visible :**      |
| `closeSearchPanel`  |     `Escape`     | Closes the Search Panel                     |
| `focusSearchBar`    |        ---       | Put the cursor in the search bar            |
|                     |                  | **When viewing the item's metadata :**      |
| `importMetadata`    |        ---       | Import the item's metadata to the Roam grap |
| `toggleNotes`       |                  | Show/hide the notes, if any                 |
| `copyCitekey`       |        ---       | Copy the item's citekey                     |
| `copyCitation`      |        ---       | Copy the item's citation (Roam alias)       |
| `copyPageRef`       |        ---       | Copy the item's citekey as page reference   |
| `copyTag`           |        ---       | Copy the item's citekey as tag              |

## How to setup custom shortcuts

Shortcut objects must list the sequence of keys involved, and refer to them **by their name in lowercase** (if you know JavaScript, that would be the `event.key` value). The only exception is the four special keys (Alt, Ctrl, Meta, Shift) which must be named `altKey`, `ctrlKey`, `metaKey`, and `shiftKey` respectively.

For example, the shortcut sequence `alt-p` would be described by the following object :

```javascript
{'altKey': true, 'p': true}
```

Shortcut objects are assigned to a specific action, inside the `shortcuts` property in `zoteroRoam_settings` :

```javascript
// Note: you should add settings *within* the zoteroRoam_settings object
// that contains your dataRequests -- do not declare it again


// Here we're assigning our alt-p shortcut to the toggleSearchPanel action :

zoteroRoam_settings = {
    // Your dataRequests object should be here :
    dataRequests: {
        apikey: 'XXXXXXXXXXXXXXXX',
        dataURI: 'users/1234567/items',
        params: 'limit=100'
    },
    shortcuts: {
        'toggleSearchPanel': {'altKey': true, 'p': true}
    }
}
```

```javascript
// Note that multiple shortcuts can be assigned to a given action.
// This is done by providing an Array of shortcut objects.
// For example, we can assign both alt-p and alt-q to toggle the Search Panel :

zoteroRoam_settings = {
    // Your dataRequests object should be here :
    dataRequests: {
        apikey: 'XXXXXXXXXXXXXXXX',
        dataURI: 'users/1234567/items',
        params: 'limit=100'
    },
    shortcuts: {
        'toggleSearchPanel': [{'altKey': true, 'p': true},
                                {'altKey': true, 'q': true}]
    }
}
```

The tricky part in creating shortcuts is that **there is no universal list of key names** - they're dependent on your keyboard hardware, your OS (Windows/Mac/Linux...), and also your browser. This can lead to some unexpected behaviors - especially on Mac, and with international keyboards. 

To help make testing easier, I created a small tool that lets you press a combination of keys & returns the corresponding shortcut object. It's not perfect, but hopefully it helps you set up shortcuts that work with your computer and software. You can use it here :

{% embed url="<https://codepen.io/alix-yl/pen/vYyQMWB>" %}
Let me know if you're having bugs/issues with this ! Keyboard mappings are pretty complicated
{% endembed %}