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
Name | Required | Type | Description |
route | true | string | The Route pattern to be matched by the URL Fragment |
name | true | string | The unique name of the Route |
callback | true | function | The callback function for the Route |
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
Name | Required | Type | Description |
routes | true | array | An array of route definition as defined above. |
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.