Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 00618de8c4aca96edb09094a86242b2495ba124d / . / user_guide / helpers / url_helper.html
blob: d8812e5f51e8fd3ca2ce6c4c97abc4fdfaa858f2 [file] [log] [blame]
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Derek Allardafd99ac2008-01-19 19:59:14 +0000[diff] [blame]2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]3<head>
4
Derek Jonesfd93d222008-05-06 15:18:50 +0000[diff] [blame]5<title>URL Helper : CodeIgniter User Guide</title>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]6
7<style type='text/css' media='all'>@import url('../userguide.css');</style>
8<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
9
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]10<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]11<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]12<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +0000[diff] [blame]13<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]14
15<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
Derek Allard3d879d52008-01-18 19:41:32 +0000[diff] [blame]19<meta name='author' content='ExpressionEngine Dev Team' />
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]20<meta name='description' content='CodeIgniter User Guide' />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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.jpg" width="153" height="44" 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>
Derek Allard197d10b2008-02-12 04:20:38 +0000[diff] [blame]30<td><h1>CodeIgniter User Guide Version 1.6.1</h1></td>
adminc0d5d522006-10-30 19:40:35 +0000[diff] [blame]31<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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">
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]42<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]43<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
44URL Helper
45</td>
Derek Allardbc030912007-06-24 18:25:29 +0000[diff] [blame]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>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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
72<p>Returns your site URL, as specified in your config file. The index.php file (or whatever you have set as your
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
admine334c472006-10-21 19:44:22 +0000[diff] [blame]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
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]76in the event your URL changes.</p>
77
78<p>Segments can be optionally passed to the function as a string or an array. Here is a string example:</p>
79
80<code>echo site_url("news/local/123");</code>
81
82<p>The above example would return something like: http://www.your-site.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>
93<p>Returns your site base URL, as specified in your config file. Example:</p>
94<code>echo base_url();</code>
95
96
97<h2>index_page()</h2>
98<p>Returns your site "index" page, as specified in your config file. Example:</p>
99<code>echo index_page();</code>
100
101
102
103<h2>anchor()</h2>
104
105<p>Creates a standard HTML anchor link based on your local site URL:</p>
106
107<code>&lt;a href="http://www.your-site.com">Click Here&lt;/a></code>
108
109<p>The tag has three optional parameters:</p>
110
111<code>anchor(<var>uri segments</var>, <var>text</var>, <var>attributes</var>)</code>
112
113<p>The first parameter can contain any segments you wish appended to the URL. As with the <dfn>site_url()</dfn> function above,
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]114segments can be a string or an array.</p>
115
116<p><strong>Note:</strong>&nbsp; If you are building links that are internal to your application do not include the base URL (http://...). This
117will be added automatically from the information specified in your config file. Include only the URI segments you wish appended to the URL.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]118
119<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>
120
121<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>
122
123<p>Here are some examples:</p>
124
Derek Allardc4e9dc92007-02-06 19:52:30 +0000[diff] [blame]125<code>echo anchor('news/local/123', 'My News');</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]126
127<p>Would produce: &lt;a href="http://www.your-site.com/index.php/news/local/123" title="My News">My News&lt;/a></p>
128
Derek Allardc4e9dc92007-02-06 19:52:30 +0000[diff] [blame]129<code>echo anchor('news/local/123', 'My News', array('title' => 'The best news!'));</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]130
131<p>Would produce: &lt;a href="http://www.your-site.com/index.php/news/local/123" title="The best news!">My News&lt;/a></p>
132
133
134<h2>anchor_popup()</h2>
135
admine334c472006-10-21 19:44:22 +0000[diff] [blame]136<p>Nearly identical to the <dfn>anchor()</dfn> function except that it opens the URL in a new window.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]137
admine334c472006-10-21 19:44:22 +0000[diff] [blame]138You can specify JavaScript window attributes in the third parameter to control how the window is opened. If
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]139the third parameter is not set it will simply open a new window with your own browser settings. Here is an example
140with attributes:</p>
141
142<code>
143
144$atts = array(<br />
145&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'width'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> '800',<br />
146&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'height'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> '600',<br />
147&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'scrollbars' => 'yes',<br />
148&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'status'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> 'yes',<br />
149&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'resizable'&nbsp;&nbsp;=> 'yes',<br />
150&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'screenx'&nbsp;&nbsp;&nbsp;&nbsp;=> '0',<br />
151&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'screeny'&nbsp;&nbsp;&nbsp;&nbsp;=> '0'<br />
152&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
153<br />
Derek Allard9967ab42008-02-13 13:14:47 +0000[diff] [blame]154echo anchor_popup('news/local/123', 'Click Me!', $atts);</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]155
156<p>Note: The above attributes are the function defaults so you only need to set the ones that are different from what you need.
157If you want the function to use all of its defaults simply pass an empty array in the third parameter:</p>
158
Derek Allardc4e9dc92007-02-06 19:52:30 +0000[diff] [blame]159<code>echo anchor_popup('news/local/123', 'Click Me!', array());</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]160
161
162<h2>mailto()</h2>
163
164<p>Creates a standard HTML email link. Usage example:</p>
165
166<code>echo mailto('me@my-site.com', 'Click Here to Contact Me');</code>
167
168<p>As with the <dfn>anchor()</dfn> tab above, you can set attributes using the third parameter.</p>
169
170
171<h2>safe_mailto()</h2>
172
173<p>Identical to the above function except it writes an obfuscated version of the mailto tag using ordinal numbers
174written with JavaScript to help prevent the email address from being harvested by spam bots.</p>
175
176
177<h2>auto_link()</h2>
178
179<p>Automatically turns URLs and email addresses contained in a string into links. Example:</p>
180
181<code>$string = auto_link($string);</code>
182
183<p>The second parameter determines whether URLs and emails are converted or just one or the other. Default behavior is both
184if the parameter is not specified</p>
185
186<p>Converts only URLs:</p>
187<code>$string = auto_link($string, 'url');</code>
188
189<p>Converts only Email addresses:</p>
190<code>$string = auto_link($string, 'email');</code>
191
Derek Allardce66d152008-03-04 20:55:55 +0000[diff] [blame]192<p>The third parameter determines whether links are shown in a new window. The value can be TRUE or FALSE (boolean):</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]193<code>$string = auto_link($string, 'both', TRUE);</code>
194
195
196<h2>url_title()</h2>
197<p>Takes a string as input and creates a human-friendly URL string. This is useful if, for example, you have a blog
198in which you'd like to use the title of your entries in the URL. Example:</p>
199
200<code>$title = "What's wrong with CSS?";<br />
201<br />
202$url_title = url_title($title);<br />
203<br />
204// Produces: whats-wrong-with-css
205</code>
206
207
208<p>The second parameter determines the word delimiter. By default dashes are used. Options are: <dfn>dash</dfn>, or <dfn>underscore</dfn>:</p>
209
210<code>$title = "What's wrong with CSS?";<br />
211<br />
212$url_title = url_title($title, 'underscore');<br />
213<br />
214// Produces: whats_wrong_with_css
215</code>
216
217
218<h3>prep_url()</h3>
219<p>This function will add <kbd>http://</kbd> in the event it is missing from a URL. Pass the URL string to the function like this:</p>
220<code>
Derek Allard8788d4b2007-08-08 17:04:40 +0000[diff] [blame]221$url = "www.example.com";<br /><br />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]222$url = prep_url($url);</code>
223
224
225
226
227<h2>redirect()</h2>
228
229<p>Does a "header redirect" to the local URI specified. Just like other functions in this helper, this one is designed
230to redirect to a local URL within your site. You will <strong>not</strong> specify the full site URL, but rather simply the URI segments
231to the controller you want to direct to. The function will build the URL based on your config file values.</p>
232
Derek Allard05f830c2008-04-27 13:35:20 +0000[diff] [blame]233<p>The optional second parameter allows you to choose between the "location"
234method (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>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]235
236<code>if ($logged_in == FALSE)<br />
237{<br />
238&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;redirect('/login/form/', 'refresh');<br />
Derek Allard05f830c2008-04-27 13:35:20 +0000[diff] [blame]239}<br />
240<br />
241// with 301 redirect<br />
242redirect('/article/13', 'location', 301);</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]243
244<p class="important"><strong>Note:</strong> In order for this function to work it must be used before anything is outputted
Derek Allard05f830c2008-04-27 13:35:20 +0000[diff] [blame]245to the browser since it utilizes server headers.<br />
246<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>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]247
248
249
250
251
252
253</div>
254<!-- END CONTENT -->
255
256
257<div id="footer">
258<p>
259Previous Topic:&nbsp;&nbsp;<a href="typography_helper.html">Typography Helper</a>
260&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
261<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
262<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
263Next Topic:&nbsp;&nbsp;<a href="xml_helper.html">XML Helper</a>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]264</p>
Derek Jones07870432008-02-13 03:49:26 +0000[diff] [blame]265<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006-2008 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]266</div>
267
268</body>
269</html>