Routes

Scooter's routes map incoming HTTP requests to controller actions.

For example, for the following HTTP request example,

GET /posts/10

Scooter's routing would redirect it to PostsController's show action method to handle the request.

Route config file

Routes are specified in config/routes.properties file. You can list as many routes as you want in it.

Route matching

It is possible that more than one route matches an incoming HTTP request. Exactly which route is selected depends on the route's priority.

A route's priority is determined by the order it is declared in the config/routes.properties file. Scooter's route matching component selects the first matching route.

If no route is found, a NoRouteFoundException exception is thrown.

Route types

Scooter supports five major routes types.

  1. Named route
  2. Root route
  3. Regular route
  4. Default route
  5. RESTful route

Named route

Named route maps a non-dynamic url to an action. You can declare it as follows:

routes.name.login=url:/login; controller:home; action:login

Here we declare a named route which would match HTTP requests with url /login to HomeController's login aciton method.

A named route must have a unique name, a url, a controller and an action.

Root route

Root route specifies which controller action handles a root level access. A root access url is usually of type /index or simply /.

You may either define a root route or link it to an existing named route.

# define a root route
routes.root=url:index; controller:blog; action:main
#
# link a root route to a named route called "index"
routes.root:index

Regular route

Unlike named routes, regular routes allow you to specify dynamic parameters in a url pattern.

Dynamic parameter is prefixed by symbol $. In the example below, we define a regular route named showpost. Any request such as /entry/1 or /entry/1001 is going to be handled by PostsController's show action.

routes.regular.showpost=url:entry/$id; controller:posts; action:show

A regular route must have a unique name, a url, a controller and an action.

Default route

Default routes are selected only when no other routes are found for a HTTP request.

Default routes should be listed at the end of the routes.properties file. Scooter by default has already listed default routes in the file.

Only three default routes are supported:

routes.default.0=url:$controller/$action
#
routes.default.1=url:$controller/$action/$id
#
routes.default.2=url:$controller/$action/$id.$format

The above default routes can handle requests such as:

  • /posts/list
  • /posts/show/1001
  • /posts/show/1001.xml

In the last default route, a response format is specified. In our example, the response is of "xml" format.

To prevent a request such as /posts/10 to match a default route, you can specify requirements. The following example indicates that only character values are allowed in controller and action parameters.

routes.default.0=url:$controller/$action; requirements: {controller => /\\D+/, action => /\\D+/}

RESTful route

RESTful route is the default routing type in Scooter. To obtain RESTful routes, you first declare resources:

resources.list=recipes, comments, tags, users, accounts

Scooter framework then creates seven routes for each of the listed resources. See here for more details.

Static contents

Static contents such as stylesheets, javascripts, html documents and images do not need to be handled by a controller. You simply put them under the static directory.

Any HTTP request urls starting with /static/ are going to be handled by the default servlet of web server.

GET /static/...

Displaying routes

You can find all the routes currently supported by your application by clicking on the Routes link on top of your admin page.

The content of that page changes whenever you make changes in routes.properties file.