W20 provides a declarative syntax to register AngularJS routes in your application. It is done through the routes section of fragment manifests:

"routes": {
    "/route1": {
        ...
    },
    "/route2": {
        ...
    }
}

The application module will process the routes section of all fragments and register the valid routes in the AngularJS routing system. The two components of a W20 route definition are:

• The route paths which are specified by the keys of the routes object. To ensure route uniqueness in an application, the fragment identifier is used as a route path prefix. For example, if the fragment identifier is fragment1 the full route path registered in AngularJS routing for /route1 is /fragment1/route1.
• The route definitions which are specified as an object for each route path. Every options of the AngularJS route object can be configured, the most common one being the templateUrl and the controller associated to the view.

 "routes": {
     "/route1": {
       "templateUrl": "{fragment-id}/views/route1Template.html",
       "controller": "route1Controller"
     }
 }

Route types

A route definition should contain a type attribute. If it is not present, a route type of view is assumed which is a standard AngularJS route. Two route types are available out-of-the-box:

• A view route is a standard AngularJS route, which is minimally processed by W20. If it contains a templateUrl, its value is resolved into a full URL by the RequireJS function toUrl(). As such, every fragment alias (like {fragment1}) is resolved.
• A sandbox route type is a W20-specific route type which encapsulate the page denoted by the url attribute into an iframe. It is useful to add any pre-existing HTML pages into a W20 application such as legacy application screens. The url attribute is resolved into a full URL by the RequireJS function toUrl().

Any custom route type can be registered by using the registerRouteHandler() function of the application module public definition:

define([
    '{w20-core}/modules/application'
], function(application) {
    ...

    application.registerRouteHandler('myCustomType', function (route) {
        // analyze and transform the route object here        

        return route;
    });

    ...
});

The handler will be invoked for each detected route of type myCustomType. It is required that the returned route object is a valid AngularJS route definition.

Hidden routes

You can hide a route from the menu by setting the hidden attribute to true in the route definition object:

 "routes": {
     "/route1": {
         "hidden": true
     }
 }

Categorizing routes

The category attribute can be used to define a category for the route which will often be rendered as a section or folder in graphical themes. The category name supports hierarchical categories separated with dots:

 "routes": {
     "/route1": {
         "category": "a.b.c"
     }
 }

This will put the route1 route in the c sub-category of b which is itself a sub-category of category a. The special category name __top define the route as a top-level route (without category). It is the default value of this attribute.

Additional route metadata

Additional attributes can be attached to route definition and will be ignored by AngularJS. When retrieving the route through the AngularJS $route service, these attributes will be preserved, allow for further processing during the execution of the application.

W20 route metadata

W20 adds a limited set of attributes on all routes:

• type: the type attribute is automatically added if not present (with the view value),
• path: the full path of the route,
• category: the category of the route (which can be used to classify the routes for navigation) is added with a default value of __top.
• i18n: the i18n key for the route name is added with a default value of application.view.normalized.route.path. Path normalization consists of replacing slashes with dots. As such, the /fragment1/route1 fragments will have a default i18n key of application.view.fragment1.route1.
• resolve: a resolve object will be added to check for route security and for any additional custom check defined by the check attribute on the route definition (which must reference by name a custom check function registered with AngularJS injector through a module.value('myCheck', function checkFn() { ... }); and returning a promise). The routing is suspended until the promise is resolved (or rejected).

Custom metadata

Any additional metadata can be added to the route for custom purposes, but be aware to not interfere with W20 route metadata as any custom attribute of the same name will be overwritten before any custom route handler is called.