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