summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/helpers/url_helper.rst
blob: 7a49f188da45c3317a79904c14f868bab081f213 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
##########
URL Helper
##########

The URL Helper file contains functions that assist in working with URLs.

.. contents:: Page Contents

Loading this Helper
===================

This helper is loaded using the following code::

	$this->load->helper('url');

The following functions are available:

site_url()
==========

.. php:function:: site_url($uri = '', $protocol = NULL)

	:param	string	$uri: URI string
	:param	string	$protocol: Protocol, e.g. 'http' or 'https'
	:returns:	string

Returns your site URL, as specified in your config file. The index.php
file (or whatever you have set as your site **index_page** in your config
file) will be added to the URL, as will any URI segments you pass to the
function, plus the **url_suffix** as set in your config file.

You are encouraged to use this function any time you need to generate a
local URL so that your pages become more portable in the event your URL
changes.

Segments can be optionally passed to the function as a string or an
array. Here is a string example::

	echo site_url('news/local/123');

The above example would return something like:
*http://example.com/index.php/news/local/123*

Here is an example of segments passed as an array::

	$segments = array('news', 'local', '123');
	echo site_url($segments);

This function is an alias for ``CI_Config::site_url()``. For more info,
please see the :doc:`Config Library <../libraries/config>` documentation.

base_url()
===========

.. php:function:: base_url($uri = '', $protocol = NULL)

	:param	string	$uri: URI string
	:param	string	$protocol: Protocol, e.g. 'http' or 'https'
	:returns:	string

Returns your site base URL, as specified in your config file. Example::

	echo base_url();

This function returns the same thing as :php:func:`site_url()`, without
the *index_page* or *url_suffix* being appended.

Also like :php:func:`site_url()`, you can supply segments as a string or
an array. Here is a string example::

	echo base_url("blog/post/123");

The above example would return something like:
*http://example.com/blog/post/123*

This is useful because unlike :php:func:`site_url()`, you can supply a
string to a file, such as an image or stylesheet. For example::

	echo base_url("images/icons/edit.png");

This would give you something like:
*http://example.com/images/icons/edit.png*

This function is an alias for ``CI_Config::base_url()``. For more info,
please see the :doc:`Config Library <../libraries/config>` documentation.

current_url()
=============

.. php:function:: current_url()

	:returns:	string

Returns the full URL (including segments) of the page being currently
viewed.

.. note:: Calling this function is the same as doing this:
	|
	| site_url(uri_string());

uri_string()
============

.. php:function:: uri_string()

	:returns:	string

Returns the URI segments of any page that contains this function.
For example, if your URL was this::

	http://some-site.com/blog/comments/123

The function would return::

	blog/comments/123

This function is an alias for ``CI_Config::uri_string()``. For more info,
please see the :doc:`Config Library <../libraries/config>` documentation.

index_page()
============

.. php:function:: index_page()

	:returns:	string

Returns your site **index_page**, as specified in your config file.
Example::

	echo index_page();

anchor()
========

.. php:function:: anchor($uri = '', $title = '', $attributes = '')

	:param	string	$uri: URI string
	:param	string	$title: Anchor title
	:param	mixed	$attributes: HTML attributes
	:returns:	string

Creates a standard HTML anchor link based on your local site URL.

The first parameter can contain any segments you wish appended to the
URL. As with the :php:func:`site_url()` function above, segments can
be a string or an array.

.. note:: If you are building links that are internal to your application
	do not include the base URL (http://...). This will be added
	automatically from the information specified in your config file.
	Include only the URI segments you wish appended to the URL.

The second segment is the text you would like the link to say. If you
leave it blank, the URL will be used.

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.

Here are some examples::

	echo anchor('news/local/123', 'My News', 'title="News title"');
	// Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a>

	echo anchor('news/local/123', 'My News', array('title' => 'The best news!'));
	// Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a>

	echo anchor('', 'Click here');
	// Prints: <a href="http://example.com">Click Here</a>

anchor_popup()
==============

.. php:function:: anchor_popup($uri = '', $title = '', $attributes = FALSE)

	:param	string	$uri: URI string
	:param	string	$title: Anchor title
	:param	mixed	$attributes: HTML attributes
	:returns:	string

Nearly identical to the :php:func:``anchor()`` function except that it
opens the URL in a new window. You can specify JavaScript window
attributes in the third parameter to control how the window is opened.
If the third parameter is not set it will simply open a new window with
your own browser settings.

Here is an example with attributes::

	$atts = array(
		'width'       => 800,
		'height'      => 600,
		'scrollbars'  => 'yes',
		'status'      => 'yes',
		'resizable'   => 'yes',
		'screenx'     => 0,
		'screeny'     => 0,
		'window_name' => '_blank'
	);

	echo anchor_popup('news/local/123', 'Click Me!', $atts);

.. note:: The above attributes are the function defaults so you only need to
	set the ones that are different from what you need. If you want the
	function to use all of its defaults simply pass an empty array in the
	third parameter:
	|
	| echo anchor_popup('news/local/123', 'Click Me!', array());

.. note:: The **window_name** is not really an attribute, but an argument to
	the JavaScript `window.open() <http://www.w3schools.com/jsref/met_win_open.asp>`
	method, which accepts either a window name or a window target.

.. note:: Any other attribute than the listed above will be parsed as an
	HTML attribute to the anchor tag.

mailto()
========

.. php:function:: mailto($email, $title = '', $attributes = '')

	:param	string	$email: E-mail address
	:param	string	$title: Anchor title
	:param	mixed	$attributes: HTML attributes
	:returns:	string

Creates a standard HTML e-mail link. Usage example::

	echo mailto('me@my-site.com', 'Click Here to Contact Me');

As with the :php:func:`anchor()` tab above, you can set attributes using the
third parameter::

	$attributes = array('title' => 'Mail me');
	echo mailto('me@my-site.com', 'Contact Me', $attributes);

safe_mailto()
=============

.. php:function:: safe_mailto($email, $title = '', $attributes = '')

	:param	string	$email: E-mail address
	:param	string	$title: Anchor title
	:param	mixed	$attributes: HTML attributes
	:returns:	string

Identical to the :php:func:`mailto()` function except it writes an obfuscated
version of the *mailto* tag using ordinal numbers written with JavaScript to
help prevent the e-mail address from being harvested by spam bots.

auto_link()
===========

.. php:function:: auto_link($str, $type = 'both', $popup = FALSE)

	:param	string	$str: Input string
	:param	string	$type: Link type ('email', 'url' or 'both')
	:param	bool	$popup: Whether to create popup links
	:returns:	string

Automatically turns URLs and e-mail addresses contained in a string into
links. Example::

	$string = auto_link($string);

The second parameter determines whether URLs and e-mails are converted or
just one or the other. Default behavior is both if the parameter is not
specified. E-mail links are encoded as :php:func:`safe_mailto()` as shown
above.

Converts only URLs::

	$string = auto_link($string, 'url');

Converts only e-mail addresses::

	$string = auto_link($string, 'email');

The third parameter determines whether links are shown in a new window.
The value can be TRUE or FALSE (boolean)::

	$string = auto_link($string, 'both', TRUE);

url_title()
===========

.. php:function:: url_title($str, $separator = '-', $lowercase = FALSE)

	:param	string	$str: Input string
	:param	string	$separator: Word separator
	:param	string	$lowercase: Whether to transform the output string to lower-case
	:returns:	string

Takes a string as input and creates a human-friendly URL string. This is
useful if, for example, you have a blog in which you'd like to use the
title of your entries in the URL. Example::

	$title = "What's wrong with CSS?";
	$url_title = url_title($title);
	// Produces: Whats-wrong-with-CSS

The second parameter determines the word delimiter. By default dashes
are used. Preferred options are: **-** (dash) or **_** (underscore)

Example::

	$title = "What's wrong with CSS?";
	$url_title = url_title($title, 'underscore');
	// Produces: Whats_wrong_with_CSS

.. note:: Old usage of 'dash' and 'underscore' as the second parameter
	is DEPRECATED.

The third parameter determines whether or not lowercase characters are
forced. By default they are not. Options are boolean TRUE/FALSE.

Example::

	$title = "What's wrong with CSS?";
	$url_title = url_title($title, 'underscore', TRUE);
	// Produces: whats_wrong_with_css

prep_url()
----------

.. php:function:: prep_url($str = '')

	:param	string	$str: URL string
	:returns:	string

This function will add http:// in the event that a protocol prefix
is missing from a URL.

Pass the URL string to the function like this::

	$url = prep_url('example.com');

redirect()
==========

.. php:function:: redirect($uri = '', $method = 'auto', $code = NULL)

	:param	string	$uri: URI string
	:param	string	$method: Redirect method ('auto', 'location' or 'refresh')
	:param	string	$code: HTTP Response code (usually 302 or 303)
	:returns:	void

Does a "header redirect" to the URI specified. If you specify the full
site URL that link will be built, but for local links simply providing
the URI segments to the controller you want to direct to will create the
link. The function will build the URL based on your config file values.

The optional second parameter allows you to force a particular redirection
method. The available methods are **auto**, **location** and **refresh**,
with location being faster but less reliable on IIS servers.
The default is **auto**, which will attempt to intelligently choose the
method based on the server environment.

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
*only* available with **location** redirects, and not *refresh*. Examples::

	if ($logged_in == FALSE)
	{      
		redirect('/login/form/');
	}

	// with 301 redirect
	redirect('/article/13', 'location', 301);

.. note:: In order for this function to work it must be used before anything
	is outputted to the browser since it utilizes server headers.

.. note:: For very fine grained control over headers, you should use the
	`Output Library </libraries/output>` ``set_header()`` method.

.. note:: To IIS users: if you hide the `Server` HTTP header, the *auto*
	method won't detect IIS, in that case it is advised you explicitly
	use the **refresh** method.

.. note:: When the **location** method is used, an HTTP status code of 303
	will *automatically* be selected when the page is currently accessed
	via POST and HTTP/1.1 is used.

.. important:: This function will terminate script execution.