Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 8fdda7907446db9ae2b9096a7caf361d4af98ce6 / . / user_guide / helpers / url_helper.html
blob: d20f1b1e27c21bcc62ea30803cdf38fbebc227ee [file] [log] [blame]
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]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>URL Helper : 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</head>
22<body>
23
24<!-- START NAVIGATION -->
25<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
26<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>
27<div id="masthead">
28<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
29<tr>
Pascal Kriete1f622292011-04-07 12:06:51 -0400[diff] [blame]30<td><h1>CodeIgniter User Guide Version 2.0.2</h1></td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]31<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
32</tr>
33</table>
34</div>
35<!-- END NAVIGATION -->
36
37
38<!-- START BREADCRUMB -->
39<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
40<tr>
41<td id="breadcrumb">
42<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
43<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
44URL Helper
45</td>
46<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>
47</tr>
48</table>
49<!-- END BREADCRUMB -->
50
51<br clear="all" />
52
53
54<!-- START CONTENT -->
55<div id="content">
56
57
58<h1>URL Helper</h1>
59
60<p>The URL Helper file contains functions that assist in working with URLs.</p>
61
62
63<h2>Loading this Helper</h2>
64
65<p>This helper is loaded using the following code:</p>
66<code>$this->load->helper('url');</code>
67
68<p>The following functions are available:</p>
69
70<h2>site_url()</h2>
71
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]72<p>Returns your site URL, as specified in your config file. The index.php file (or whatever you have set as your
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]73site <dfn>index_page</dfn> in your config file) will be added to the URL, as will any URI segments you pass to the function.</p>
74
75<p>You are encouraged to use this function any time you need to generate a local URL so that your pages become more portable
76in the event your URL changes.</p>
77
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]78<p>Segments can be optionally passed to the function as a string or an array. Here is a string example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]79
80<code>echo site_url("news/local/123");</code>
81
82<p>The above example would return something like: http://example.com/index.php/news/local/123</p>
83
84<p>Here is an example of segments passed as an array:</p>
85
86<code>
87$segments = array('news', 'local', '123');<br />
88<br />
89echo site_url($segments);</code>
90
91
92<h2>base_url()</h2>
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]93<p>Returns your site base URL, as specified in your config file. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]94<code>echo base_url();</code>
95
96
97<h2>current_url()</h2>
98<p>Returns the full URL (including segments) of the page being currently viewed.</p>
99
100
101<h2>uri_string()</h2>
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]102<p>Returns the URI segments of any page that contains this function. For example, if your URL was this:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]103<code>http://some-site.com/blog/comments/123</code>
104
105<p>The function would return:</p>
Derek Allard1f237112009-08-17 15:31:33 +0000[diff] [blame]106<code>/blog/comments/123</code>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]107
108
109<h2>index_page()</h2>
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]110<p>Returns your site "index" page, as specified in your config file. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]111<code>echo index_page();</code>
112
113
114
115<h2>anchor()</h2>
116
117<p>Creates a standard HTML anchor link based on your local site URL:</p>
118
119<code>&lt;a href="http://example.com">Click Here&lt;/a></code>
120
121<p>The tag has three optional parameters:</p>
122
123<code>anchor(<var>uri segments</var>, <var>text</var>, <var>attributes</var>)</code>
124
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]125<p>The first parameter can contain any segments you wish appended to the URL. As with the <dfn>site_url()</dfn> function above,
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]126segments can be a string or an array.</p>
127
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]128<p><strong>Note:</strong>&nbsp; If you are building links that are internal to your application do not include the base URL (http://...). This
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]129will be added automatically from the information specified in your config file. Include only the URI segments you wish appended to the URL.</p>
130
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]131<p>The second segment is the text you would like the link to say. If you leave it blank, the URL will be used.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]132
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]133<p>The third parameter can contain a list of attributes you would like added to the link. The attributes can be a simple string or an associative array.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]134
135<p>Here are some examples:</p>
136
Derek Allard6f7b0aa2009-09-16 08:26:33 +0000[diff] [blame]137<code>echo anchor('news/local/123', 'My News', 'title="News title"');</code>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]138
Derek Allard6f7b0aa2009-09-16 08:26:33 +0000[diff] [blame]139<p>Would produce: &lt;a href="http://example.com/index.php/news/local/123" title="News title">My News&lt;/a></p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]140
141<code>echo anchor('news/local/123', 'My News', array('title' => 'The best news!'));</code>
142
143<p>Would produce: &lt;a href="http://example.com/index.php/news/local/123" title="The best news!">My News&lt;/a></p>
144
145
146<h2>anchor_popup()</h2>
147
148<p>Nearly identical to the <dfn>anchor()</dfn> function except that it opens the URL in a new window.
149
150You can specify JavaScript window attributes in the third parameter to control how the window is opened. If
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]151the third parameter is not set it will simply open a new window with your own browser settings. Here is an example
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]152with attributes:</p>
153
154<code>
155
156$atts = array(<br />
157&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'width'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> '800',<br />
158&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'height'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> '600',<br />
159&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'scrollbars' => 'yes',<br />
160&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'status'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> 'yes',<br />
161&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'resizable'&nbsp;&nbsp;=> 'yes',<br />
162&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'screenx'&nbsp;&nbsp;&nbsp;&nbsp;=> '0',<br />
163&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'screeny'&nbsp;&nbsp;&nbsp;&nbsp;=> '0'<br />
164&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
165<br />
166echo anchor_popup('news/local/123', 'Click Me!', $atts);</code>
167
168<p>Note: The above attributes are the function defaults so you only need to set the ones that are different from what you need.
169If you want the function to use all of its defaults simply pass an empty array in the third parameter:</p>
170
171<code>echo anchor_popup('news/local/123', 'Click Me!', array());</code>
172
173
174<h2>mailto()</h2>
175
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]176<p>Creates a standard HTML email link. Usage example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]177
178<code>echo mailto('me@my-site.com', 'Click Here to Contact Me');</code>
179
180<p>As with the <dfn>anchor()</dfn> tab above, you can set attributes using the third parameter.</p>
181
182
183<h2>safe_mailto()</h2>
184
185<p>Identical to the above function except it writes an obfuscated version of the mailto tag using ordinal numbers
186written with JavaScript to help prevent the email address from being harvested by spam bots.</p>
187
188
189<h2>auto_link()</h2>
190
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]191<p>Automatically turns URLs and email addresses contained in a string into links. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]192
193<code>$string = auto_link($string);</code>
194
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]195<p>The second parameter determines whether URLs and emails are converted or just one or the other. Default behavior is both
196if the parameter is not specified. Email links are encoded as safe_mailto() as shown above.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]197
198<p>Converts only URLs:</p>
199<code>$string = auto_link($string, 'url');</code>
200
201<p>Converts only Email addresses:</p>
202<code>$string = auto_link($string, 'email');</code>
203
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]204<p>The third parameter determines whether links are shown in a new window. The value can be TRUE or FALSE (boolean):</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]205<code>$string = auto_link($string, 'both', TRUE);</code>
206
207
208<h2>url_title()</h2>
209<p>Takes a string as input and creates a human-friendly URL string. This is useful if, for example, you have a blog
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]210in which you'd like to use the title of your entries in the URL. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]211
212<code>$title = "What's wrong with CSS?";<br />
213<br />
214$url_title = url_title($title);<br />
215<br />
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]216// Produces: Whats-wrong-with-CSS
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]217</code>
218
219
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]220<p>The second parameter determines the word delimiter. By default dashes are used. Options are: <dfn>dash</dfn>, or <dfn>underscore</dfn>:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]221
222<code>$title = "What's wrong with CSS?";<br />
223<br />
224$url_title = url_title($title, 'underscore');<br />
225<br />
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]226// Produces: Whats_wrong_with_CSS
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]227</code>
228
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]229<p>The third parameter determines whether or not lowercase characters are forced. By default they are not. Options are boolean <dfn>TRUE</dfn>/<dfn>FALSE</dfn>:</p>
Derek Jones40a2fc82008-12-09 19:41:25 +0000[diff] [blame]230
231<code>$title = "What's wrong with CSS?";<br />
232<br />
233$url_title = url_title($title, 'underscore', TRUE);<br />
234<br />
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]235// Produces: whats_wrong_with_css
Derek Jones40a2fc82008-12-09 19:41:25 +0000[diff] [blame]236</code>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]237
238<h3>prep_url()</h3>
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]239<p>This function will add <kbd>http://</kbd> in the event that a scheme is missing from a URL. Pass the URL string to the function like this:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]240<code>
241$url = "example.com";<br /><br />
242$url = prep_url($url);</code>
243
244
245
246
247<h2>redirect()</h2>
248
Derek Allard15fd1a62010-01-17 16:35:13 +0000[diff] [blame]249<p>Does a "header redirect" to the URI specified. If you specify the full site URL that link will be build, but for local links simply providing the URI segments
250to the controller you want to direct to will create the link. The function will build the URL based on your config file values.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]251
252<p>The optional second parameter allows you to choose between the "location"
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]253method (default) or the "refresh" method. Location is faster, but on Windows servers it can sometimes be a problem. The optional third parameter allows you to send a specific HTTP Response Code - this could be used for example to create 301 redirects for search engine purposes. The default Response Code is 302. The third parameter is <em>only</em> available with 'location' redirects, and not 'refresh'. Examples:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]254
255<code>if ($logged_in == FALSE)<br />
256{<br />
257&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;redirect('/login/form/', 'refresh');<br />
258}<br />
259<br />
260// with 301 redirect<br />
261redirect('/article/13', 'location', 301);</code>
262
263<p class="important"><strong>Note:</strong> In order for this function to work it must be used before anything is outputted
264to the browser since it utilizes server headers.<br />
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame]265<strong>Note:</strong> For very fine grained control over headers, you should use the <a href="../libraries/output.html">Output Library</a>'s set_header() function.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]266
267
268
269
270
271
272</div>
273<!-- END CONTENT -->
274
275
276<div id="footer">
277<p>
278Previous Topic:&nbsp;&nbsp;<a href="typography_helper.html">Typography Helper</a>
279&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
280<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
281<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
282Next Topic:&nbsp;&nbsp;<a href="xml_helper.html">XML Helper</a>
283</p>
Derek Jones898949f2011-01-28 07:42:16 -0600[diff] [blame]284<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]285</div>
286
287</body>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]288</html>