Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 928c55cbc5f3f162c10077f46d75d0bc0b1cbe53 / . / user_guide / general / helpers.html
blob: ea794f08a32a6bc682b0188205d28320e156a617 [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 Allard8039d4c2008-05-31 02:47:56 +0000[diff] [blame]5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Derek Jonesfd93d222008-05-06 15:18:50 +0000[diff] [blame]6<title>Helper Functions : CodeIgniter User Guide</title>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]11<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]12<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]13<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +0000[diff] [blame]14<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]15
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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
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.jpg" width="153" height="44" 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>
Derek Jones1ca3fc42008-06-27 00:19:33 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.3</h1></td>
adminc0d5d522006-10-30 19:40:35 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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">
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45Helper Functions
46</td>
Derek Allardbc030912007-06-24 18:25:29 +0000[diff] [blame]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&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]48</tr>
49</table>
50<!-- END BREADCRUMB -->
51
52<br clear="all" />
53
54
55<!-- START CONTENT -->
56<div id="content">
57
58<h1>Helper Functions</h1>
59
60<p>Helpers, as the name suggests, help you with tasks. Each helper file is simply a collection of functions in a particular
61category. There are <dfn>URL Helpers</dfn>, that assist in creating links, there are <dfn>Form Helpers</dfn>
62that help you create form elements, <dfn>Text Helpers</dfn> perform various text formatting routines,
63<dfn>Cookie Helpers</dfn> set and read cookies, <dfn>File Helpers</dfn> help you deal with files, etc.
64</p>
65
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]66<p>Unlike most other systems in CodeIgniter, Helpers are not written in an Object Oriented format. They are simple, procedural functions.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]67Each helper function performs one specific task, with no dependence on other functions.</p>
68
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]69<p>CodeIgniter does not load Helper Files by default, so the first step in using
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]70a Helper is to load it. Once loaded, it becomes globally available in your <a href="../general/controllers.html">controller</a> and <a href="../general/views.html">views</a>.</p>
71
Derek Allard928c55c2008-08-21 12:46:58 +0000[diff] [blame^]72<p>Helpers are typically stored in your <dfn>system/helpers</dfn>, or <dfn>system/application/helpers </dfn>directory. CodeIgniter will look first in your <dfn>system/application/helpers</dfn>
admine334c472006-10-21 19:44:22 +0000[diff] [blame]73directory. If the directory does not exist or the specified helper is not located there CI will instead look in your global
admin7c5595f2006-09-20 23:35:42 +0000[diff] [blame]74<dfn>system/helpers</dfn> folder.</p>
75
76
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]77<h2>Loading a Helper</h2>
78
79<p>Loading a helper file is quite simple using the following function:</p>
80
81<code>$this->load->helper('<var>name</var>');</code>
82
83<p>Where <var>name</var> is the file name of the helper, without the .php file extension or the "helper" part.</p>
84
85<p>For example, to load the <dfn>URL Helper</dfn> file, which is named <var>url_helper.php</var>, you would do this:</p>
86
87<code>$this->load->helper('<var>url</var>');</code>
88
89<p>A helper can be loaded anywhere within your controller functions (or even within your View files, although that's not a good practice),
90as long as you load it before you use it. You can load your helpers in your controller constructor so that they become available
91automatically in any function, or you can load a helper in a specific function that needs it.</p>
92
93<p class="important">Note: The Helper loading function above does not return a value, so don't try to assign it to a variable. Just use it as shown.</p>
94
95
96<h2>Loading Multiple Helpers</h2>
97
98<p>If you need to load more than one helper you can specify them in an array, like this:</p>
99
100<code>$this->load->helper( <samp>array(</samp>'<var>helper1</var>', '<var>helper2</var>', '<var>helper3</var>'<samp>)</samp> );</code>
101
102<h2>Auto-loading Helpers</h2>
103
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]104<p>If you find that you need a particular helper globally throughout your application, you can tell CodeIgniter to auto-load it during system initialization.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]105This is done by opening the <var>application/config/autoload.php</var> file and adding the helper to the autoload array.</p>
106
107
108<h2>Using a Helper</h2>
109
110<p>Once you've loaded the Helper File containing the function you intend to use, you'll call it the way you would a standard PHP function.</p>
111
112<p>For example, to create a link using the <dfn>anchor()</dfn> function in one of your view files you would do this:</p>
113
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame]114<code>&lt;?php echo anchor('blog/comments', 'Click Here');?&gt;</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]115
116<p>Where "Click Here" is the name of the link, and "blog/comments" is the URI to the controller/function you wish to link to.</p>
117
Derek Jones269b9422008-01-28 21:00:20 +0000[diff] [blame]118<h2>"Extending" Helpers</h2>
119
120<p>To "extend" Helpers, create a file in your <dfn>application/helpers/</dfn> folder with an identical name to the existing Helper, but prefixed with <kbd>MY_</kbd> (this item is configurable. See below.).</p>
121
122<p>If all you need to do is add some functionality to an existing helper - perhaps add a function or two, or change how a particular
123 helper function operates - then it's overkill to replace the entire helper with your version. In this case it's better to simply
124 "extend" the Helper. The term "extend" is used loosely since Helper functions are procedural and discrete and cannot be extended
125 in the traditional programmatic sense. Under the hood, this gives you the ability to add to the functions a Helper provides,
126 or to modify how the native Helper functions operate.</p>
127
128<p>For example, to extend the native <kbd>Array Helper</kbd> you'll create a file named <dfn>application/helpers/</dfn><kbd>MY_array_helper.php</kbd>, and add or override functions:</p>
129
130<code>
131// any_in_array() is not in the Array Helper, so it defines a new function<br />
132function any_in_array($needle, $haystack)<br />
133{<br />
134&nbsp;&nbsp;&nbsp;&nbsp;$needle = (is_array($needle)) ? $needle : array($needle);<br />
135 <br />
136&nbsp;&nbsp;&nbsp;&nbsp;foreach ($needle as $item)<br />
137&nbsp;&nbsp;&nbsp;&nbsp;{<br />
138&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (in_array($item, $haystack))<br />
139&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
140&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return TRUE;<br />
141&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
142&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
143 <br />
144&nbsp;&nbsp;&nbsp;&nbsp;return FALSE;<br />
145}<br />
146<br />
147// random_element() is included in Array Helper, so it overrides the native function<br />
148function random_element($array)<br />
149{<br />
150&nbsp;&nbsp;&nbsp;&nbsp;shuffle($array);<br />
Derek Allard1ea127a2008-04-04 12:26:46 +0000[diff] [blame]151&nbsp;&nbsp;&nbsp;&nbsp;return array_pop($array);<br />
Derek Jones269b9422008-01-28 21:00:20 +0000[diff] [blame]152}<br />
153</code>
154
155<h3>Setting Your Own Prefix</h3>
156
157<p>The filename prefix for "extending" Helpers is the same used to extend libraries and Core classes. To set your own prefix, open your <dfn>application/config/config.php</dfn> file and look for this item:</p>
158
159<code>$config['subclass_prefix'] = 'MY_';</code>
160
161<p>Please note that all native CodeIgniter libraries are prefixed with <kbd>CI_</kbd> so DO NOT use that as your prefix.</p>
162
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]163
164<h2>Now What?</h2>
165
166<p>In the Table of Contents you'll find a list of all the available Helper Files. Browse each one to see what they do.</p>
167
168
169</div>
170<!-- END CONTENT -->
171
172
173<div id="footer">
174<p>
Derek Allard9da4dbc2007-04-03 11:39:35 +0000[diff] [blame]175Previous Topic:&nbsp;&nbsp;<a href="models.html">Models</a>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]176&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
177<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
178<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
179Next Topic:&nbsp;&nbsp;<a href="plugins.html">Plugins</a>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]180</p>
Derek Jones07870432008-02-13 03:49:26 +0000[diff] [blame]181<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]182</div>
183
184</body>
185</html>