How to create custom Sidecar routes

Have you ever found yourself wishing you could create a custom Sidecar user interface within your Sugar instance? Maybe you want to allow users to visit a URL that displays a custom view.

It turns out that creating a linkable URL (or route) to within the Sugar client is fairly simple. In this post, I'll walk you through how to implement a new route in your Sugar instance that displays an alert.

What is a Route?

Sidecar utilizes the Backbone Router as the method for controlling client-side navigation within the Sugar application. The Router will take the current URL in the browser (the route) and call the appropriate callback function.  The callback could do something like display an alert or load a Sidecar Layout or View.  The Router will pass information included in the route like a module name and a record identifier to the callback function.

Most of the routes are already set up for you. For example, visiting a Sugar instance URL that ends with "#Home" will load the default dashboard layout. Visiting a URL that ends with "#Accounts/<id>" will load the Account record view for the record with the appropriate identifier.

Creating your own route

When you decide to create your own route, the first thing you'll want to do is decide what your custom route should be. In this example, we'll use "helloWorld" as our custom route, meaning that the full URL will be http://yourSugarInstance/#helloWorld.

Next, you need to decide what should happen when someone accesses the route. Let's display an alert message that says, "Hello, fabulous person!"

Now that we know what we want to do, it's time to code!

Create a new file in your Sugar directory:  ./custom/javascript/customRoutes.js:

SUGAR.App.events.on("router:init", function(){
    //Register the route #helloWorld
    SUGAR.App.router.route("helloWorld", "Hello World", function() {
        SUGAR.App.alert.show('message-id', {
            level: 'info',
            messages: 'Hello, fabulous person!',
            autoClose: false
        });
    });
})

This code registers the custom "helloWorld" route during the "router:init" event.  This code could exist in a file with any name at any location.

The next thing we need to do is create a JSGrouping extension that will tell Sugar we have created custom routes.

Create a new file in your Sugar directory: ./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';
    }
}

Before we can try our custom route, we need to run Quick Repair.  Login to Sugar as an administrative user and navigate to Administration > Repair > Quick Repair and Rebuild.

Now we're ready to test.  Navigate to http://yourSugarInstance/#helloWorld.  Unless you missed a step, the alert you created will appear!Note:  you may need to refresh the page once to pull in the updated JavaScript in order for the alert to appear. It's a good idea to disable your browser cache when doing JavaScript development too.

If you want to take things a step further and display an iframe for a custom route as seen in the screenshot below, check out the Canvas IFrame Building Block example.

For more detailed information on creating custom routes including how to designate new route patterns, see the Developer Guide.

  • Comment originally made by Lauren Schaefer.

    Hi Hector,

    Great question!  I based the code sample above on the sample code in the Developer Guide, and I found myself scratching my head a bit as I tried to answer your question.  For future reference, here is the code snippet we are disucssing:

    foreach ($js_groupings as $key => $groupings) {

        foreach  ($groupings as $file => $target) {

        //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';

            }

            break;

        }

    }

    After talking with some people, below is what I learned:

    Each $grouping array will have the same $target for each value in the array. So, you need to unravel the $grouping array to grab one of its values before you know if you have the right grouping or not (which is iterated via the outer loop). Using a “foreach” loop allows you to get the first key and value for the $groupings array in a single line of code, but, since the intent isn’t to actually iterate, we used a break keyword.  We've refactored the code to be a bit more clear.  I'll be updating this blog post and the Developer Guide shortly to use the following code:

    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';

        }

    }

  • Comment originally made by Hector Rios.

    Hi Lauren,

    Nice write-up! Just one thing that I wanted to mention. In the code for the JSGrouping file, should the "break" statement not be placed right after the following line of code

    $js_groupings[$key]['custom/javascript/customRoutes.js'] = 'include/javascript/sugar_grp7.min.js';

    as opposed to being outside of the "IF" statement?

    Thanks