Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 2f9559736080f8386fec1bb5a1d99bd9855e2a4d / . / user_guide / libraries / validation.html
blob: 815b542be6169bef5fc48d0018b98173aaa7cc4d [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 Allard404e35d2007-08-07 01:00:45 +0000[diff] [blame]5<title>CodeIgniter User Guide : Form Validation</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
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 Allard197d10b2008-02-12 04:20:38 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.1</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;
45Form Validation
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>Form Validation</h1>
59
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]60<p>Before explaining CodeIgniter's approach to data validation, let's describe the ideal scenario:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]61
62<ol>
63<li>A form is displayed.</li>
64<li>You fill it in and submit it.</li>
65<li>If you submitted something invalid, or perhaps missed a required item, the form is redisplayed containing your data along with an error message describing the problem.</li>
66<li>This process continues until you have submitted a valid form.</li>
67</ol>
68
69<p>On the receiving end, the script must:</p>
70
71<ol>
72<li>Check for required data.</li>
admine334c472006-10-21 19:44:22 +0000[diff] [blame]73<li>Verify that the data is of the correct type, and meets the correct criteria. (For example, if a username is submitted
74it must be validated to contain only permitted characters. It must be of a minimum length,
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]75and not exceed a maximum length. The username can't be someone else's existing username, or perhaps even a reserved word. Etc.)</li>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]76<li>Sanitize the data for security.</li>
77<li>Pre-format the data if needed (Does the data need to be trimmed? HTML encoded? Etc.)</li>
78<li>Prep the data for insertion in the database.</li>
79</ol>
80
81
82<p>Although there is nothing complex about the above process, it usually requires a significant
83amount of code, and to display error messages, various control structures are usually placed within the form HTML.
84Form validation, while simple to create, is generally very messy and tedious to implement.</p>
85
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]86<dfn>CodeIgniter provides a comprehensive validation framework that truly minimizes the amount of code you'll write.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]87It also removes all control structures from your form HTML, permitting it to be clean and free of code.</dfn>
88
89<h2>Overview</h2>
90
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]91<p>In order to implement CodeIgniter's form validation you'll need three things:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]92
93<ol>
94<li>A <a href="../general/views.html">View</a> file containing the form.</li>
95<li>A View file containing a "success" message to be displayed upon successful submission.</li>
96<li>A <a href="../general/controllers.html">controller</a> function to receive and process the submitted data.</li>
97</ol>
98
99<p>Let's create those three things, using a member sign-up form as the example.</p>
100
101<h2>The Form</h2>
102
103<p>Using a text editor, create a form called <dfn>myform.php</dfn>. In it, place this code and save it to your <samp>applications/views/</samp>
104folder:</p>
105
106
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]107<textarea class="textarea" style="width:100%" cols="50" rows="30">&lt;html>
108&lt;head>
109&lt;title>My Form&lt;/title>
110&lt;/head>
111&lt;body>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]112
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]113&lt;?php echo $this->validation->error_string; ?>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]114
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]115&lt;?php echo form_open('form'); ?>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]116
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]117&lt;h5>Username&lt;/h5>
118&lt;input type="text" name="username" value="" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]119
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]120&lt;h5>Password&lt;/h5>
121&lt;input type="text" name="password" value="" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]122
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]123&lt;h5>Password Confirm&lt;/h5>
124&lt;input type="text" name="passconf" value="" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]125
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]126&lt;h5>Email Address&lt;/h5>
127&lt;input type="text" name="email" value="" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]128
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]129&lt;div>&lt;input type="submit" value="Submit" />&lt;/div>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]130
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]131&lt;/form>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]132
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]133&lt;/body>
134&lt;/html>
135</textarea>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]136
137
138<h2>The Success Page</h2>
139
140
141<p>Using a text editor, create a form called <dfn>formsuccess.php</dfn>. In it, place this code and save it to your <samp>applications/views/</samp>
142folder:</p>
143
144
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]145<textarea class="textarea" style="width:100%" cols="50" rows="14">
146&lt;html>
147&lt;head>
148&lt;title>My Form&lt;/title>
149&lt;/head>
150&lt;body>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]151
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]152&lt;h3>Your form was successfully submitted!&lt;/h3>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]153
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]154&lt;p>&lt;?php echo anchor('form', 'Try it again!'); ?>&lt;/p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]155
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]156&lt;/body>
157&lt;/html>
158</textarea>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]159
160
161<h2>The Controller</h2>
162
163<p>Using a text editor, create a controller called <dfn>form.php</dfn>. In it, place this code and save it to your <samp>applications/controllers/</samp>
164folder:</p>
165
166
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]167<textarea class="textarea" style="width:100%" cols="50" rows="21">&lt;?php
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]168
169class Form extends Controller {
170
171 function index()
172 {
173 $this->load->helper(array('form', 'url'));
174
175 $this->load->library('validation');
176
177 if ($this->validation->run() == FALSE)
178 {
179 $this->load->view('myform');
180 }
181 else
182 {
183 $this->load->view('formsuccess');
184 }
185 }
186}
187?></textarea>
188
189
190<h2>Try it!</h2>
191
192<p>To try your form, visit your site using a URL similar to this one:</p>
193
194<code>www.your-site.com/index.php/<var>form</var>/</code>
195
admine334c472006-10-21 19:44:22 +0000[diff] [blame]196<p><strong>If you submit the form you should simply see the form reload. That's because you haven't set up any validation
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]197rules yet, which we'll get to in a moment.</strong></p>
198
199
200<h2>Explanation</h2>
201
202<p>You'll notice several things about the above pages:</p>
203
204<p>The <dfn>form</dfn> (myform.php) is a standard web form with a couple exceptions:</p>
205
206<ol>
207<li>It uses a <dfn>form helper</dfn> to create the form opening.
208Technically, this isn't necessary. You could create the form using standard HTML. However, the benefit of using the helper
209is that it generates the action URL for you, based on the URL in your config file. This makes your application more portable
210and flexible in the event your URLs change.</li>
211
212<li>At the top of the form you'll notice the following variable:
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]213<code>&lt;?php echo $this->validation->error_string; ?&gt;</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]214
215<p>This variable will display any error messages sent back by the validator. If there are no messages it returns nothing.</p>
216</li>
217</ol>
218
219<p>The <dfn>controller</dfn> (form.php) has one function: <dfn>index()</dfn>. This function initializes the validation class and
admine334c472006-10-21 19:44:22 +0000[diff] [blame]220loads the <var>form helper</var> and <var>URL helper</var> used by your view files. It also <samp>runs</samp>
221the validation routine. Based on
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]222whether the validation was successful it either presents the form or the success page.</p>
223
224<p><strong>Since you haven't told the validation class to validate anything yet, it returns "false" (boolean false) by default. The <samp>run()</samp>
225function only returns "true" if it has successfully applied your rules without any of them failing.</strong></p>
226
227
228<h2>Setting Validation Rules</h2>
229
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]230<p>CodeIgniter lets you set as many validation rules as you need for a given field, cascading them in order, and it even lets you prep and pre-process the field data
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]231at the same time. Let's see it in action, we'll explain it afterwards.</p>
232
233<p>In your <dfn>controller</dfn> (form.php), add this code just below the validation initialization function:</p>
234
235<code>$rules['username'] = "required";<br />
236$rules['password'] = "required";<br />
237$rules['passconf'] = "required";<br />
238$rules['email'] = "required";<br />
239<br />
240$this->validation->set_rules($rules);</code>
241
242<p>Your controller should now look like this:</p>
243
244<textarea class="textarea" style="width:100%" cols="50" rows="28"><?php
245
246class Form extends Controller {
247
248 function index()
249 {
250 $this->load->helper(array('form', 'url'));
251
252 $this->load->library('validation');
253
254 $rules['username'] = "required";
255 $rules['password'] = "required";
256 $rules['passconf'] = "required";
257 $rules['email'] = "required";
258
259 $this->validation->set_rules($rules);
260
261 if ($this->validation->run() == FALSE)
262 {
263 $this->load->view('myform');
264 }
265 else
266 {
267 $this->load->view('formsuccess');
268 }
269 }
270}
271?></textarea>
272
273<p><dfn>Now submit the form with the fields blank and you should see the error message.
274If you submit the form with all the fields populated you'll see your success page.</dfn></p>
275
276<p class="important"><strong>Note:</strong> The form fields are not yet being re-populated with the data when
277there is an error. We'll get to that shortly, once we're through explaining the validation rules.</p>
278
279
280<h2>Changing the Error Delimiters</h2>
281
282<p>By default, the system adds a paragraph tag (&lt;p&gt;) around each error message shown. You can easily change these delimiters with
283this code, placed in your controller:</p>
284
285<code>$this->validation->set_error_delimiters('<kbd>&lt;div class="error"></kbd>', '<kbd>&lt;/div></kbd>');</code>
286
287<p>In this example, we've switched to using div tags.</p>
288
289<h2>Cascading Rules</h2>
290
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]291<p>CodeIgniter lets you pipe multiple rules together. Let's try it. Change your rules array like this:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]292
293
294<code>$rules['username'] = "required|min_length[5]|max_length[12]";<br />
295$rules['password'] = "required|matches[passconf]";<br />
296$rules['passconf'] = "required";<br />
297$rules['email'] = "required|valid_email";</code>
298
299<p>The above code requires that:</p>
300
301<ol>
302<li>The username field be no shorter than 5 characters and no longer than 12.</li>
303<li>The password field must match the password confirmation field.</li>
304<li>The email field must contain a valid email address.</li>
305</ol>
306
307<p>Give it a try!</p>
308
309<p class="important"><strong>Note:</strong> There are numerous rules available which you can read about in the validation reference.</p>
310
311
312<h2>Prepping Data</h2>
313
admine334c472006-10-21 19:44:22 +0000[diff] [blame]314<p>In addition to the validation functions like the ones we used above, you can also prep your data in various ways.
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]315For example, you can set up rules like this:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]316
317<code>$rules['username'] = "<kbd>trim</kbd>|required|min_length[5]|max_length[12]|<kbd>xss_clean</kbd>";<br />
318$rules['password'] = "<kbd>trim</kbd>|required|matches[passconf]|<kbd>md5</kbd>";<br />
319$rules['passconf'] = "<kbd>trim</kbd>|required";<br />
320$rules['email'] = "<kbd>trim</kbd>|required|valid_email";</code>
321
Derek Allard866b8132008-04-21 22:02:37 +0000[diff] [blame]322<p>In the above example, we are "trimming" the fields, converting the password to MD5, and running the username through
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]323the "xss_clean" function, which removes malicious data.</p>
324
325<p class="important"><strong>Any native PHP function that accepts one parameter can be used as a rule, like <dfn>htmlspecialchars</dfn>,
326<dfn>trim</dfn>, <dfn>MD5</dfn>, etc.</strong></p>
327
328<p><strong>Note:</strong> You will generally want to use the prepping functions <strong>after</strong>
329the validation rules so if there is an error, the original data will be shown in the form.</p>
330
331<h2>Callbacks: Your own Validation Functions</h2>
332
333<p>The validation system supports callbacks to your own validation functions. This permits you to extend the validation class
334to meet your needs. For example, if you need to run a database query to see if the user is choosing a unique username, you can
335create a callback function that does that. Let's create a simple example.</p>
336
337<p>In your controller, change the "username" rule to this:</p>
338
339<code>$rules['username'] = "callback_username_check"; </code>
340
341<p>Then add a new function called <dfn>username_check</dfn> to your controller. Here's how your controller should look:</p>
342
343
344<textarea class="textarea" style="width:100%" cols="50" rows="44"><?php
345
346class Form extends Controller {
347
348 function index()
349 {
350 $this->load->helper(array('form', 'url'));
351
352 $this->load->library('validation');
353
354 $rules['username'] = "callback_username_check";
355 $rules['password'] = "required";
356 $rules['passconf'] = "required";
357 $rules['email'] = "required";
358
359 $this->validation->set_rules($rules);
360
361 if ($this->validation->run() == FALSE)
362 {
363 $this->load->view('myform');
364 }
365 else
366 {
367 $this->load->view('formsuccess');
368 }
369 }
370
371 function username_check($str)
372 {
373 if ($str == 'test')
374 {
375 $this->validation->set_message('username_check', 'The %s field can not be the word "test"');
376 return FALSE;
377 }
378 else
379 {
380 return TRUE;
381 }
382 }
383
384}
385?></textarea>
386
387<p>Reload your form and submit it with the word "test" as the username. You can see that the form field data was passed to your
388callback function for you to process.</p>
389
390<p><strong>To invoke a callback just put the function name in a rule, with "callback_" as the rule prefix.</strong></p>
391
admine334c472006-10-21 19:44:22 +0000[diff] [blame]392<p>The error message was set using the <dfn>$this->validation->set_message</dfn> function.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]393Just remember that the message key (the first parameter) must match your function name.</p>
394
admine334c472006-10-21 19:44:22 +0000[diff] [blame]395<p class="important"><strong>Note:</strong> You can apply your own custom error messages to any rule, just by setting the
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]396message similarly. For example, to change the message for the "required" rule you will do this:</p>
397
398<code>$this->validation->set_message('required', 'Your custom message here');</code>
399
400<h2>Re-populating the form</h2>
401
admine334c472006-10-21 19:44:22 +0000[diff] [blame]402<p>Thus far we have only been dealing with errors. It's time to repopulate the form field with the submitted data.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]403This is done similarly to your rules. Add the following code to your controller, just below your rules:</p>
404
405<code>$fields['username'] = 'Username';<br />
406$fields['password'] = 'Password';<br />
407$fields['passconf'] = 'Password Confirmation';<br />
408$fields['email'] = 'Email Address';<br />
409<br />
410$this->validation->set_fields($fields);</code>
411
admine334c472006-10-21 19:44:22 +0000[diff] [blame]412<p>The array keys are the actual names of the form fields, the value represents the full name that you want shown in the
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]413error message.</p>
414
415<p>The index function of your controller should now look like this:</p>
416
417
418<textarea class="textarea" style="width:100%" cols="50" rows="30">function index()
419{
420 $this->load->helper(array('form', 'url'));
421
422 $this->load->library('validation');
423
424 $rules['username'] = "required";
425 $rules['password'] = "required";
426 $rules['passconf'] = "required";
427 $rules['email'] = "required";
428
429 $this->validation->set_rules($rules);
430
431 $fields['username'] = 'Username';
432 $fields['password'] = 'Password';
433 $fields['passconf'] = 'Password Confirmation';
434 $fields['email'] = 'Email Address';
435
436 $this->validation->set_fields($fields);
437
438 if ($this->validation->run() == FALSE)
439 {
440 $this->load->view('myform');
441 }
442 else
443 {
444 $this->load->view('formsuccess');
445 }
446}</textarea>
447
448
Derek Allard866b8132008-04-21 22:02:37 +0000[diff] [blame]449<p>Now open your <dfn>myform.php</dfn> view file and update the value in each field so that it has an attribute corresponding to its name:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]450
451
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]452<textarea class="textarea" style="width:100%" cols="50" rows="30">
453&lt;html>
454&lt;head>
455&lt;title>My Form&lt;/title>
456&lt;/head>
457&lt;body>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]458
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]459&lt;?php echo $this->validation->error_string; ?>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]460
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]461&lt;?php echo form_open('form'); ?>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]462
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]463&lt;h5>Username&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]464&lt;input type="text" name="username" value="&lt;?php echo $this->validation->username;?>" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]465
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]466&lt;h5>Password&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]467&lt;input type="text" name="password" value="&lt;?php echo $this->validation->password;?>" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]468
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]469&lt;h5>Password Confirm&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]470&lt;input type="text" name="passconf" value="&lt;?php echo $this->validation->passconf;?>" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]471
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]472&lt;h5>Email Address&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]473&lt;input type="text" name="email" value="&lt;?php echo $this->validation->email;?>" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]474
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]475&lt;div>&lt;input type="submit" value="Submit" />&lt;/div>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]476
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]477&lt;/form>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]478
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]479&lt;/body>
480&lt;/html>
481</textarea>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]482
483
484<p>Now reload your page and submit the form so that it triggers an error. Your form fields should be populated
485and the error messages will contain a more relevant field name.</p>
486
487
488
489<h2>Showing Errors Individually</h2>
490
491<p>If you prefer to show an error message next to each form field, rather than as a list, you can change your form so that it looks like this:</p>
492
493
Derek Allardc2c25612007-07-19 23:12:49 +0000[diff] [blame]494<textarea class="textarea" style="width:100%" cols="50" rows="20">
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]495&lt;h5>Username&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]496&lt;?php echo $this->validation->username_error; ?>
497&lt;input type="text" name="username" value="&lt;?php echo $this->validation->username;?>" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]498
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]499&lt;h5>Password&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]500&lt;?php echo $this->validation->password_error; ?>
501&lt;input type="text" name="password" value="&lt;?php echo $this->validation->password;?>" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]502
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]503&lt;h5>Password Confirm&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]504&lt;?php echo $this->validation->passconf_error; ?>
505&lt;input type="text" name="passconf" value="&lt;?php echo $this->validation->passconf;?>" size="50" />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]506
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]507&lt;h5>Email Address&lt;/h5>
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]508&lt;?php echo $this->validation->email_error; ?>
509&lt;input type="text" name="email" value="&lt;?php echo $this->validation->email;?>" size="50" /></textarea>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]510
511<p>If there are no errors, nothing will be shown. If there is an error, the message will appear, wrapped in the delimiters you
512have set (&lt;p> tags by default).</p>
513
514<p class="important"><strong>Note: </strong>To display errors this way you must remember to set your fields using the <kbd>$this->validation->set_fields</kbd>
admine334c472006-10-21 19:44:22 +0000[diff] [blame]515function described earlier. The errors will be turned into variables that have "_error" after your field name.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]516For example, your "username" error will be available at:<br /><dfn>$this->validation->username_error</dfn>.</p>
517
518
519<h2>Rule Reference</h2>
520
521<p>The following is a list of all the native rules that are available to use:</p>
522
523
524
525<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
526<tr>
527<th>Rule</th>
528<th>Parameter</th>
529<th>Description</th>
530<th>Example</th>
531</tr><tr>
532
533<td class="td"><strong>required</strong></td>
534<td class="td">No</td>
535<td class="td">Returns FALSE if the form element is empty.</td>
536<td class="td">&nbsp;</td>
537</tr><tr>
538
539<td class="td"><strong>matches</strong></td>
540<td class="td">Yes</td>
541<td class="td">Returns FALSE if the form element does not match the one in the parameter.</td>
542<td class="td">matches[form_item]</td>
543</tr><tr>
544
545<td class="td"><strong>min_length</strong></td>
546<td class="td">Yes</td>
547<td class="td">Returns FALSE if the form element is shorter then the parameter value.</td>
548<td class="td">min_length[6]</td>
549</tr><tr>
550
551<td class="td"><strong>max_length</strong></td>
552<td class="td">Yes</td>
553<td class="td">Returns FALSE if the form element is longer then the parameter value.</td>
554<td class="td">max_length[12]</td>
555</tr><tr>
556
557<td class="td"><strong>exact_length</strong></td>
558<td class="td">Yes</td>
559<td class="td">Returns FALSE if the form element is not exactly the parameter value.</td>
560<td class="td">exact_length[8]</td>
561</tr><tr>
562
563<td class="td"><strong>alpha</strong></td>
564<td class="td">No</td>
565<td class="td">Returns FALSE if the form element contains anything other than alphabetical characters.</td>
566<td class="td">&nbsp;</td>
567</tr><tr>
568
569<td class="td"><strong>alpha_numeric</strong></td>
570<td class="td">No</td>
571<td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters.</td>
572<td class="td">&nbsp;</td>
573</tr><tr>
574
575<td class="td"><strong>alpha_dash</strong></td>
576<td class="td">No</td>
577<td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters, underscores or dashes.</td>
578<td class="td">&nbsp;</td>
Derek Allard12f9cc82008-01-22 07:21:32 +0000[diff] [blame]579</tr>
580<tr>
581 <td class="td"><strong>numeric</strong></td>
582 <td class="td">No</td>
583 <td class="td">Returns FALSE if the form element contains anything other than numeric characters.</td>
584 <td class="td">&nbsp;</td>
585</tr>
586<tr>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]587
Derek Allard12f9cc82008-01-22 07:21:32 +0000[diff] [blame]588<td class="td"><strong>integer</strong></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]589<td class="td">No</td>
Derek Allard12f9cc82008-01-22 07:21:32 +0000[diff] [blame]590<td class="td">Returns FALSE if the form element contains anything other than an integer.</td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]591<td class="td">&nbsp;</td>
592</tr><tr>
593
594<td class="td"><strong>valid_email</strong></td>
595<td class="td">No</td>
596<td class="td">Returns FALSE if the form element does not contain a valid email address.</td>
597<td class="td">&nbsp;</td>
598</tr>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]599<tr>
admin10c3f412006-10-08 07:21:12 +0000[diff] [blame]600<td class="td"><strong>valid_ip</strong></td>
601<td class="td">No</td>
602<td class="td">Returns FALSE if the supplied IP is not valid.</td>
603<td class="td">&nbsp;</td>
604</tr>
Derek Jones15130ca2008-01-28 15:54:45 +0000[diff] [blame]605<tr>
606 <td class="td"><strong>valid_base64</strong></td>
607 <td class="td">No</td>
608 <td class="td">Returns FALSE if the supplied string contains anything other than valid Base64 characters.</td>
609 <td class="td">&nbsp;</td>
610</tr>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]611</table>
612
Derek Allard78729d82008-02-01 16:58:38 +0000[diff] [blame]613<p><strong>Note:</strong> These rules can also be called as discrete functions. For example:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]614
615<code>$this->validation->required($string);</code>
616
617<p class="important"><strong>Note:</strong> You can also use any native PHP functions that permit one parameter.</p>
618
619
620
621<h2>Prepping Reference</h2>
622
623<p>The following is a list of all the prepping functions that are available to use:</p>
624
625
626
627<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
628<tr>
629<th>Name</th>
630<th>Parameter</th>
631<th>Description</th>
632</tr><tr>
633
634<td class="td"><strong>xss_clean</strong></td>
635<td class="td">No</td>
636<td class="td">Runs the data through the XSS filtering function, described in the <a href="input.html">Input Class</a> page.</td>
637</tr><tr>
638
639<td class="td"><strong>prep_for_form</strong></td>
640<td class="td">No</td>
641<td class="td">Converts special characters so that HTML data can be shown in a form field without breaking it.</td>
642</tr><tr>
643
644<td class="td"><strong>prep_url</strong></td>
645<td class="td">No</td>
646<td class="td">Adds "http://" to URLs if missing.</td>
647</tr><tr>
648
649<td class="td"><strong>strip_image_tags</strong></td>
650<td class="td">No</td>
651<td class="td">Strips the HTML from image tags leaving the raw URL.</td>
652</tr><tr>
653
654<td class="td"><strong>encode_php_tags</strong></td>
655<td class="td">No</td>
656<td class="td">Converts PHP tags to entities.</td>
657</tr>
658
659</table>
660
661<p class="important"><strong>Note:</strong> You can also use any native PHP functions that permit one parameter,
662like <kbd>trim</kbd>, <kbd>htmlspecialchars</kbd>, <kbd>urldecode</kbd>, etc.</p>
663
664
665<h2>Setting Custom Error Messages</h2>
666
667<p>All of the native error messages are located in the following language file: <dfn>language/english/validation_lang.php</dfn></p>
668
669<p>To set your own custom message you can either edit that file, or use the following function:</p>
670
671<code>$this->validation->set_message('<var>rule</var>', '<var>Error Message</var>');</code>
672
673<p>Where <var>rule</var> corresponds to the name of a particular rule, and <var>Error Message</var> is the text you would like displayed.</p>
674
675
admin82654c32006-10-20 23:07:40 +0000[diff] [blame]676<h2>Dealing with Select Menus, Radio Buttons, and Checkboxes</h2>
677
admine334c472006-10-21 19:44:22 +0000[diff] [blame]678<p>If you use select menus, radio buttons or checkboxes, you will want the state of
admine7e1dcd2006-10-21 18:04:01 +0000[diff] [blame]679these items to be retained in the event of an error. The Validation class has three functions that help you do this:</p>
admin82654c32006-10-20 23:07:40 +0000[diff] [blame]680
681<h2>set_select()</h2>
682
683<p>Permits you to display the menu item that was selected. The first parameter
684must contain the name of the select menu, the second parameter must contain the value of
685each item. Example:</p>
686
687<code>
688&lt;select name="myselect"><br />
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]689&lt;option value="one" <dfn>&lt;?php echo $this->validation->set_select('myselect', 'one'); ?></dfn> >One&lt;/option><br />
690&lt;option value="two" <dfn>&lt;?php echo $this->validation->set_select('myselect', 'two'); ?></dfn> >Two&lt;/option><br />
691&lt;option value="three" <dfn>&lt;?php echo $this->validation->set_select('myselect', 'three'); ?></dfn> >Three&lt;/option><br />
admin82654c32006-10-20 23:07:40 +0000[diff] [blame]692&lt;/select>
693</code>
694
695
696<h2>set_checkbox()</h2>
697
698<p>Permits you to display a checkbox in the state it was submitted. The first parameter
699must contain the name of the checkbox, the second parameter must contain its value. Example:</p>
700
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]701<code>&lt;input type="checkbox" name="mycheck" value="1" <dfn>&lt;?php echo $this->validation->set_checkbox('mycheck', '1'); ?></dfn> /></code>
admin82654c32006-10-20 23:07:40 +0000[diff] [blame]702
703
704<h2>set_radio()</h2>
705
706<p>Permits you to display radio buttons in the state they were submitted. The first parameter
707must contain the name of the radio button, the second parameter must contain its value. Example:</p>
708
Derek Allard2f955972008-04-24 13:12:46 +0000[diff] [blame^]709<code>&lt;input type="radio" name="myradio" value="1" <dfn>&lt;?php echo $this->validation->set_radio('myradio', '1'); ?></dfn> /></code>
admin82654c32006-10-20 23:07:40 +0000[diff] [blame]710
711
712
713
714
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]715</div>
716<!-- END CONTENT -->
717
718
719<div id="footer">
720<p>
Derek Allard9da4dbc2007-04-03 11:39:35 +0000[diff] [blame]721Previous Topic:&nbsp;&nbsp;<a href="user_agent.html">User Agent Class</a>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]722&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
723<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
724<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
725Next Topic:&nbsp;&nbsp;<a href="xmlrpc.html">XML-RPC Class</a>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]726</p>
Derek Jones07870432008-02-13 03:49:26 +0000[diff] [blame]727<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]728</div>
729
730</body>
731</html>