Routing
Routing is the process of mapping a URL pattern to a controller method. When that URL pattern is accessed, the request will execute its corresponding controller.
Routes are defined inside the
getRoutes() method of a module's configuration file, identified by {moduleName}Config.php. The method returns an array of Route objects. Specialized route objects, which extend the Route object may also be included in the list.<?php
class UserConfig extends moduleConfig {
/**
* Defines all of the routes relevant to the User module.
*
* @return route[]
*/
public static function getRoutes() {
return array(
new route(array(
'id' => 'user_list',
'name' => 'Our Users',
'route' => '/users/list',
'controller' => '[email protected]',
'method' => 'GET',
'priority' => route::PRIORITY_HIGH,
'protected' => false
))
);
}
}
Basic routes are defined by the
sa\application\route object. These are strictly used for application-facing routing. In other words, this route type is not acceptable for static assets (CSS, JS, Img) or administrative pages.Field | Required | Type | Description |
id | required | string | An identifier that is unique to this route. The naming convention for route Ids is {moduleName}_{action}. The Id should only contain lowercase alphabetic characters with underscores delimiting each word. |
name | required | string | A user friendly name for the route. This is generally used for the page heading, if applicable. |
route | required | string | The URL pattern that is mapped to the controller. There are two ways to define a route pattern. 1. A static URL, such as /users/list 2. A regular expression to capture dynamic URLS (/users/edit/1). |
controller | required | string | The controller method to be executed when the route is accessed. The controller and method are delimited by a '@'. For example: [email protected], where the controller is UsersController and the method to be executed is editUser. |
method | optional | string | The HTTP verb that is allowed to access this route. Valid values are GET and POST. If not specified, the route will except all HTTP verbs. |
priority | optional | constant | If a route with the same name is already defined, you can give your route a higher priority so it will execute instead of the other duplicate route.Valid values: route::PRIORITY_EXTREMLY_HIGH,route::PRIORITY_HIGH, route::RIORITY_ABOVENORMAL, route::PRIORITY_NORMAL, route::PRIORITY_BELOWNORMAL, route::PRIORITY_LOW |
protected | optional | boolean | If true, the route will require users to be logged in to access it. If not specified, the default value is false. |
Siteadmin routes are defined by the
sa\application\saRoute object, which extends the basic route and accepts the same constructor parameters. These routes may only be accessed by users who are logged in as a Siteadmin user. The naming convention of siteadmin routes is similar to the convention for basic routes, with the addition of a sa_ prefix at the beginning of the route id field.<?php
new saRoute(array(
'id' => 'sa_user_list',
'name' => 'Our Users',
'route' => '/users/list',
'controller' => '[email protected]',
'method' => 'GET',
'priority' => route::PRIORITY_HIGH
));
Resource routes respond to requests for CSS, JS, and image assets.
<?php
new resourceRoute(array(
'id'=>'user_css',
'name'=>'css',
'route'=>'^/user/css/[a-zA-Z0-9-_\.]{1,}$',
'controller'=>'[email protected]'
));
Some routes may require dynamic parameters, such as ID's or page titles. The routing system uses regular expressions to restrict the data type and format of theses route parameters.
^/user/[0-9]$
^/user/[0-9]{9,9}$
^/pages/[a-z0-9-_]$
^/user/[0-9]/invoices/[0-9]$
It's worth noting that optional parameters are not supported. The following routes are not valid.
^/user/[0-9]{0,}$
^/user/[0-9]?$
While the URL utility is useful for parsing and building URLs, sometimes it is necessary to access the raw
route object. The global app context provides a helper function to achieve this.Consider the following route...
new route(array(
'id' => 'user_list',
'name' => 'Our Users',
'route' => '/users/list',
'controller' => '[email protected]',
'method' => 'GET',
'priority' => route::PRIORITY_HIGH,
'protected' => false
))
You can retrieve this object by referencing its ID with the line below.
app::get()->findRouteById('user_list')
Last modified 4yr ago