Routes

Overview

Routes determine where users are directed based on patterns in the URL.

Routes

Routes, defined in ./include/javascript/sugar7.js, are URL patterns signified by a hashtag ("#") in the URL. An example module URL pattern for the Sugar application is http://{site url}/#<module>. This route would direct a user to the list view for a given module. The following sections will outline routes and how they are defined.

Route Definitions

The router accepts route definitions in the following format:

  routes = [
    {
        name: "My First Route",
        route: "pattern/to/match",
        callback: function()
        {
            //handling logic here.
        }
    },
    {
        name: "My Second Route",
        route: "pattern/:variable",
        callback: "<callback name>"
    }
]

A route takes in three properties: the name of the route, the route pattern to match, and the callback to be called when the route is matched. If a default callback is desired, you can specify the callback name as a string.

Route Patterns

Route patterns determine where to direct the user. An example of routing is done when navigating to an account record. When doing this you may notice that your URL is:

http://{site url}/#Accounts/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

A stock route's definition is defined in ./include/javascript/sugar7.js as:

  {
    name: "record",
    route: ":module/:id"
},

Variables in the route pattern are prefixed with a colon such as :variable. The route pattern above contains two variables:

• module
• id

Custom Routes

As of 7.8.x, you can add the routes during the initialization of the Router, so custom routes can be registered in the Sidecar router during both router:init and router:start events. It is recommended to register them in the Initialization event before any routing has occurred. There are two methods in the Sidecar Router, which allow for adding custom routes:

route()

Arguments

Example

The following example registers a custom Route during the router:init event, using the route() method.

./custom/javascript/customRoutes.js

  (function(app){
    app.events.on("router:init", function(){
      //Register the route #test/123
      app.router.route("test/:id", "test123", function() {
          console.log(arguments);
          app.controller.loadView({
              layout: "custom_layout",
              create: true
          });
      });
    })
})(SUGAR.App);

addRoutes()

When you need to add multiple routes, you can define the routes in an array and pass the entire array to the addRoutes() method on the Sidecar Router to ensure they are registered. Please note, the addRoutes() method utilizes the above route() method to register the routes with the Backbone Router. The Backbone router redirects after the first matching route. Due to this, the order in which the routes are listed in the array is important as it will determine which route will be used by the application. It is recommended that the most specific routes be listed first in the array so that they are recognized first, instead of those routes which may contain a variable.

Arguments

Example

The following example registers custom Route during the router:init event, using the addRoutes() method.

The route's JavaScript controller can exist anywhere you'd like. For our purposes, we created it in ./custom/javascript/customRoutes.js. This file will contain your custom route definitions.

./custom/javascript/customRoutes.js

  (function(app){
    app.events.on("router:init", function(){
        var routes = [
    	    {
                route: 'test/doSomething',
                name: 'testDoSomething',
                callback: function(){
             	    alert("Doing something...");
                }
            },
            {
                route: 'test/:id',
                name: 'test123',
                callback: function(){
             	    console.log(arguments);
                    app.controller.loadView({
                        layout: "custom_layout",
                        create: true
                    });
                }
            }
        ];
        app.router.addRoutes(routes);
    })
})(SUGAR.App);

Next, create the JSGrouping extension. This file will allow Sugar to recognize that you've added custom routes. 

./custom/Extension/application/Ext/JSGroupings/myCustomRoutes.php

  <?php

foreach ($js_groupings as $key => $groupings) {
    $target = current(array_values($groupings));

    //if the target grouping is found
    if ($target == 'include/javascript/sugar_grp7.min.js') {
        //append the custom JavaScript file
        $js_groupings[$key]['custom/javascript/customRoutes.js'] = 'include/javascript/sugar_grp7.min.js';
    }
}

Once your files are in place, navigate to Admin > Repairs > Quick Repair & Rebuild. For additional information, please refer to the JSGroupings framework.