From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/general/routing.rst | 133 ++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 user_guide_src/source/general/routing.rst (limited to 'user_guide_src/source/general/routing.rst') diff --git a/user_guide_src/source/general/routing.rst b/user_guide_src/source/general/routing.rst new file mode 100644 index 000000000..45950fc11 --- /dev/null +++ b/user_guide_src/source/general/routing.rst @@ -0,0 +1,133 @@ +########### +URI Routing +########### + +Typically there is a one-to-one relationship between a URL string and +its corresponding controller class/method. The segments in a URI +normally follow this pattern:: + + example.com/class/function/id/ + +In some instances, however, you may want to remap this relationship so +that a different class/function 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 function +name, but in the example above it instead has a product ID. To overcome +this, CodeIgniter allows you to remap the URI handler. + +Setting your own routing rules +============================== + +Routing rules are defined in your application/config/routes.php file. In +it you'll see an array called $route 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:: + + $route['product/:num'] = "catalog/product_lookup"; + +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" class and the "product_lookup" method are instead used. + +You can match literal values or you can use two wildcard types: + +**(:num)** will match a segment containing only numbers. + **(:any)** will match a segment containing any character. + +.. note:: Routes will run in the order they are defined. Higher routes + will always take precedence over lower ones. + +Examples +======== + +Here are a few routing examples:: + + $route['journals'] = "blogs"; + +A URL containing the word "journals" in the first segment will be +remapped to the "blogs" class. + +:: + + $route['blog/joe'] = "blogs/users/34"; + +A URL containing the segments blog/joe will be remapped to the "blogs" +class and the "users" method. The ID will be set to "34". + +:: + + $route['product/(:any)'] = "catalog/product_lookup"; + +A URL with "product" as the first segment, and anything in the second +will be remapped to the "catalog" class and the "product_lookup" +method. + +:: + + $route['product/(:num)'] = "catalog/product_lookup_by_id/$1"; + +A URL with "product" as the first segment, and a number in the second +will be remapped to the "catalog" class and the +"product_lookup_by_id" method passing in the match as a variable to +the function. + +.. 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. + +.. note:: If you use back-references you must use the dollar syntax + rather than the double backslash syntax. + +A typical RegEx route might look something like this:: + + $route['products/([a-z]+)/(\d+)'] = "$1/id_$2"; + +In the above example, a URI similar to products/shirts/123 would instead +call the shirts controller class and the id_123 function. + +You can also mix and match wildcards with regular expressions. + +Reserved Routes +=============== + +There are two reserved routes:: + + $route['default_controller'] = 'welcome'; + +This route indicates which controller class 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" class would be loaded. You are +encouraged to always have a default route otherwise a 404 page will +appear by default. + +:: + + $route['404_override'] = ''; + +This route indicates which controller class should be loaded if the +requested controller is not found. It will override the default 404 +error page. It won't affect to the show_404() function, which will +continue loading the default error_404.php file at +application/errors/error_404.php. + +.. important:: The reserved routes must come before any wildcard or + regular expression routes. -- cgit v1.2.3-24-g4f1b