How to Use Routing in Your Ext JS 5 Apps

Introduction

Ext JS 5 is a major release that offers many new features to create rich, enterprise grade web applications. MVVM and two-way data binding do a lot of the heavy lifting for developers. Another new feature in Ext JS 5 is Routing, which makes history support easy to manage within a controller. The forward and back buttons are common parts of the user interface on every browser – and handling this navigation within a single page application is now very simple with Ext JS 5.

Ext JS 5 Routing

Ext JS has always allowed you to handle history changes using the Ext.util.History class, but in Ext JS 5 we made the process much easier and more flexible. The router provides an easy configuration to map hash tokens to controller methods, with parameters and before actions to control the flow of route execution, and uses Ext.util.History behind the scenes. Let’s look at a simple example:

        Ext.define('MyApp.controller.Main', {
                extend : 'Ext.app.Controller',

                routes : {
                        'home' : 'onHome'
                },

                onHome : function() {}
        });

In the routes object, the key (‘home‘) is the hash to match, and the value (‘onHome‘) is the method on the controller to execute when the hash is matched (for example: http://localhost#home). To change a hash within a controller, you can use the redirectTo method:

        this.redirectTo(‘home’); //redirects to http://localhost#home

This will change the URL hash to #home which will then execute the onHome method scoped to the MyApp.controller.Main controller instance that configured the route. If you have multiple controllers that match the same hash token, the order of execution will be the order defined in the Application instance in the controllers array.

Hash Tokens and Parameters

A hash token can also contain parameters, and the router makes it simple to handle by passing them to the controller method as arguments. A hash with parameters may look like ‘#user/1234’ where 1234 is the user ID and should be treated as a parameter. A controller can be configured to listen to the hash in this way:

        Ext.define(‘MyApp.controller.Main', {
                extend : 'Ext.app.Controller',
        
                routes : {
                        'user/:id' : 'onUser'
                },
        
                onUser : function(id) {}
        });

When you configure a route to expect a parameter, you should use a colon followed by the name of the parameter, in this case :id is the parameter. The router will match any value passed as the parameter and then will pass this parameter to the onUser method. The order of arguments passed to the controller method is the same order that is defined in the configured route.

You can also control the matching of hash parameters based on a regular expression. In the user ID example, the ID can only be digits and any other value should not be matched. In order to control this matching, the route needs to use the conditions config:

        Ext.define('Fiddle.controller.Main', {
                extend : 'Ext.app.Controller',

                routes : {
                        'user/:id' : {
                                action     : 'onUser',
                                conditions : {
                                        ':id' : '([0-9]+)'
                                }
                        }
                },

                onUser : function(id) {}
        });

This example introduces two things: the route can be an object where the action key is the controller method and the conditions config is used. The conditions config is an object of parameters and regular expression strings. The reason it’s a regular expression string and not an actual regular expression is the router creates a master regular expression based on the parameters within the route and the conditions config allows you to override the default matching regular expression string that is used. The default regular expression string for parameters is ‘([%a-zA-Z0-9-_s,]+)’.

If no route is configured to match a hash that occurs, an unmatchedroute event will be fired on the application. This event can be listened for on the application or a controller, each in the same way. Here is an example of listening in a controller:

        Ext.define('Fiddle.controller.Main', {
                extend : 'Ext.app.Controller',

                listen : {
                        controller : {
                                '*' : {
                                        unmatchedroute : 'onUnmatchedRoute'
                                }
                        }
                },

                onUnmatchedRoute : function(hash) {}
        });

There may be times when you need to hook into the route execution process to prevent a route from continuing to execute or delay the execution for some asynchronous action like an ajax request. In order to do this, a route can be configured with a before action and also passed any parameters configured in the route. Here is an example of using an ajax request and continuing the route after the request has finished:

        Ext.define('Fiddle.controller.Main', {
                extend : 'Ext.app.Controller',

                routes : {
                        'user/:id' : {
                                action     : 'onUser',
                                before     : 'beforeUser',
                                conditions : {
                                        ':id' : '([0-9]+)'
                                }
                        }
                },

                beforeUser : function(id, action) {
                        Ext.Ajax.request({
                                url     : '/user/confirm',
                                params  : {
                                        userid : id
                                },
                                success : function() {
                                        action.resume();
                                },
                                failure : function() {
                                        action.stop();
                                }
                        });
                },

                onUser : function(id) {}
        });

The beforeUser method receives the id parameter like in the onUser method, but it also gets an action argument. The action argument has a resume and stop method that controls the route’s execution. Executing action.resume(); like in the success handler of the Ext.Ajax.request will resume the route’s execution; this is what allows the route to be asynchronous. Executing the action.stop(); method, as seen in the failure callback, will stop the current route from executing. If true is passed to the stop method, all queued routes will stop executing, allowing you to have complete control over the routes.

Ext JS applications can become large and complex, and they may require multiple hash tokens to be active at the same time. Ext JS 5 has the ability to handle multiple hash tokens and execute them separately from each other; the separate tokens will be sandboxed. This means that if you cancel one route by passing true to the action.stop method, it will only prevent the other routes for that hash token; the other hash tokens will continue to execute. Each token needs to be pipe delimited. An example hash would look like this:

        #user/1234|message/5ga

The router will split this hash and have the ‘user/1234‘ and ‘message/5ga‘ tokens. The router will start with the user token and find all routes that match that token and execute any matched routes. If no routes match the token, the unmatchedroute event will be fired. The router will then move onto the message token and find all routes and execute them. If no routes match the token, the unmatchedroute event will be fired.

Conclusion

The new router in Ext JS 5 allows you to handle the browser history stack as simply as a configuration, yet it’s still flexible and powerful to meet complex application needs. Together with the MVC+VM, two-way data binding and the other new features, Ext JS 5 is the perfect framework for enterprise grade applications.