[z_archive/KronOS.git] / video / user_guide / general / routing.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>URI Routing : CodeIgniter User Guide</title>

<style type='text/css' media='all'>@import url('../userguide.css');</style>
<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />

<script type="text/javascript" src="../nav/nav.js"></script>
<script type="text/javascript" src="../nav/prototype.lite.js"></script>
<script type="text/javascript" src="../nav/moo.fx.js"></script>
<script type="text/javascript" src="../nav/user_guide_menu.js"></script>

<meta http-equiv='expires' content='-1' />
<meta http-equiv= 'pragma' content='no-cache' />
<meta name='robots' content='all' />
<meta name='author' content='ExpressionEngine Dev Team' />
<meta name='description' content='CodeIgniter User Guide' />

</head>
<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>CodeIgniter User Guide Version 2.1.3</h1></td>
<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->


<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
URI Routing
</td>
<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
</tr>
</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">

<h1>URI Routing</h1>

<p>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:</p>

<code>example.com/<dfn>class</dfn>/<samp>function</samp>/<var>id</var>/</code>

<p>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.</p>

<p>For example, lets say you want your URLs to have this prototype:</p>

<p>
example.com/product/1/<br />
example.com/product/2/<br />
example.com/product/3/<br />
example.com/product/4/
</p>

<p>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.</p>


<h2>Setting your own routing rules</h2>

<p>Routing rules are defined in your <var>application/config/routes.php</var> file.  In it you'll see an array called <dfn>$route</dfn> that
permits you to specify your own routing criteria. Routes can either be specified using <dfn>wildcards</dfn> or <dfn>Regular Expressions</dfn></p>


<h2>Wildcards</h2>

<p>A typical wildcard route might look something like this:</p>

<code>$route['product/:num'] = "catalog/product_lookup";</code>

<p>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.</p>

<p>You can match literal values or you can use two wildcard types:</p>

<p><strong>(:num)</strong> will match a segment containing only numbers.<br />
<strong>(:any)</strong> will match a segment containing any character.
</p>

<p class="important"><strong>Note:</strong> Routes will run in the order they are defined.
Higher routes will always take precedence over lower ones.</p>

<h2>Examples</h2>

<p>Here are a few routing examples:</p>

<code>$route['journals'] = "blogs";</code>
<p>A URL containing the word "journals" in the first segment will be remapped to the "blogs" class.</p>

<code>$route['blog/joe'] = "blogs/users/34";</code>
<p>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".</p>

<code>$route['product/(:any)'] = "catalog/product_lookup";</code>
<p>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.</p>

<code>$route['product/(:num)'] = "catalog/product_lookup_by_id/$1";</code>
<p>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.</p>

<p class="important"><strong>Important:</strong> Do not use leading/trailing slashes.</p>

<h2>Regular Expressions</h2>

<p>If you prefer you can use regular expressions to define your routing rules.  Any valid regular expression is allowed, as are back-references.</p>

<p class="important"><strong>Note:</strong>&nbsp; If you use back-references you must use the dollar syntax rather than the double backslash syntax.</p>

<p>A typical RegEx route might look something like this:</p>

<code>$route['products/([a-z]+)/(\d+)'] = "$1/id_$2";</code>

<p>In the above example, a URI similar to <dfn>products/shirts/123</dfn> would instead call the <dfn>shirts</dfn> controller class and the <dfn>id_123</dfn> function.</p>

<p>You can also mix and match wildcards with regular expressions.</p>

<h2>Reserved Routes</h2>

<p>There are two reserved routes:</p>

<code>$route['default_controller'] = 'welcome';</code>

<p>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.</p>

<code>$route['404_override'] = '';</code>

<p>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 <samp>show_404()</samp> function, which will continue loading the default <dfn>error_404.php</dfn> file at <var>application/errors/error_404.php</var>.</p>

<p class="important"><strong>Important:</strong>&nbsp; The reserved routes must come before any wildcard or regular expression routes.</p>

</div>
<!-- END CONTENT -->


<div id="footer">
<p>
Previous Topic:&nbsp;&nbsp;<a href="common_functions.html">Common Functions</a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href="errors.html">Error Handling</a>
</p>
<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2012 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
</div>

</body>
</html>
Commit	Line	Data
59c06b17 CS	1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	2	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	3	<head>
	4
	5	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	6	<title>URI Routing : CodeIgniter User Guide</title>
	7
	8	<style type='text/css' media='all'>@import url('../userguide.css');</style>
	9	<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
	10
	11	<script type="text/javascript" src="../nav/nav.js"></script>
	12	<script type="text/javascript" src="../nav/prototype.lite.js"></script>
	13	<script type="text/javascript" src="../nav/moo.fx.js"></script>
	14	<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
	15
	16	<meta http-equiv='expires' content='-1' />
	17	<meta http-equiv= 'pragma' content='no-cache' />
	18	<meta name='robots' content='all' />
	19	<meta name='author' content='ExpressionEngine Dev Team' />
	20	<meta name='description' content='CodeIgniter User Guide' />
	21
	22	</head>
	23	<body>
	24
	25	<!-- START NAVIGATION -->
	26	<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
	27	<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
	28	<div id="masthead">
	29	<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
	30	<tr>
	31	<td><h1>CodeIgniter User Guide Version 2.1.3</h1></td>
	32	<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
	33	</tr>
	34	</table>
	35	</div>
	36	<!-- END NAVIGATION -->
	37
	38
	39	<!-- START BREADCRUMB -->
	40	<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
	41	<tr>
	42	<td id="breadcrumb">
	43	<a href="http://codeigniter.com/">CodeIgniter Home</a>  ›
	44	<a href="../index.html">User Guide Home</a>  ›
	45	URI Routing
	46	</td>
	47	<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide  <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <input type="submit" class="submit" name="sa" value="Go" /></form></td>
	48	</tr>
	49	</table>
	50	<!-- END BREADCRUMB -->
	51
	52	<br clear="all" />
	53
	54
	55	<!-- START CONTENT -->
	56	<div id="content">
	57
	58	<h1>URI Routing</h1>
	59
	60	<p>Typically there is a one-to-one relationship between a URL string and its corresponding controller class/method.
	61	The segments in a URI normally follow this pattern:</p>
	62
	63	<code>example.com/<dfn>class</dfn>/<samp>function</samp>/<var>id</var>/</code>
	64
65	<p>In some instances, however, you may want to remap this relationship so that a different class/function can be called
66	instead of the one corresponding to the URL.</p>
67
68	<p>For example, lets say you want your URLs to have this prototype:</p>
69
70	<p>
71	example.com/product/1/<br />
72	example.com/product/2/<br />
73	example.com/product/3/<br />
74	example.com/product/4/
75	</p>
76
77	<p>Normally the second segment of the URL is reserved for the function name, but in the example above it instead has a product ID.
78	To overcome this, CodeIgniter allows you to remap the URI handler.</p>
79
80
81	<h2>Setting your own routing rules</h2>
82
83	<p>Routing rules are defined in your <var>application/config/routes.php</var> file. In it you'll see an array called <dfn>$route</dfn> that
84	permits you to specify your own routing criteria. Routes can either be specified using <dfn>wildcards</dfn> or <dfn>Regular Expressions</dfn></p>
85
86
87	<h2>Wildcards</h2>
88
89	<p>A typical wildcard route might look something like this:</p>
90
91	<code>$route['product/:num'] = "catalog/product_lookup";</code>
92
93	<p>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.
94	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,
95	the "catalog" class and the "product_lookup" method are instead used.</p>
96
97	<p>You can match literal values or you can use two wildcard types:</p>
98
99	<p><strong>(:num)</strong> will match a segment containing only numbers.<br />
100	<strong>(:any)</strong> will match a segment containing any character.
101	</p>
102
103	<p class="important"><strong>Note:</strong> Routes will run in the order they are defined.
104	Higher routes will always take precedence over lower ones.</p>
105
106	<h2>Examples</h2>
107
108	<p>Here are a few routing examples:</p>
109
110	<code>$route['journals'] = "blogs";</code>
111	<p>A URL containing the word "journals" in the first segment will be remapped to the "blogs" class.</p>
112
113	<code>$route['blog/joe'] = "blogs/users/34";</code>
114	<p>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".</p>
115
116	<code>$route['product/(:any)'] = "catalog/product_lookup";</code>
117	<p>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.</p>
118
119	<code>$route['product/(:num)'] = "catalog/product_lookup_by_id/$1";</code>
120	<p>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.</p>
121
122	<p class="important"><strong>Important:</strong> Do not use leading/trailing slashes.</p>
123
124	<h2>Regular Expressions</h2>
125
126	<p>If you prefer you can use regular expressions to define your routing rules. Any valid regular expression is allowed, as are back-references.</p>
127
128	<p class="important"><strong>Note:</strong>  If you use back-references you must use the dollar syntax rather than the double backslash syntax.</p>
129
130	<p>A typical RegEx route might look something like this:</p>
131
132	<code>$route['products/([a-z]+)/(\d+)'] = "$1/id_$2";</code>
133
134	<p>In the above example, a URI similar to <dfn>products/shirts/123</dfn> would instead call the <dfn>shirts</dfn> controller class and the <dfn>id_123</dfn> function.</p>
135
136	<p>You can also mix and match wildcards with regular expressions.</p>
137
138	<h2>Reserved Routes</h2>
139
140	<p>There are two reserved routes:</p>
141
142	<code>$route['default_controller'] = 'welcome';</code>
143
144	<p>This route indicates which controller class should be loaded if the URI contains no data, which will be the case
145	when people load your root URL. In the above example, the "welcome" class would be loaded. You
146	are encouraged to always have a default route otherwise a 404 page will appear by default.</p>
147
148	<code>$route['404_override'] = '';</code>
149
150	<p>This route indicates which controller class should be loaded if the requested controller is not found. It will override the default 404
151	error page. It won't affect to the <samp>show_404()</samp> function, which will continue loading the default <dfn>error_404.php</dfn> file at <var>application/errors/error_404.php</var>.</p>
152
153	<p class="important"><strong>Important:</strong>  The reserved routes must come before any wildcard or regular expression routes.</p>
154
155	</div>
156	<!-- END CONTENT -->
157
158
159	<div id="footer">
160	<p>
161	Previous Topic:  <a href="common_functions.html">Common Functions</a>
162	·
163	<a href="#top">Top of Page</a>   ·
164	<a href="../index.html">User Guide Home</a>   ·
165	Next Topic:  <a href="errors.html">Error Handling</a>
166	</p>
167	<p><a href="http://codeigniter.com">CodeIgniter</a>  ·  Copyright © 2006 - 2012  ·  <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
168	</div>
169
170	</body>
171	</html>