# 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. ## Where are routes defined? 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 'user_list', 'name' => 'Our Users', 'route' => '/users/list', 'controller' => 'UsersController@index', 'method' => 'GET', 'priority' => route::PRIORITY_HIGH, 'protected' => false )) ); } } ``` ## Basic Route 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. #### Route constructor options | 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: `UsersController@editUser`, 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 Route 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 'sa_user_list', 'name' => 'Our Users', 'route' => '/users/list', 'controller' => 'UsersController@index', 'method' => 'GET', 'priority' => route::PRIORITY_HIGH )); ``` ### Resource Route Resource routes respond to requests for CSS, JS, and image assets. ```php 'user_css', 'name'=>'css', 'route'=>'^/user/css/[a-zA-Z0-9-_\.]{1,}$', 'controller'=>'UserResourceController@css' )); ``` ## URL Parameters & Regular Expressions 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. #### Numeric ID with variable length ``` ^/user/[0-9]$ ``` #### Numeric ID with fixed length ``` ^/user/[0-9]{9,9}$ ``` #### String parameter ``` ^/pages/[a-z0-9-_]$ ``` #### Multiple Parameters ``` ^/user/[0-9]/invoices/[0-9]$ ``` #### Optional Parameters It's worth noting that optional parameters are not supported. The following routes are not valid. ``` ^/user/[0-9]{0,}$ ^/user/[0-9]?$ ``` ### Passing URL Parameters to a Controller View the controller documentation's [Accessing URL Parameters](https://app.gitbook.com/s/-LB7PTje97ARlss-zn8u/developer-guide/the-basics/controllers.md#accessing-url-parameters) section. ### Find route object by ID While the [URL utility](/developer-guide/utilities-and-helpers/url.md) 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... ```php new route(array( 'id' => 'user_list', 'name' => 'Our Users', 'route' => '/users/list', 'controller' => 'UsersController@index', 'method' => 'GET', 'priority' => route::PRIORITY_HIGH, 'protected' => false )) ``` You can retrieve this object by referencing its ID with the line below. ```php app::get()->findRouteById('user_list') ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.siteadministrator.com/developer-guide/the-basics/routing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.