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