Last updated on Monday, January 23, 2017
Today I’ll show you how to add keyboard shortcuts to your APEX 5.0 application so that pressing a key combination will navigate to a specific page. For example you could have Ctrl+Alt+D bring you to your “dashboard” page from any other page in your app.
You may have noticed that the Page Designer supports a number of keyboard shortcuts. To see a list of shortcuts click on the Help menu or press Alt+Shift+F1.
All the shortcuts are for navigating around or performing some action in the Page Designer. The shortcuts are also shown where appropriate in popup menus such as the Grid Layout Menu.
libraries/apex/actions.js). The name comes from the actions concept in desktop GUI frameworks such as Swing. An action encapsulates UI state as well as behavior. As a concrete example look at the Expand/Restore functionality, which maximizes the area for the Grid Layout. You can access this functionality using the Expand/Restore toolbar icon button, the Grid Layout Menu, or the Alt+F11 key. No matter where this feature is presented or how it is accessed it all comes from a single action object. The action consists of the UI label (in this case dynamic antonyms Expand or Restore), the shortcut key Alt+F11, the state; expanded or not, the icon and the action function that actually collapses or restores the splitters. Whenever the action state is updated the presentation (menus, buttons etc.) are all updated. This is how the state, icon, and labels (tooltip) are kept in sync between the button and the menu.
This is far more complex than what you’ll be implementing today but I wanted to give a little background so you know that there is more going on than a simple keydown event handler.
Enough background, lets get started.
Step 1. Create a new application using the Universal Theme. Click Application Builder menu. Click Create. Click Desktop. Name the application
Keyboard Shortcut Demo.
Click Next. The home page will be the page to navigate to with a keyboard shortcut. Now add another page so we have some other page to navigate from. Click Add Page. Click Blank and then Click Add Page.
Now click Create Application. On the confirmation step click Create Application again.
Step 2. If you run the app now you will see that it uses a left side tree for navigation. This is the default but keyboard shortcuts are integrated with the menu so you must switch to top menu navigation. Click Edit Application Properties. Click User Interface tab. Click the edit desktop icon button. In the navigation menu section Change Position to
Top and List Template to
Top Navigation Menu. Now Template Options appear. Check the
Add Actions option. Click Apply Changes. Now if you run the app you will see that it has a menu bar (it looks more like tabs because we don’t have enough pages to create drop down menus).
apex.debug API to write error, warning, and informational messages to the console. Your apps or plug-ins can do the same. Errors are always written but other messages are not by default. To see warnings or other messages use the same debug YES flag that turns on server debug logging. See the Application Express API Reference documentation for details.
Now if you refresh the application you should see that the warning is gone.
Step 4. Finally it is time to add the keyboard shortcut. Click Shared Components. Under Navigation click Lists. The list that drives the navigation menus is called Desktop Navigation Menu; click on it. We want to add a shortcut to navigate to the home page so edit the Home page. The shortcut is defined using the User Defined list attributes. Here is an APEX 5.0 gem that you may not have heard about. In the past if you wanted to know what user defined attributes did you would have to open up the intended list template and dig around. Now you can just click the List Template Attributes button, select the theme and list template and you get a list of attributes. This is provided that the list template author bothered to give the attributes a description.
Tip for all the list template authors out there: give your attributes a description. You will thank yourself someday.
Click List Templates Attributes. Select Universal Theme. Select Top Navigation Menu. Note that A01 is the ID and A05 is the shortcut key. Close the dialog.
All actions are identified with a unique name or id. So for A01 enter go_home. For A05 enter Ctrl+Alt+D.
A note about key names. The actions facility is picky about the format of the key names. Modifiers such as shift must be given in this order: Ctrl, Alt, Meta, Shift and match those names exactly. The + character separates the modifiers and the key name.
Now go back to page 2 of the app and refresh it to make sure it has all the latest changes. Press Ctrl+Alt+D. You should find yourself on the home page!
No matter how many pages you add, as long as the navigation menu is on that page, you can use the shortcut key.
One word of caution before you go to crazy with this feature. Unfortunately in web browsers many keys are used by the browser itself. Also there are keys that are used by the operating system. And if that isn’t bad enough browser plug-ins may take over some key combinations. You need to try your best to pick keys that are not used by the browsers or operating systems that your users are using. We thought we did a good job picking the keys for Page Designer but then a Ubuntu Linux user pointed out some keys that weren’t available on that system.
I’ll show one more thing that you can do with actions. Recall how in Page Designer there were some actions that could be done using a menu or a button. Once you have defined an action you can invoke it from a button. This is how you turn an ordinary APEX button into an action button.
Step 5. Go to page 2 in the app and click Edit Page 2 in the developer toolbar. Add a static content region to the Content Body and add a button anywhere in that region. Set the Name to GO_HOME and set the Label to Home. To make a button an action button you need to do three things:
js-actionButtonto CSS Classes.
- Add attribute
data-actionwith a value equal to the action id to Custom Attributes. In this case add
- Set Action to
Defined by Dynamic Action. The action isn’t really defined by a dynamic action but you don’t want any of the other choices either. Think of Defined by Dynamic Action as “none of the above”.
Save and run page 2. You now have a button that will bring you to the home page. Note that it doesn’t mater what label you give this button because if the action already has a label (as it does in this case because it is defined by the menu) then the button will have the same label. In the same way a button and menu can share the same icon (make sure the button Icon CSS Classes has at least the icon type such as “fa”).
Here is a demo app that is essentially the same as described here but with icons for both the home page and page 2, keyboard shortcut Ctrl+Alt+2 to go to page 2, and page 2 was added as a sub menu item so you can see that it automatically shows the shortcut key in the menu item label. This shows that top level menu items such as Home never show an icon or shortcut key even if they have them defined but they can still be used by actions.