Adding custom hot keys

Adding custom hot keys, or keyboard shortcuts, increases productivity by helping users to perform common tasks quickly and efficiently. You can also create custom hot keys to focus on important fields or selections and reduce the number of clicks that a user needs to take to perform actions.

1. For the page to which you want to add the custom hot keys, create or locate the buc-page-definitions.json file.

   Update or create the JSON file within the module's src-custom/assets/custom folder. For example, packages/<route>/src-custom/assets/custom/buc-page-definitions.json.

   If no additional customizations are required other than the changes in the JSON file, the JSON file does not need to be associated to any route. Instead, create the JSON file under packages/<app>-root-config/src/assets/custom/buc-page-definitions.json. Doing so can ensure that future Order Hub releases are automatically applied without manually synchronizing your customization code.

   To find the pages that support the addition of hot keys, see the pages that are listed in the following file.

   • buc-app-<module>/packages/<module>-shared/assets/buc-app-<module>/buc-page-definitions.json
2. Define hot keys within the hotkeys object of your page in the buc-page-definitions.json file. Include the following properties.

   Key id

   A unique ID for the hot key. For example, "go-next" or "initiate-save."

   Values(Object) id

   A unique ID. You can reuse the object ID.

   description

   A reference to a translation string that describes the hot key action. For example, "CREATE_ORDER.KEY_BINDINGS.GO_NEXT."

   type

   A string that references the type of action to perform. For example, "click" or "focus." Click simulates clicking the target element and is used for buttons and links. Focus moves the keyboard focus to the target element and is used for input fields.

   elementIdentifier

   A string that represents a CSS query selector to target the element. For example, "[tid='button-id'] button", "input#field\ Name", or "buc-label#contract-field input." Use test IDs, or tid attributes when available for stability. Be specific to avoid targeting multiple elements. Test CSS selectors to help ensure that they target the correct element, and consider dynamic content and make sure that selectors work across different states.

   keybinding

   A string of keys, or keyboard combination to initiate the action delimited by +. For example, "shift+n", "ctrl+s", or "shift+1." Supported modifiers are shift, ctr, alt, and meta. You can use a single key, or include one or more modifiers. Use shift combinations for common actions. When you determine the strings, make sure to avoid conflicts with browser shortcuts and be consistent across similar features.

   keybinding_$(locale)

   An optional string of keys to use when a user is using a specific locale. If this property is not set, the default property is keybinding.

   See the following example.

   {
     "create-contract-order": {
       "name": "create-contract-order",
       "actions": [],
       "tabs": [],
       "hotkeys": {
         "go-next": {
           "id": "go-next",
           "description": "KEY_BINDINGS.GO_NEXT",
           "keybinding": "shift+n",
           "type": "click",
           "elementIdentifier": "[tid='contract-order-create-next'] button"
         },
         "go-previous": {
           "id": "go-previous",
           "description": "KEY_BINDINGS.GO_PREVIOUS",
           "keybinding": "shift+p",
           "type": "click",
           "elementIdentifier": "[tid='contract-order-create-previous'] button"
         },
         "initiate-save": {
           "id": "initiate-save",
           "description": "KEY_BINDINGS.INITIATE_SAVE",
           "keybinding": "shift+s",
           "type": "click",
           "elementIdentifier": "[tid='contract-order-create-save'] button"
         },
         "initiate-confirm": {
           "id": "confirm-contract-order",
           "description": "KEY_BINDINGS.INITIATE_CONFIRM",
           "keybinding": "shift+c",
           "type": "click",
           "elementIdentifier": "[tid='contract-order-create-confirm'] button"
         },
         "focus-first-element": {
           "id": "focus-first-element",
           "description": "KEY_BINDINGS.FOCUS_FIRST_ELEMENT",
           "keybinding": "shift+1",
           "type": "focus",
           "elementIdentifier": "buc-label#contractOrderName input"
         }
       }
     }
   }

3. Add translation keys for the custom hot key within KEY_BINDINGS in the appropriate en.json file.
   Some guidelines for translation.

   • Be descriptive. Clearly explain what the keyboard shortcut does.
   • Use action verbs. Start with verbs such as navigate, save, move, or activate.
   • Be concise. Keep descriptions short but informative.
   • End with a period.

   {
     "CREATE_CONTRACT_ORDER": {
       "COMMON": {
         "ROUTE_CREATE_CONTRACT_ORDER": "Create contract order",
         ...
       },
       "KEY_BINDINGS": {
         "GO_PREVIOUS": "Navigate to the previous page.",
         "GO_NEXT": "Navigate to the next page.",
         "INITIATE_SAVE": "Save changes.",
         "INITIATE_CONFIRM": "Activate/Confirm.",
         "FOCUS_FIRST_ELEMENT": "Move to the name field."
       }
     }
   }