Routes

Routes is our homegrown routing system. Any site can use Routes to perform routing by setting a global variable, routes, in its _init.js. This routes object can then be instructed on how URLs in your application should be processed. Here's an example:

core.core.routes();

routes = new Routes();
routes.add( "abc", "index.jxp" );

Now, when accessing the path /abc on your site, the file index.jxp will be run. You can also use regular expressions:

routes.add( /abc(\d)/, "/month/$1" );

This means, if someone accesses the path /abc0, they will be routed to the JXP located at /month/0.jxp. If they visit /abc1, they will be routed to /month/1.jxp, and so on, up to /abc9. (The $1 syntax in the target of the route is the same as the syntax for the JS String.replace method.)

Routes objects can have subroutes:

subsection = new Routes();
subsection.add( "hello", "helloworld.jxp" );
routes.add( "greetings", subsection );

Now, when you visit /greetings/hello, /greetings/helloworld.jxp will be run. The path of the route is used to locate the path of the JXP. If you want to specify a particular JXP in your site, you can use a pathname starting with a slash. This "absolute path" style starts from the root of your site.

If you're just using strings, you can also use attributes of the routes object:

routes.text = "helloworld.jxp"; // equivalent to routes.add( "text", "helloworld.jxp" )

Using Routes enables you to install core-modules very easily. Most core modules installations consist of calling an install() script and then adding the module's routes to your application's routes object. The special case here is the admin site, which handles URLs before routes does, and cannot be overridden.

Routing to functions

routes.add( "foo" , function(){ print "hello world"; } );

Routes.create

Routes.create allows you to create routing that will work when a site is run by itself as well as when it is run within another site. An example will make this more clear:

Given a directory structure like:

supersite/
   |- _init.js
   |- index.jxp
   |- subsite/
         |- _init.js
         |- index2.jxp

subsite might have a really simple routing setup in _init.js, like this:

core.core.routes();

routes = new Routes();
routes.home = "index2";

If you run subsite and navigate to /home your request is routed to subsite/index2.jxp

Now what if you want to be able to run supersite as well, routing requests for /home to index.jxp and requests for /subsite/home to index2.jxp? This is a case that comes up in our samples, see sample-php.

In order to do this, replace the line

routes = new Routes();

with

var routes = Routes.create(local.$);

in your _init.js. Note the use of var. To use Routes.create(), routes must be declared with local scope. You also must give local.$ as an argument. This is so that Routes.create knows its calling path.

Routes.create will check to see if a global with the name routes already exists. If it doesn't it will create a new Routes object and return it. It will also push that object into the global scope as routes. If a global routes already exists, Routes.create will create a new Routes object and return it. It will add that new Routes object as a subroutes on the global routes.

More Information

Routes API documentation