Sidecar API Reference

Module: Core/Router

App router. It extends the standard Backbone.js router.

The router manages the watching of the address hash and routes to the correct handler. You need to add your routes with their callback using addRoutes method. To add your routes, you have to listen to the router:init event.

Example:

const Events = require('core/events');
Events.on('router:init', function(router) {
    var routes = [
        {
            route: 'MyModule/my_custom_route',
            name: 'MyModule',
            callback: MyModule
        }
    ];
    SUGAR.App.router.addRoutes(routes);
});

Methods

<inner> addRoutes(routes)

Add routes into the router.

Currently, Backbone stops after the first matching route. Therefore, the order of how custom routes are added is important. In general, the developer should add the more specific route first, so that the intended route gets called.

For example, the route MyRoute/create will call myRouteCreate in the following code snippet:

var routes = [
    {
        name: 'myRouteCreate',
        route: 'MyRoute/create',
        callback: myRouteCreate
    },
    {
        name: 'myRoute',
        route: "MyRoute(/:my_custom_route)",
        callback: myRoute
    }
];

If the order of myRouteCreate and myRoute is reversed, triggering MyRoute/create will call myRoute with :my_custom_route set to create, which may not be intended.

Parameters:
Name Type Description
routes Array

The ordered list of routes.

<inner> buildRoute(moduleOrContext [, id] [, action])

Builds a route.

This is a convenience function. If you need to override this, define a customBuildRoute function on Utils/Utils and return an empty string if you want to fall back to this definition of buildRoute.

Parameters:
Name Type Argument Description
moduleOrContext Core/Context | string

The name of the module or a context object to extract the module from.
id string <optional>

The model's ID.
action string <optional>

Action name.
Returns:

route The built route.

Type
string

<inner> create(module)

Handles the create route.

Parameters:
Name Type Description
module string

Module name.

<inner> get(name)

Retrieves the callback associated with the given route name.

Parameters:
Name Type Description
name string

The route to get the callback function.
Returns:

The callback associated with this route name.

Type
function

<inner> getFragment()

Gets the current Backbone fragment.

Returns:

The current Backbone history fragment.

Type
string

<inner> getPreviousFragment()

Gets the previous Backbone fragment.

Returns:

The previous Backbone fragment.

Type
string

<inner> go(steps)

Navigates the window history.

Parameters:
Name Type Description
steps number

Number of steps to navigate (can be negative).

<inner> goBack()

Navigates to the previous route in history.

<inner> index()

Handles the index route.

Loads home layout for the Home module or list route with default module defined in SUGAR.App.config. For external authentication it will try to load the page visited when auth was triggered.

<inner> init()

Initializes the router.

<inner> initialize( [opts])

Sets custom routes and binds them if available.

Parameters:
Name Type Argument Description
opts Object <optional>

options to initialize the router.

<inner> layout(module, layout)

Handles arbitrary layout for a module that doesn't have a record associated with the layout.

Parameters:
Name Type Description
module string

Module name.
layout string

Layout name.

<inner> list(module)

Handles the list route.

Parameters:
Name Type Description
module string

Module name.

<inner> login()

Routes to the login page.

You have to implement a login layout to use it.

Fires:
  • app:login
  • app:login:success after a successful external login.

<inner> logout(clear)

Logs out the user and routes to the login page.

Parameters:
Name Type Description
clear boolean

Refreshes the page once logout is complete to clear any sensitive data from browser tab memory.
Fires:
  • event:'app:logout:success'

<inner> navigate(fragment [, options])

Updates the URL with the given fragment.

Parameters:
Name Type Argument Description
fragment string

The fragment to navigate to.
options Object <optional>

The options hash.

Properties
Name Type Argument Description
trigger boolean <optional>

true to fire the route callback.
replace boolean <optional>

true to modify the current URL without adding an entry to the window.history object.
Returns:

This router.

Type
Core.Router

<inner> record(module, id [, action] [, layout])

Handles the record route.

Parameters:
Name Type Argument Description
module string

Module name.
id string

Record ID. If id is create, it will load the create view.
action string <optional>

Action name (edit, etc.). Defaults to detail if not specified.
layout string <optional>

The layout to use for this route. Defaults to record if not specified.

<inner> refresh()

Re-triggers the current route. Used to refresh the current layout/page without doing a hard refresh.

<inner> reset()

Resets the router.

Stops Backbone.history and cleans up routes. Then initializes and starts the router again.

<inner> route(route, name [, callback])

Registers a handler for a named route.

This method wraps the handler into Core.Router#_routeHandler method.

Parameters:
Name Type Argument Description
route string

Route expression.
name string

Route name.
callback function <optional>

Route handler. If not supplied, will use the method name that matches the name param.

<inner> start()

Starts Backbone history which in turn starts routing the hashtag.

See Backbone.history documentation for details.

<inner> stop()

Stops Backbone.history.