the singularity of being and nothingness
ExtJS 4: Adding an App-wide Keystroke Mapping
In a previous post, I showed how it’s pretty simply to catch keystrokes in your controller, and then do cool stuff in your app. But what if you want to add an app-wide keystroke mapping? For example, consider you’re create something like Sencha’s desktop demo. Within such an interface, it might be nice to map keystrokes to functionality within your app (like initiating a search, closing a window, etc.).
So here’s an easy way to do that.
In this example, I’m creating an app-wide keystroke mapping for search functionality. When a user enters the keystroke of the letter “S” and the Ctrl key, I want to give focus to a search box that exists within the app.
First of all, here’s the app.js for my application:
Ext.application({ name: "MyApp", appFolder: "app", autoCreateViewport:true, controllers: ["Search"....], launch: function() { var map = new Ext.util.KeyMap(Ext.getBody(), { key: 83, ctrl: true, handler: function() { this.getController("Search").activatesearch(); }, scope: this, defaultEventAction: "stopEvent" }); } });
Ok, so let’s go through this a bit.
First, I create a new instance of Ext.util.KeyMap. I specified two of the three available parameters. The first (in this case, Ext.getBody()) is the element to which this keystroke should be mapped. Since I want this to be an app-wide keystroke, I’m using Ext.getBody(). This will ensure that wherever I use this keystroke combination, the event will be captured and managed by my controller.
The second argument is the “binding”–this is an object in which you defined precisely what keystroke you want to capture in this mapping. There are lots of options available, so be sure to check out the docs. In this example, I’m simply mapping to a keystroke combination of the letter “S” and the “Ctrl” key. And in the handler, I simply pass off the event to my controller.
NOTE: To use “S”, I had to specify that actual numerical assignment for that key. The docs seem to indicate that the letter “S” will work, but I could not get it to function correctly.
Now the REALLY important part here is the usage of “defaultEventAction.” For the sake of learning, try implementing this key mapping, but leave off the defaultEventAction. You’ll find that while your event will indeed fire on the correct keystroke, any other browser-default actions will fire as well. So for “Ctrl + S”, most browsers will open up a dialog box to save the page. Obviously not what we want.
So by using “stopEvent” for defaultEventAction, we tell ExtJS to fire our desired event, and then to prevent the script from continuing to fire its normal progression of events.
Wrapping Up
A word of caution. Before you start going crazy with implementing key mappings in your apps, be sure to carefully consider which browser-default events you might be overriding, and whether or not this is the best thing for your app (and your site visitors!). For example, I chose to use “Ctrl + S” for search INSTEAD OF “Ctrl + F” because I still wanted the browser-default search to be able to work. So I concluded that preventing a save page event in my app was worth preventing in order to have an app-wide key mapping. This may be worthwhile in your app, but might create unforeseen problems as well. Just be thoughtful about what you’re doing, and carefully weigh the advantages of having custom key mappings over and against normal user expectations of their browser’s default actions.
Print article | This entry was posted by existdissolve on August 16, 2011 at 2:34 am, and is filed under ExtJS. Follow any responses to this post through RSS 2.0. You can leave a response or trackback from your own site. |