URI Routing

Typically there is a one-to-one relationship between a URL string and its corresponding controller/handler. The segments in a URI normally follow this pattern:

example.com/controller/handler/id/

In some instances, however, you may want to remap this relationship so that a different controller/handler can be called instead of the one corresponding to the URL.

For example, lets say you want your URLs to have this prototype:

example.com/product/1/
example.com/product/2/
example.com/product/3/
example.com/product/4/

Normally the second segment of the URL is reserved for the handler name, but in the example above it instead has a product ID. To overcome this, revIgniter allows you to remap the URI handler.

Setting your own routing rules

Routing rules are defined in your application/config/routes.lc file. In it you'll see an array called gRoute that permits you to specify your own routing criteria. Routes can either be specified using wildcards or Regular Expressions

Wildcards

A typical wildcard route might look something like this:

put "catalog/productLookup" into gRoute[2]["product/:num"]

In a route, the array key contains the URI to be matched, while the array value contains the destination it should be re-routed to. In the above example, if the literal word "product" is found in the first segment of the URL, and a number is found in the second segment, the "catalog" controller and the "productLookup" handler are instead used.

You can match literal values or you can use two wildcard types:

:num
:any

:num will match a segment containing only numbers.
:any will match a segment containing any character.

Note: The gRoute array must be numbered and the key number for reserved routes must be 1. So, the keys of your custom routes must start with 2 as in the example above. Routes will run in the order of the keys of the gRoutes array. Routes with lower key numbers will always take precedence over those with higher ones.

Examples

Here are a few routing examples:

put "blogs" into gRoute[2]["journals"]

A URL containing the word "journals" in the first segment will be remapped to the "blogs" controller.

put "blogs/users/34" into gRoute[3]["blog/joe"]

A URL containing the segments "blog/joe" will be remapped to the "blogs" controller and the "users" handler. The ID will be set to "34".

put "catalog/productLookup" into gRoute[4]["product/:any"]

A URL with "product" as the first segment, and anything in the second will be remapped to the "catalog" controller and the "productLookup" handler.

put "catalog/productLookupByID/$1" into gRoute[5]["product/(:num)"]

A URL with "product" as the first segment, and a number in the second will be remapped to the "catalog" controller and the "productLookupByID" handler passing in the match as a variable to the handler.

Important: Do not use leading/trailing slashes.

Regular Expressions

If you prefer you can use regular expressions to define your routing rules. Any valid regular expression is allowed, as are back-references up to 10 ($1 - $10).

Note:  If you use back-references you must use the dollar syntax.

A typical RegEx route might look something like this:

put "$1/id_$2" into gRoute[2]["products/([a-z]+)/(\d+)"]

In the above example, a URI similar to products/shirts/123 would instead call the shirts controller and the id_123 handler.

You can also mix and match wildcards with regular expressions.

 

Reserved Routes

There are three reserved routes:

put "welcome" into gRoute[1]["defaultController"]

This route indicates which controller should be loaded if the URI contains no data, which will be the case when people load your root URL. In the above example, the "welcome" controller would be loaded. You are encouraged to always have a default route otherwise a 404 page will appear by default.

put "errors/pageMissing" into gRoute[1]["404Override"]

This route indicates which controller should be loaded if the requested controller is not found. It will override the default 404 error page. It won't affect to the rigShow404 handler, which will continue loading the default error404.lc file at application/errors/error404.lc. This way you can write your own 404 error controller. But there are two things you should keep in mind:

Important:  Do not name any handler in your error controller "index". Place your error controller in application/controllers, do not place it in any subfolder of application/controllers.

put "scaffolding" into gRoute[1]["scaffoldingTrigger"]

This route lets you set a secret word, which when present in the URL, triggers the Scaffolding feature. Please read the Scaffolding page for details.

Important:  The gRoute array must be numbered and the key number for reserved routes must be 1 as shown above.