projects / z_archive / KronOS.git / blame
| Commit | Line | Data |
|---|---|---|
| 59c06b17 CS |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 2 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | |
| 3 | <head> | |
| 4 | ||
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> | |
| 6 | <title>Form Validation : CodeIgniter User Guide</title> | |
| 7 | ||
| 8 | <style type='text/css' media='all'>@import url('../userguide.css');</style> | |
| 9 | <link rel='stylesheet' type='text/css' media='all' href='../userguide.css' /> | |
| 10 | ||
| 11 | <script type="text/javascript" src="../nav/nav.js"></script> | |
| 12 | <script type="text/javascript" src="../nav/prototype.lite.js"></script> | |
| 13 | <script type="text/javascript" src="../nav/moo.fx.js"></script> | |
| 14 | <script type="text/javascript" src="../nav/user_guide_menu.js"></script> | |
| 15 | ||
| 16 | <meta http-equiv='expires' content='-1' /> | |
| 17 | <meta http-equiv= 'pragma' content='no-cache' /> | |
| 18 | <meta name='robots' content='all' /> | |
| 19 | <meta name='author' content='ExpressionEngine Dev Team' /> | |
| 20 | <meta name='description' content='CodeIgniter User Guide' /> | |
| 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_darker.jpg" width="154" height="43" 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> | |
| 30 | <td><h1>CodeIgniter User Guide Version 2.1.3</h1></td> | |
| 31 | <td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td> | |
| 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"> | |
| 42 | <a href="http://codeigniter.com/">CodeIgniter Home</a> › | |
| 43 | <a href="../index.html">User Guide Home</a> › | |
| 44 | Form Validation | |
| 45 | </td> | |
| 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 <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <input type="submit" class="submit" name="sa" value="Go" /></form></td> | |
| 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 | ||
| 59 | <p>CodeIgniter provides a comprehensive form validation and data prepping class that helps minimize the amount of code you'll write.</p> | |
| 60 | ||
| 61 | <ul> | |
| 62 | <li><a href="#overview">Overview</a></li> | |
| 63 | <li><a href="#tutorial">Form Validation Tutorial</a> | |
| 64 | ||
| 65 | <ul> | |
| 66 | <li><a href="#theform">The Form</a></li> | |
| 67 | <li><a href="#thesuccesspage">The Success Page</a></li> | |
| 68 | <li><a href="#thecontroller">The Controller</a></li> | |
| 69 | <li><a href="#validationrules">Setting Validation Rules</a></li> | |
| 70 | <li><a href="#validationrulesasarray">Setting Validation Rules Using an Array</a></li> | |
| 71 | <li><a href="#cascadingrules">Cascading Rules</a></li> | |
| 72 | <li><a href="#preppingdata">Prepping Data</a></li> | |
| 73 | <li><a href="#repopulatingform">Re-populating the Form</a></li> | |
| 74 | <li><a href="#callbacks">Callbacks</a></li> | |
| 75 | <li><a href="#settingerrors">Setting Error Messages</a></li> | |
| 76 | <li><a href="#errordelimiters">Changing the Error Delimiters</a></li> | |
| 77 | <li><a href="#translatingfn">Translating Field Names</a></li> | |
| 78 | <li><a href="#individualerrors">Showing Errors Individually</a></li> | |
| 79 | <li><a href="#savingtoconfig">Saving Sets of Validation Rules to a Config File</a></li> | |
| 80 | <li><a href="#arraysasfields">Using Arrays as Field Names</a></li> | |
| 81 | </ul> | |
| 82 | </li> | |
| 83 | <li><a href="#rulereference">Rule Reference</a></li> | |
| 84 | <li><a href="#preppingreference">Prepping Reference</a></li> | |
| 85 | <li><a href="#functionreference">Function Reference</a></li> | |
| 86 | <li><a href="#helperreference">Helper Reference</a></li> | |
| 87 | ||
| 88 | </ul> | |
| 89 | ||
| 90 | ||
| 91 | ||
| 92 | ||
| 93 | ||
| 94 | ||
| 95 | <p> </p> | |
| 96 | ||
| 97 | <a name="overview"></a> | |
| 98 | <h1>Overview</h1> | |
| 99 | ||
| 100 | ||
| 101 | <p>Before explaining CodeIgniter's approach to data validation, let's describe the ideal scenario:</p> | |
| 102 | ||
| 103 | <ol> | |
| 104 | <li>A form is displayed.</li> | |
| 105 | <li>You fill it in and submit it.</li> | |
| 106 | <li>If you submitted something invalid, or perhaps missed a required item, the form is redisplayed containing your data | |
| 107 | along with an error message describing the problem.</li> | |
| 108 | <li>This process continues until you have submitted a valid form.</li> | |
| 109 | </ol> | |
| 110 | ||
| 111 | <p>On the receiving end, the script must:</p> | |
| 112 | ||
| 113 | <ol> | |
| 114 | <li>Check for required data.</li> | |
| 115 | <li>Verify that the data is of the correct type, and meets the correct criteria. For example, if a username is submitted | |
| 116 | it must be validated to contain only permitted characters. It must be of a minimum length, | |
| 117 | and not exceed a maximum length. The username can't be someone else's existing username, or perhaps even a reserved word. Etc.</li> | |
| 118 | <li>Sanitize the data for security.</li> | |
| 119 | <li>Pre-format the data if needed (Does the data need to be trimmed? HTML encoded? Etc.)</li> | |
| 120 | <li>Prep the data for insertion in the database.</li> | |
| 121 | </ol> | |
| 122 | ||
| 123 | ||
| 124 | <p>Although there is nothing terribly complex about the above process, it usually requires a significant | |
| 125 | amount of code, and to display error messages, various control structures are usually placed within the form HTML. | |
| 126 | Form validation, while simple to create, is generally very messy and tedious to implement.</p> | |
| 127 | ||
| 128 | <p> </p> | |
| 129 | ||
| 130 | ||
| 131 | <a name="tutorial"></a> | |
| 132 | <h1>Form Validation Tutorial</h1> | |
| 133 | ||
| 134 | <p>What follows is a "hands on" tutorial for implementing CodeIgniters Form Validation.</p> | |
| 135 | ||
| 136 | ||
| 137 | <p>In order to implement form validation you'll need three things:</p> | |
| 138 | ||
| 139 | <ol> | |
| 140 | <li>A <a href="../general/views.html">View</a> file containing a form.</li> | |
| 141 | <li>A View file containing a "success" message to be displayed upon successful submission.</li> | |
| 142 | <li>A <a href="../general/controllers.html">controller</a> function to receive and process the submitted data.</li> | |
| 143 | </ol> | |
| 144 | ||
| 145 | <p>Let's create those three things, using a member sign-up form as the example.</p> | |
| 146 | ||
| 147 | ||
| 148 | ||
| 149 | <a name="theform"></a> | |
| 150 | ||
| 151 | <h2>The Form</h2> | |
| 152 | ||
| 153 | <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> | |
| 154 | folder:</p> | |
| 155 | ||
| 156 | ||
| 157 | <textarea class="textarea" style="width:100%" cols="50" rows="30"><html> | |
| 158 | <head> | |
| 159 | <title>My Form</title> | |
| 160 | </head> | |
| 161 | <body> | |
| 162 | ||
| 163 | <?php echo validation_errors(); ?> | |
| 164 | ||
| 165 | <?php echo form_open('form'); ?> | |
| 166 | ||
| 167 | <h5>Username</h5> | |
| 168 | <input type="text" name="username" value="" size="50" /> | |
| 169 | ||
| 170 | <h5>Password</h5> | |
| 171 | <input type="text" name="password" value="" size="50" /> | |
| 172 | ||
| 173 | <h5>Password Confirm</h5> | |
| 174 | <input type="text" name="passconf" value="" size="50" /> | |
| 175 | ||
| 176 | <h5>Email Address</h5> | |
| 177 | <input type="text" name="email" value="" size="50" /> | |
| 178 | ||
| 179 | <div><input type="submit" value="Submit" /></div> | |
| 180 | ||
| 181 | </form> | |
| 182 | ||
| 183 | </body> | |
| 184 | </html> | |
| 185 | </textarea> | |
| 186 | ||
| 187 | ||
| 188 | ||
| 189 | ||
| 190 | <a name="thesuccesspage"></a> | |
| 191 | <h2>The Success Page</h2> | |
| 192 | ||
| 193 | ||
| 194 | <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> | |
| 195 | folder:</p> | |
| 196 | ||
| 197 | ||
| 198 | <textarea class="textarea" style="width:100%" cols="50" rows="14"> | |
| 199 | <html> | |
| 200 | <head> | |
| 201 | <title>My Form</title> | |
| 202 | </head> | |
| 203 | <body> | |
| 204 | ||
| 205 | <h3>Your form was successfully submitted!</h3> | |
| 206 | ||
| 207 | <p><?php echo anchor('form', 'Try it again!'); ?></p> | |
| 208 | ||
| 209 | </body> | |
| 210 | </html> | |
| 211 | </textarea> | |
| 212 | ||
| 213 | ||
| 214 | ||
| 215 | <a name="thecontroller"></a> | |
| 216 | <h2>The Controller</h2> | |
| 217 | ||
| 218 | <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> | |
| 219 | folder:</p> | |
| 220 | ||
| 221 | ||
| 222 | <textarea class="textarea" style="width:100%" cols="50" rows="21"><?php | |
| 223 | ||
| 224 | class Form extends CI_Controller { | |
| 225 | ||
| 226 | function index() | |
| 227 | { | |
| 228 | $this->load->helper(array('form', 'url')); | |
| 229 | ||
| 230 | $this->load->library('form_validation'); | |
| 231 | ||
| 232 | if ($this->form_validation->run() == FALSE) | |
| 233 | { | |
| 234 | $this->load->view('myform'); | |
| 235 | } | |
| 236 | else | |
| 237 | { | |
| 238 | $this->load->view('formsuccess'); | |
| 239 | } | |
| 240 | } | |
| 241 | } | |
| 242 | ?></textarea> | |
| 243 | ||
| 244 | ||
| 245 | <h2>Try it!</h2> | |
| 246 | ||
| 247 | <p>To try your form, visit your site using a URL similar to this one:</p> | |
| 248 | ||
| 249 | <code>example.com/index.php/<var>form</var>/</code> | |
| 250 | ||
| 251 | <p><dfn>If you submit the form you should simply see the form reload. That's because you haven't set up any validation | |
| 252 | rules yet.</dfn></p> | |
| 253 | ||
| 254 | <p><strong>Since you haven't told the Form Validation class to validate anything yet, it returns <kbd>FALSE</kbd> (boolean false) by default. The <samp>run()</samp> | |
| 255 | function only returns <kbd>TRUE</kbd> if it has successfully applied your rules without any of them failing.</strong></p> | |
| 256 | ||
| 257 | ||
| 258 | <h2>Explanation</h2> | |
| 259 | ||
| 260 | <p>You'll notice several things about the above pages:</p> | |
| 261 | ||
| 262 | <p>The <dfn>form</dfn> (myform.php) is a standard web form with a couple exceptions:</p> | |
| 263 | ||
| 264 | <ol> | |
| 265 | <li>It uses a <dfn>form helper</dfn> to create the form opening. | |
| 266 | Technically, this isn't necessary. You could create the form using standard HTML. However, the benefit of using the helper | |
| 267 | is that it generates the action URL for you, based on the URL in your config file. This makes your application more portable in the event your URLs change.</li> | |
| 268 | ||
| 269 | <li>At the top of the form you'll notice the following function call: | |
| 270 | <code><?php echo validation_errors(); ?></code> | |
| 271 | ||
| 272 | <p>This function will return any error messages sent back by the validator. If there are no messages it returns an empty string.</p> | |
| 273 | </li> | |
| 274 | </ol> | |
| 275 | ||
| 276 | <p>The <dfn>controller</dfn> (form.php) has one function: <dfn>index()</dfn>. This function initializes the validation class and | |
| 277 | loads the <var>form helper</var> and <var>URL helper</var> used by your view files. It also <samp>runs</samp> | |
| 278 | the validation routine. Based on | |
| 279 | whether the validation was successful it either presents the form or the success page.</p> | |
| 280 | ||
| 281 | ||
| 282 | ||
| 283 | ||
| 284 | <a name="validationrules"></a> | |
| 285 | ||
| 286 | <h2>Setting Validation Rules</h2> | |
| 287 | ||
| 288 | <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 | |
| 289 | at the same time. To set validation rules you will use the <dfn>set_rules()</dfn> function:</p> | |
| 290 | ||
| 291 | <code>$this->form_validation->set_rules();</code> | |
| 292 | ||
| 293 | <p>The above function takes <strong>three</strong> parameters as input:</p> | |
| 294 | ||
| 295 | <ol> | |
| 296 | <li>The field name - the exact name you've given the form field.</li> | |
| 297 | <li>A "human" name for this field, which will be inserted into the error message. For example, if your field is named "user" you might give it a human name of "Username". <strong>Note:</strong> If you would like the field name to be stored in a language file, please see <a href="#translatingfn">Translating Field Names</a>.</li> | |
| 298 | <li>The validation rules for this form field.</li> | |
| 299 | </ol> | |
| 300 | ||
| 301 | ||
| 302 | <p><br />Here is an example. In your <dfn>controller</dfn> (form.php), add this code just below the validation initialization function:</p> | |
| 303 | ||
| 304 | <code> | |
| 305 | $this->form_validation->set_rules('username', 'Username', 'required');<br /> | |
| 306 | $this->form_validation->set_rules('password', 'Password', 'required');<br /> | |
| 307 | $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required');<br /> | |
| 308 | $this->form_validation->set_rules('email', 'Email', 'required');<br /> | |
| 309 | </code> | |
| 310 | ||
| 311 | <p>Your controller should now look like this:</p> | |
| 312 | ||
| 313 | <textarea class="textarea" style="width:100%" cols="50" rows="28"><?php | |
| 314 | ||
| 315 | class Form extends CI_Controller { | |
| 316 | ||
| 317 | function index() | |
| 318 | { | |
| 319 | $this->load->helper(array('form', 'url')); | |
| 320 | ||
| 321 | $this->load->library('form_validation'); | |
| 322 | ||
| 323 | $this->form_validation->set_rules('username', 'Username', 'required'); | |
| 324 | $this->form_validation->set_rules('password', 'Password', 'required'); | |
| 325 | $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required'); | |
| 326 | $this->form_validation->set_rules('email', 'Email', 'required'); | |
| 327 | ||
| 328 | if ($this->form_validation->run() == FALSE) | |
| 329 | { | |
| 330 | $this->load->view('myform'); | |
| 331 | } | |
| 332 | else | |
| 333 | { | |
| 334 | $this->load->view('formsuccess'); | |
| 335 | } | |
| 336 | } | |
| 337 | } | |
| 338 | ?></textarea> | |
| 339 | ||
| 340 | <p><dfn>Now submit the form with the fields blank and you should see the error messages. | |
| 341 | If you submit the form with all the fields populated you'll see your success page.</dfn></p> | |
| 342 | ||
| 343 | <p class="important"><strong>Note:</strong> The form fields are not yet being re-populated with the data when | |
| 344 | there is an error. We'll get to that shortly.</p> | |
| 345 | ||
| 346 | ||
| 347 | ||
| 348 | ||
| 349 | <a name="validationrulesasarray"></a> | |
| 350 | <h2>Setting Rules Using an Array</h2> | |
| 351 | ||
| 352 | <p>Before moving on it should be noted that the rule setting function can be passed an array if you prefer to set all your rules in one action. | |
| 353 | If you use this approach you must name your array keys as indicated:</p> | |
| 354 | ||
| 355 | <code> | |
| 356 | $config = array(<br /> | |
| 357 | array(<br /> | |
| 358 | 'field' => 'username', <br /> | |
| 359 | 'label' => 'Username', <br /> | |
| 360 | 'rules' => 'required'<br /> | |
| 361 | ),<br /> | |
| 362 | array(<br /> | |
| 363 | 'field' => 'password', <br /> | |
| 364 | 'label' => 'Password', <br /> | |
| 365 | 'rules' => 'required'<br /> | |
| 366 | ),<br /> | |
| 367 | array(<br /> | |
| 368 | 'field' => 'passconf', <br /> | |
| 369 | 'label' => 'Password Confirmation', <br /> | |
| 370 | 'rules' => 'required'<br /> | |
| 371 | ), <br /> | |
| 372 | array(<br /> | |
| 373 | 'field' => 'email', <br /> | |
| 374 | 'label' => 'Email', <br /> | |
| 375 | 'rules' => 'required'<br /> | |
| 376 | )<br /> | |
| 377 | );<br /> | |
| 378 | <br /> | |
| 379 | $this->form_validation->set_rules($config); | |
| 380 | </code> | |
| 381 | ||
| 382 | ||
| 383 | ||
| 384 | ||
| 385 | ||
| 386 | ||
| 387 | <a name="cascadingrules"></a> | |
| 388 | <h2>Cascading Rules</h2> | |
| 389 | ||
| 390 | <p>CodeIgniter lets you pipe multiple rules together. Let's try it. Change your rules in the third parameter of rule setting function, like this:</p> | |
| 391 | ||
| 392 | <code> | |
| 393 | $this->form_validation->set_rules('username', 'Username', 'required|min_length[5]|max_length[12]|is_unique[users.username]');<br /> | |
| 394 | $this->form_validation->set_rules('password', 'Password', 'required|matches[passconf]');<br /> | |
| 395 | $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required');<br /> | |
| 396 | $this->form_validation->set_rules('email', 'Email', 'required|valid_email|is_unique[users.email]');<br /> | |
| 397 | </code> | |
| 398 | ||
| 399 | <p>The above code sets the following rules:</p> | |
| 400 | ||
| 401 | <ol> | |
| 402 | <li>The username field be no shorter than 5 characters and no longer than 12.</li> | |
| 403 | <li>The password field must match the password confirmation field.</li> | |
| 404 | <li>The email field must contain a valid email address.</li> | |
| 405 | </ol> | |
| 406 | ||
| 407 | <p>Give it a try! Submit your form without the proper data and you'll see new error messages that correspond to your new rules. | |
| 408 | There are numerous rules available which you can read about in the validation reference.</p> | |
| 409 | ||
| 410 | ||
| 411 | ||
| 412 | <a name="preppingdata"></a> | |
| 413 | <h2>Prepping Data</h2> | |
| 414 | ||
| 415 | <p>In addition to the validation functions like the ones we used above, you can also prep your data in various ways. | |
| 416 | For example, you can set up rules like this:</p> | |
| 417 | ||
| 418 | <code> | |
| 419 | $this->form_validation->set_rules('username', 'Username', '<kbd>trim</kbd>|required|min_length[5]|max_length[12]|<kbd>xss_clean</kbd>');<br /> | |
| 420 | $this->form_validation->set_rules('password', 'Password', '<kbd>trim</kbd>|required|matches[passconf]|<kbd>md5</kbd>');<br /> | |
| 421 | $this->form_validation->set_rules('passconf', 'Password Confirmation', '<kbd>trim</kbd>|required');<br /> | |
| 422 | $this->form_validation->set_rules('email', 'Email', '<kbd>trim</kbd>|required|valid_email');<br /> | |
| 423 | </code> | |
| 424 | ||
| 425 | ||
| 426 | <p>In the above example, we are "trimming" the fields, converting the password to MD5, and running the username through | |
| 427 | the "xss_clean" function, which removes malicious data.</p> | |
| 428 | ||
| 429 | <p><strong>Any native PHP function that accepts one parameter can be used as a rule, like <dfn>htmlspecialchars</dfn>, | |
| 430 | <dfn>trim</dfn>, <dfn>MD5</dfn>, etc.</strong></p> | |
| 431 | ||
| 432 | <p><strong>Note:</strong> You will generally want to use the prepping functions <strong>after</strong> | |
| 433 | the validation rules so if there is an error, the original data will be shown in the form.</p> | |
| 434 | ||
| 435 | ||
| 436 | ||
| 437 | ||
| 438 | <a name="repopulatingform"></a> | |
| 439 | <h2>Re-populating the form</h2> | |
| 440 | ||
| 441 | <p>Thus far we have only been dealing with errors. It's time to repopulate the form field with the submitted data. CodeIgniter offers several helper functions | |
| 442 | that permit you to do this. The one you will use most commonly is:</p> | |
| 443 | ||
| 444 | <code>set_value('field name')</code> | |
| 445 | ||
| 446 | ||
| 447 | <p>Open your <dfn>myform.php</dfn> view file and update the <strong>value</strong> in each field using the <dfn>set_value()</dfn> function:</p> | |
| 448 | ||
| 449 | <p><strong>Don't forget to include each field name in the <dfn>set_value()</dfn> functions!</strong></p> | |
| 450 | ||
| 451 | ||
| 452 | <textarea class="textarea" style="width:100%" cols="50" rows="30"> | |
| 453 | <html> | |
| 454 | <head> | |
| 455 | <title>My Form</title> | |
| 456 | </head> | |
| 457 | <body> | |
| 458 | ||
| 459 | <?php echo validation_errors(); ?> | |
| 460 | ||
| 461 | <?php echo form_open('form'); ?> | |
| 462 | ||
| 463 | <h5>Username</h5> | |
| 464 | <input type="text" name="username" value="<?php echo set_value('username'); ?>" size="50" /> | |
| 465 | ||
| 466 | <h5>Password</h5> | |
| 467 | <input type="text" name="password" value="<?php echo set_value('password'); ?>" size="50" /> | |
| 468 | ||
| 469 | <h5>Password Confirm</h5> | |
| 470 | <input type="text" name="passconf" value="<?php echo set_value('passconf'); ?>" size="50" /> | |
| 471 | ||
| 472 | <h5>Email Address</h5> | |
| 473 | <input type="text" name="email" value="<?php echo set_value('email'); ?>" size="50" /> | |
| 474 | ||
| 475 | <div><input type="submit" value="Submit" /></div> | |
| 476 | ||
| 477 | </form> | |
| 478 | ||
| 479 | </body> | |
| 480 | </html> | |
| 481 | </textarea> | |
| 482 | ||
| 483 | ||
| 484 | <p><dfn>Now reload your page and submit the form so that it triggers an error. Your form fields should now be re-populated</dfn></p> | |
| 485 | ||
| 486 | <p class="important"><strong>Note:</strong> The <a href="#functionreference">Function Reference</a> section below contains functions that | |
| 487 | permit you to re-populate <select> menus, radio buttons, and checkboxes.</p> | |
| 488 | ||
| 489 | ||
| 490 | <p><strong>Important Note:</strong> If you use an array as the name of a form field, you must supply it as an array to the function. Example:</p> | |
| 491 | ||
| 492 | <code><input type="text" name="<kbd>colors[]</kbd>" value="<?php echo set_value('<kbd>colors[]</kbd>'); ?>" size="50" /></code> | |
| 493 | ||
| 494 | <p>For more info please see the <a href="#arraysasfields">Using Arrays as Field Names</a> section below.</p> | |
| 495 | ||
| 496 | ||
| 497 | ||
| 498 | ||
| 499 | ||
| 500 | <a name="callbacks"></a> | |
| 501 | <h2>Callbacks: Your own Validation Functions</h2> | |
| 502 | ||
| 503 | <p>The validation system supports callbacks to your own validation functions. This permits you to extend the validation class | |
| 504 | to 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 | |
| 505 | create a callback function that does that. Let's create a example of this.</p> | |
| 506 | ||
| 507 | <p>In your controller, change the "username" rule to this:</p> | |
| 508 | ||
| 509 | <code>$this->form_validation->set_rules('username', 'Username', '<kbd>callback_username_check</kbd>');</code> | |
| 510 | ||
| 511 | <p>Then add a new function called <dfn>username_check</dfn> to your controller. Here's how your controller should now look:</p> | |
| 512 | ||
| 513 | <textarea class="textarea" style="width:100%" cols="50" rows="40"><?php | |
| 514 | ||
| 515 | class Form extends CI_Controller { | |
| 516 | ||
| 517 | public function index() | |
| 518 | { | |
| 519 | $this->load->helper(array('form', 'url')); | |
| 520 | ||
| 521 | $this->load->library('form_validation'); | |
| 522 | ||
| 523 | $this->form_validation->set_rules('username', 'Username', 'callback_username_check'); | |
| 524 | $this->form_validation->set_rules('password', 'Password', 'required'); | |
| 525 | $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required'); | |
| 526 | $this->form_validation->set_rules('email', 'Email', 'required|is_unique[users.email]'); | |
| 527 | ||
| 528 | if ($this->form_validation->run() == FALSE) | |
| 529 | { | |
| 530 | $this->load->view('myform'); | |
| 531 | } | |
| 532 | else | |
| 533 | { | |
| 534 | $this->load->view('formsuccess'); | |
| 535 | } | |
| 536 | } | |
| 537 | ||
| 538 | public function username_check($str) | |
| 539 | { | |
| 540 | if ($str == 'test') | |
| 541 | { | |
| 542 | $this->form_validation->set_message('username_check', 'The %s field can not be the word "test"'); | |
| 543 | return FALSE; | |
| 544 | } | |
| 545 | else | |
| 546 | { | |
| 547 | return TRUE; | |
| 548 | } | |
| 549 | } | |
| 550 | ||
| 551 | } | |
| 552 | ?></textarea> | |
| 553 | ||
| 554 | <p><dfn>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 | |
| 555 | callback function for you to process.</dfn></p> | |
| 556 | ||
| 557 | <p>To invoke a callback just put the function name in a rule, with "callback_" as the rule <strong>prefix</strong>. If you need | |
| 558 | to receive an extra parameter in your callback function, just add it normally after the function name between square brackets, | |
| 559 | as in: "callback_foo<strong>[bar]</strong>", then it will be passed as the second argument of your callback function.</p> | |
| 560 | ||
| 561 | <p><strong>Note:</strong> You can also process the form data that is passed to your callback and return it. If your callback returns anything other than a boolean TRUE/FALSE | |
| 562 | it is assumed that the data is your newly processed form data.</p> | |
| 563 | ||
| 564 | <a name="settingerrors"></a> | |
| 565 | <h2>Setting Error Messages</h2> | |
| 566 | ||
| 567 | ||
| 568 | <p>All of the native error messages are located in the following language file: <dfn>language/english/form_validation_lang.php</dfn></p> | |
| 569 | ||
| 570 | <p>To set your own custom message you can either edit that file, or use the following function:</p> | |
| 571 | ||
| 572 | <code>$this->form_validation->set_message('<var>rule</var>', '<var>Error Message</var>');</code> | |
| 573 | ||
| 574 | <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> | |
| 575 | ||
| 576 | <p>If you include <dfn>%s</dfn> in your error string, it will be replaced with the "human" name you used for your field when you set your rules.</p> | |
| 577 | ||
| 578 | <p>In the "callback" example above, the error message was set by passing the name of the function:</p> | |
| 579 | ||
| 580 | <code>$this->form_validation->set_message('username_check')</code> | |
| 581 | ||
| 582 | <p>You can also override any error message found in the language file. For example, to change the message for the "required" rule you will do this:</p> | |
| 583 | ||
| 584 | <code>$this->form_validation->set_message('required', 'Your custom message here');</code> | |
| 585 | ||
| 586 | ||
| 587 | ||
| 588 | <a name="translatingfn"></a> | |
| 589 | <h2>Translating Field Names</h2> | |
| 590 | ||
| 591 | <p>If you would like to store the "human" name you passed to the <dfn>set_rules()</dfn> function in a language file, and therefore make the name able to be translated, here's how:</p> | |
| 592 | ||
| 593 | <p>First, prefix your "human" name with <dfn>lang:</dfn>, as in this example:</p> | |
| 594 | ||
| 595 | <code> | |
| 596 | $this->form_validation->set_rules('first_name', '<kbd>lang:</kbd>first_name', 'required');<br /> | |
| 597 | </code> | |
| 598 | ||
| 599 | <p>Then, store the name in one of your language file arrays (without the prefix):</p> | |
| 600 | ||
| 601 | <code>$lang['first_name'] = 'First Name';</code> | |
| 602 | ||
| 603 | <p><strong>Note:</strong> If you store your array item in a language file that is not loaded automatically by CI, you'll need to remember to load it in your controller using:</p> | |
| 604 | ||
| 605 | <code>$this->lang->load('file_name');</code> | |
| 606 | ||
| 607 | <p>See the <a href="language.html">Language Class</a> page for more info regarding language files.</p> | |
| 608 | ||
| 609 | ||
| 610 | <a name="errordelimiters"></a> | |
| 611 | <h2>Changing the Error Delimiters</h2> | |
| 612 | ||
| 613 | <p>By default, the Form Validation class adds a paragraph tag (<p>) around each error message shown. You can either change these delimiters globally or | |
| 614 | individually.</p> | |
| 615 | ||
| 616 | <ol> | |
| 617 | ||
| 618 | <li><strong>Changing delimiters Globally</strong> | |
| 619 | ||
| 620 | <p>To globally change the error delimiters, in your controller function, just after loading the Form Validation class, add this:</p> | |
| 621 | ||
| 622 | <code>$this->form_validation->set_error_delimiters('<kbd><div class="error"></kbd>', '<kbd></div></kbd>');</code> | |
| 623 | ||
| 624 | <p>In this example, we've switched to using div tags.</p> | |
| 625 | ||
| 626 | </li> | |
| 627 | ||
| 628 | <li><strong>Changing delimiters Individually</strong> | |
| 629 | ||
| 630 | <p>Each of the two error generating functions shown in this tutorial can be supplied their own delimiters as follows:</p> | |
| 631 | ||
| 632 | <code><?php echo form_error('field name', '<kbd><div class="error"></kbd>', '<kbd></div></kbd>'); ?></code> | |
| 633 | ||
| 634 | <p>Or:</p> | |
| 635 | ||
| 636 | <code><?php echo validation_errors('<kbd><div class="error"></kbd>', '<kbd></div></kbd>'); ?></code> | |
| 637 | ||
| 638 | </li> | |
| 639 | </ol> | |
| 640 | ||
| 641 | ||
| 642 | ||
| 643 | ||
| 644 | <a name="individualerrors"></a> | |
| 645 | <h2>Showing Errors Individually</h2> | |
| 646 | ||
| 647 | <p>If you prefer to show an error message next to each form field, rather than as a list, you can use the <dfn>form_error()</dfn> function.</p> | |
| 648 | ||
| 649 | <p>Try it! Change your form so that it looks like this:</p> | |
| 650 | ||
| 651 | <textarea class="textarea" style="width:100%" cols="50" rows="18"> | |
| 652 | <h5>Username</h5> | |
| 653 | <?php echo form_error('username'); ?> | |
| 654 | <input type="text" name="username" value="<?php echo set_value('username'); ?>" size="50" /> | |
| 655 | ||
| 656 | <h5>Password</h5> | |
| 657 | <?php echo form_error('password'); ?> | |
| 658 | <input type="text" name="password" value="<?php echo set_value('password'); ?>" size="50" /> | |
| 659 | ||
| 660 | <h5>Password Confirm</h5> | |
| 661 | <?php echo form_error('passconf'); ?> | |
| 662 | <input type="text" name="passconf" value="<?php echo set_value('passconf'); ?>" size="50" /> | |
| 663 | ||
| 664 | <h5>Email Address</h5> | |
| 665 | <?php echo form_error('email'); ?> | |
| 666 | <input type="text" name="email" value="<?php echo set_value('email'); ?>" size="50" /> | |
| 667 | </textarea> | |
| 668 | ||
| 669 | <p>If there are no errors, nothing will be shown. If there is an error, the message will appear.</p> | |
| 670 | ||
| 671 | <p><strong>Important Note:</strong> If you use an array as the name of a form field, you must supply it as an array to the function. Example:</p> | |
| 672 | ||
| 673 | <code><?php echo form_error('<kbd>options[size]</kbd>'); ?><br /> | |
| 674 | <input type="text" name="<kbd>options[size]</kbd>" value="<?php echo set_value("<kbd>options[size]</kbd>"); ?>" size="50" /> | |
| 675 | </code> | |
| 676 | ||
| 677 | <p>For more info please see the <a href="#arraysasfields">Using Arrays as Field Names</a> section below.</p> | |
| 678 | ||
| 679 | ||
| 680 | ||
| 681 | ||
| 682 | <p> </p> | |
| 683 | ||
| 684 | ||
| 685 | <a name="savingtoconfig"></a> | |
| 686 | <h1>Saving Sets of Validation Rules to a Config File</h1> | |
| 687 | ||
| 688 | <p>A nice feature of the Form Validation class is that it permits you to store all your validation rules for your entire application in a config file. You | |
| 689 | can organize these rules into "groups". These groups can either be loaded automatically when a matching controller/function is called, or | |
| 690 | you can manually call each set as needed.</p> | |
| 691 | ||
| 692 | <h3>How to save your rules</h3> | |
| 693 | ||
| 694 | <p>To store your validation rules, simply create a file named <kbd>form_validation.php</kbd> in your <dfn>application/config/</dfn> folder. | |
| 695 | In that file you will place an array named <kbd>$config</kbd> with your rules. As shown earlier, the validation array will have this prototype:</p> | |
| 696 | ||
| 697 | <code> | |
| 698 | $config = array(<br /> | |
| 699 | array(<br /> | |
| 700 | 'field' => 'username', <br /> | |
| 701 | 'label' => 'Username', <br /> | |
| 702 | 'rules' => 'required'<br /> | |
| 703 | ),<br /> | |
| 704 | array(<br /> | |
| 705 | 'field' => 'password', <br /> | |
| 706 | 'label' => 'Password', <br /> | |
| 707 | 'rules' => 'required'<br /> | |
| 708 | ),<br /> | |
| 709 | array(<br /> | |
| 710 | 'field' => 'passconf', <br /> | |
| 711 | 'label' => 'Password Confirmation', <br /> | |
| 712 | 'rules' => 'required'<br /> | |
| 713 | ), <br /> | |
| 714 | array(<br /> | |
| 715 | 'field' => 'email', <br /> | |
| 716 | 'label' => 'Email', <br /> | |
| 717 | 'rules' => 'required'<br /> | |
| 718 | )<br /> | |
| 719 | );<br /> | |
| 720 | </code> | |
| 721 | ||
| 722 | <p><dfn>Your validation rule file will be loaded automatically and used when you call the run() function.</dfn></p> | |
| 723 | ||
| 724 | <p class="important">Please note that you MUST name your array $config.</p> | |
| 725 | ||
| 726 | <h3>Creating Sets of Rules</h3> | |
| 727 | ||
| 728 | <p>In order to organize your rules into "sets" requires that you place them into "sub arrays". Consider the following example, showing two sets of rules. | |
| 729 | We've arbitrarily called these two rules "signup" and "email". You can name your rules anything you want:</p> | |
| 730 | ||
| 731 | ||
| 732 | <code>$config = array(<br /> | |
| 733 | '<kbd>signup</kbd>' => array(<br /> | |
| 734 | array(<br /> | |
| 735 | 'field' => 'username',<br /> | |
| 736 | 'label' => 'Username',<br /> | |
| 737 | 'rules' => 'required'<br /> | |
| 738 | ),<br /> | |
| 739 | array(<br /> | |
| 740 | 'field' => 'password',<br /> | |
| 741 | 'label' => 'Password',<br /> | |
| 742 | 'rules' => 'required'<br /> | |
| 743 | ),<br /> | |
| 744 | array(<br /> | |
| 745 | 'field' => 'passconf',<br /> | |
| 746 | 'label' => 'PasswordConfirmation',<br /> | |
| 747 | 'rules' => 'required'<br /> | |
| 748 | ),<br /> | |
| 749 | array(<br /> | |
| 750 | 'field' => 'email',<br /> | |
| 751 | 'label' => 'Email',<br /> | |
| 752 | 'rules' => 'required'<br /> | |
| 753 | )<br /> | |
| 754 | ),<br /> | |
| 755 | '<kbd>email</kbd>' => array(<br /> | |
| 756 | array(<br /> | |
| 757 | 'field' => 'emailaddress',<br /> | |
| 758 | 'label' => 'EmailAddress',<br /> | |
| 759 | 'rules' => 'required|valid_email'<br /> | |
| 760 | ),<br /> | |
| 761 | array(<br /> | |
| 762 | 'field' => 'name',<br /> | |
| 763 | 'label' => 'Name',<br /> | |
| 764 | 'rules' => 'required|alpha'<br /> | |
| 765 | ),<br /> | |
| 766 | array(<br /> | |
| 767 | 'field' => 'title',<br /> | |
| 768 | 'label' => 'Title',<br /> | |
| 769 | 'rules' => 'required'<br /> | |
| 770 | ),<br /> | |
| 771 | array(<br /> | |
| 772 | 'field' => 'message',<br /> | |
| 773 | 'label' => 'MessageBody',<br /> | |
| 774 | 'rules' => 'required'<br /> | |
| 775 | )<br /> | |
| 776 | ) <br /> | |
| 777 | );<br /> | |
| 778 | </code> | |
| 779 | ||
| 780 | ||
| 781 | <h3>Calling a Specific Rule Group</h3> | |
| 782 | ||
| 783 | <p>In order to call a specific group you will pass its name to the <kbd>run()</kbd> function. For example, to call the <kbd>signup</kbd> rule you will do this:</p> | |
| 784 | ||
| 785 | <code> | |
| 786 | if ($this->form_validation->run('<kbd>signup</kbd>') == FALSE)<br /> | |
| 787 | {<br /> | |
| 788 | $this->load->view('myform');<br /> | |
| 789 | }<br /> | |
| 790 | else<br /> | |
| 791 | {<br /> | |
| 792 | $this->load->view('formsuccess');<br /> | |
| 793 | }<br /> | |
| 794 | </code> | |
| 795 | ||
| 796 | ||
| 797 | ||
| 798 | <h3>Associating a Controller Function with a Rule Group</h3> | |
| 799 | ||
| 800 | <p>An alternate (and more automatic) method of calling a rule group is to name it according to the controller class/function you intend to use it with. For example, let's say you | |
| 801 | have a controller named <kbd>Member</kbd> and a function named <kbd>signup</kbd>. Here's what your class might look like:</p> | |
| 802 | ||
| 803 | <code> | |
| 804 | <?php<br /><br /> | |
| 805 | class <kbd>Member</kbd> extends CI_Controller {<br /> | |
| 806 | <br /> | |
| 807 | function <kbd>signup</kbd>()<br /> | |
| 808 | { <br /> | |
| 809 | $this->load->library('form_validation');<br /> | |
| 810 | <br /> | |
| 811 | if ($this->form_validation->run() == FALSE)<br /> | |
| 812 | {<br /> | |
| 813 | $this->load->view('myform');<br /> | |
| 814 | }<br /> | |
| 815 | else<br /> | |
| 816 | {<br /> | |
| 817 | $this->load->view('formsuccess');<br /> | |
| 818 | }<br /> | |
| 819 | }<br /> | |
| 820 | }<br /> | |
| 821 | ?></code> | |
| 822 | ||
| 823 | <p>In your validation config file, you will name your rule group <kbd>member/signup</kbd>:</p> | |
| 824 | ||
| 825 | ||
| 826 | <code>$config = array(<br /> | |
| 827 | '<kbd>member/signup</kbd>' => array(<br /> | |
| 828 | array(<br /> | |
| 829 | 'field' => 'username',<br /> | |
| 830 | 'label' => 'Username',<br /> | |
| 831 | 'rules' => 'required'<br /> | |
| 832 | ),<br /> | |
| 833 | array(<br /> | |
| 834 | 'field' => 'password',<br /> | |
| 835 | 'label' => 'Password',<br /> | |
| 836 | 'rules' => 'required'<br /> | |
| 837 | ),<br /> | |
| 838 | array(<br /> | |
| 839 | 'field' => 'passconf',<br /> | |
| 840 | 'label' => 'PasswordConfirmation',<br /> | |
| 841 | 'rules' => 'required'<br /> | |
| 842 | ),<br /> | |
| 843 | array(<br /> | |
| 844 | 'field' => 'email',<br /> | |
| 845 | 'label' => 'Email',<br /> | |
| 846 | 'rules' => 'required'<br /> | |
| 847 | )<br /> | |
| 848 | )<br /> | |
| 849 | );<br /> | |
| 850 | </code> | |
| 851 | ||
| 852 | <p><dfn>When a rule group is named identically to a controller class/function it will be used automatically when the run() function is invoked from that class/function.</dfn></p> | |
| 853 | ||
| 854 | <p> </p> | |
| 855 | ||
| 856 | ||
| 857 | <a name="arraysasfields"></a> | |
| 858 | <h1>Using Arrays as Field Names</h1> | |
| 859 | ||
| 860 | <p>The Form Validation class supports the use of arrays as field names. Consider this example:</p> | |
| 861 | ||
| 862 | <code><input type="text" name="<kbd>options[]</kbd>" value="" size="50" /></code> | |
| 863 | ||
| 864 | <p>If you do use an array as a field name, you must use the EXACT array name in the <a href="#helperreference">Helper Functions</a> that require the field name, | |
| 865 | and as your Validation Rule field name.</p> | |
| 866 | ||
| 867 | <p>For example, to set a rule for the above field you would use:</p> | |
| 868 | ||
| 869 | <code>$this->form_validation->set_rules('<kbd>options[]</kbd>', 'Options', 'required');</code> | |
| 870 | ||
| 871 | <p>Or, to show an error for the above field you would use:</p> | |
| 872 | ||
| 873 | <code><?php echo form_error('<kbd>options[]</kbd>'); ?></code> | |
| 874 | ||
| 875 | <p>Or to re-populate the field you would use:</p> | |
| 876 | ||
| 877 | <code><input type="text" name="<kbd>options[]</kbd>" value="<kbd><?php echo set_value('<kbd>options[]</kbd>'); ?></kbd>" size="50" /></code> | |
| 878 | ||
| 879 | <p>You can use multidimensional arrays as field names as well. For example:</p> | |
| 880 | ||
| 881 | <code><input type="text" name="<kbd>options[size]</kbd>" value="" size="50" /></code> | |
| 882 | ||
| 883 | <p>Or even:</p> | |
| 884 | ||
| 885 | <code><input type="text" name="<kbd>sports[nba][basketball]</kbd>" value="" size="50" /></code> | |
| 886 | ||
| 887 | <p>As with our first example, you must use the exact array name in the helper functions:</p> | |
| 888 | ||
| 889 | <code><?php echo form_error('<kbd>sports[nba][basketball]</kbd>'); ?></code> | |
| 890 | ||
| 891 | <p>If you are using checkboxes (or other fields) that have multiple options, don't forget to leave an empty bracket after each option, so that all selections will be added to the | |
| 892 | POST array:</p> | |
| 893 | ||
| 894 | <code> | |
| 895 | <input type="checkbox" name="<kbd>options[]</kbd>" value="red" /><br /> | |
| 896 | <input type="checkbox" name="<kbd>options[]</kbd>" value="blue" /><br /> | |
| 897 | <input type="checkbox" name="<kbd>options[]</kbd>" value="green" /> | |
| 898 | </code> | |
| 899 | ||
| 900 | <p>Or if you use a multidimensional array:</p> | |
| 901 | ||
| 902 | <code> | |
| 903 | <input type="checkbox" name="<kbd>options[color][]</kbd>" value="red" /><br /> | |
| 904 | <input type="checkbox" name="<kbd>options[color][]</kbd>" value="blue" /><br /> | |
| 905 | <input type="checkbox" name="<kbd>options[color][]</kbd>" value="green" /> | |
| 906 | </code> | |
| 907 | ||
| 908 | <p>When you use a helper function you'll include the bracket as well:</p> | |
| 909 | ||
| 910 | <code><?php echo form_error('<kbd>options[color][]</kbd>'); ?></code> | |
| 911 | ||
| 912 | ||
| 913 | ||
| 914 | ||
| 915 | <p> </p> | |
| 916 | ||
| 917 | ||
| 918 | <a name="rulereference"></a> | |
| 919 | <h1>Rule Reference</h1> | |
| 920 | ||
| 921 | <p>The following is a list of all the native rules that are available to use:</p> | |
| 922 | ||
| 923 | ||
| 924 | <table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder"> | |
| 925 | <tr> | |
| 926 | <th>Rule</th> | |
| 927 | <th>Parameter</th> | |
| 928 | <th>Description</th> | |
| 929 | <th>Example</th> | |
| 930 | </tr> | |
| 931 | ||
| 932 | <tr> | |
| 933 | <td class="td"><strong>required</strong></td> | |
| 934 | <td class="td">No</td> | |
| 935 | <td class="td">Returns FALSE if the form element is empty.</td> | |
| 936 | <td class="td"> </td> | |
| 937 | </tr> | |
| 938 | ||
| 939 | <tr> | |
| 940 | <td class="td"><strong>matches</strong></td> | |
| 941 | <td class="td">Yes</td> | |
| 942 | <td class="td">Returns FALSE if the form element does not match the one in the parameter.</td> | |
| 943 | <td class="td">matches[form_item]</td> | |
| 944 | </tr> | |
| 945 | ||
| 946 | <tr> | |
| 947 | <td class="td"><strong>is_unique</strong></td> | |
| 948 | <td class="td">Yes</td> | |
| 949 | <td class="td">Returns FALSE if the form element is not unique to the table and field name in the parameter.</td> | |
| 950 | <td class="td">is_unique[table.field]</td> | |
| 951 | </tr> | |
| 952 | ||
| 953 | <tr> | |
| 954 | <td class="td"><strong>min_length</strong></td> | |
| 955 | <td class="td">Yes</td> | |
| 956 | <td class="td">Returns FALSE if the form element is shorter then the parameter value.</td> | |
| 957 | <td class="td">min_length[6]</td> | |
| 958 | </tr> | |
| 959 | ||
| 960 | <tr> | |
| 961 | <td class="td"><strong>max_length</strong></td> | |
| 962 | <td class="td">Yes</td> | |
| 963 | <td class="td">Returns FALSE if the form element is longer then the parameter value.</td> | |
| 964 | <td class="td">max_length[12]</td> | |
| 965 | </tr> | |
| 966 | ||
| 967 | <tr> | |
| 968 | <td class="td"><strong>exact_length</strong></td> | |
| 969 | <td class="td">Yes</td> | |
| 970 | <td class="td">Returns FALSE if the form element is not exactly the parameter value.</td> | |
| 971 | <td class="td">exact_length[8]</td> | |
| 972 | </tr> | |
| 973 | ||
| 974 | <tr> | |
| 975 | <td class="td"><strong>greater_than</strong></td> | |
| 976 | <td class="td">Yes</td> | |
| 977 | <td class="td">Returns FALSE if the form element is less than the parameter value or not numeric.</td> | |
| 978 | <td class="td">greater_than[8]</td> | |
| 979 | </tr> | |
| 980 | ||
| 981 | <tr> | |
| 982 | <td class="td"><strong>less_than</strong></td> | |
| 983 | <td class="td">Yes</td> | |
| 984 | <td class="td">Returns FALSE if the form element is greater than the parameter value or not numeric.</td> | |
| 985 | <td class="td">less_than[8]</td> | |
| 986 | </tr> | |
| 987 | ||
| 988 | <tr> | |
| 989 | <td class="td"><strong>alpha</strong></td> | |
| 990 | <td class="td">No</td> | |
| 991 | <td class="td">Returns FALSE if the form element contains anything other than alphabetical characters.</td> | |
| 992 | <td class="td"> </td> | |
| 993 | </tr> | |
| 994 | ||
| 995 | <tr> | |
| 996 | <td class="td"><strong>alpha_numeric</strong></td> | |
| 997 | <td class="td">No</td> | |
| 998 | <td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters.</td> | |
| 999 | <td class="td"> </td> | |
| 1000 | </tr> | |
| 1001 | ||
| 1002 | <tr> | |
| 1003 | <td class="td"><strong>alpha_dash</strong></td> | |
| 1004 | <td class="td">No</td> | |
| 1005 | <td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters, underscores or dashes.</td> | |
| 1006 | <td class="td"> </td> | |
| 1007 | </tr> | |
| 1008 | ||
| 1009 | <tr> | |
| 1010 | <td class="td"><strong>numeric</strong></td> | |
| 1011 | <td class="td">No</td> | |
| 1012 | <td class="td">Returns FALSE if the form element contains anything other than numeric characters.</td> | |
| 1013 | <td class="td"> </td> | |
| 1014 | </tr> | |
| 1015 | ||
| 1016 | <tr> | |
| 1017 | <td class="td"><strong>integer</strong></td> | |
| 1018 | <td class="td">No</td> | |
| 1019 | <td class="td">Returns FALSE if the form element contains anything other than an integer.</td> | |
| 1020 | <td class="td"> </td> | |
| 1021 | </tr> | |
| 1022 | ||
| 1023 | <tr> | |
| 1024 | <td class="td"><strong>decimal</strong></td> | |
| 1025 | <td class="td">Yes</td> | |
| 1026 | <td class="td">Returns FALSE if the form element is not exactly the parameter value.</td> | |
| 1027 | <td class="td"> </td> | |
| 1028 | </tr> | |
| 1029 | ||
| 1030 | <tr> | |
| 1031 | <td class="td"><strong>is_natural</strong></td> | |
| 1032 | <td class="td">No</td> | |
| 1033 | <td class="td">Returns FALSE if the form element contains anything other than a natural number: 0, 1, 2, 3, etc.</td> | |
| 1034 | <td class="td"> </td> | |
| 1035 | </tr> | |
| 1036 | ||
| 1037 | <tr> | |
| 1038 | <td class="td"><strong>is_natural_no_zero</strong></td> | |
| 1039 | <td class="td">No</td> | |
| 1040 | <td class="td">Returns FALSE if the form element contains anything other than a natural number, but not zero: 1, 2, 3, etc.</td> | |
| 1041 | <td class="td"> </td> | |
| 1042 | </tr> | |
| 1043 | ||
| 1044 | <tr> | |
| 1045 | <td class="td"><strong>valid_email</strong></td> | |
| 1046 | <td class="td">No</td> | |
| 1047 | <td class="td">Returns FALSE if the form element does not contain a valid email address.</td> | |
| 1048 | <td class="td"> </td> | |
| 1049 | </tr> | |
| 1050 | ||
| 1051 | <tr> | |
| 1052 | <td class="td"><strong>valid_emails</strong></td> | |
| 1053 | <td class="td">No</td> | |
| 1054 | <td class="td">Returns FALSE if any value provided in a comma separated list is not a valid email.</td> | |
| 1055 | <td class="td"> </td> | |
| 1056 | </tr> | |
| 1057 | ||
| 1058 | <tr> | |
| 1059 | <td class="td"><strong>valid_ip</strong></td> | |
| 1060 | <td class="td">No</td> | |
| 1061 | <td class="td">Returns FALSE if the supplied IP is not valid. Accepts an optional parameter of "IPv4" or "IPv6" to specify an IP format.</td> | |
| 1062 | <td class="td"> </td> | |
| 1063 | </tr> | |
| 1064 | ||
| 1065 | <tr> | |
| 1066 | <td class="td"><strong>valid_base64</strong></td> | |
| 1067 | <td class="td">No</td> | |
| 1068 | <td class="td">Returns FALSE if the supplied string contains anything other than valid Base64 characters.</td> | |
| 1069 | <td class="td"> </td> | |
| 1070 | </tr> | |
| 1071 | ||
| 1072 | ||
| 1073 | </table> | |
| 1074 | ||
| 1075 | <p><strong>Note:</strong> These rules can also be called as discrete functions. For example:</p> | |
| 1076 | ||
| 1077 | <code>$this->form_validation->required($string);</code> | |
| 1078 | ||
| 1079 | <p class="important"><strong>Note:</strong> You can also use any native PHP functions that permit one parameter.</p> | |
| 1080 | ||
| 1081 | ||
| 1082 | ||
| 1083 | <p> </p> | |
| 1084 | ||
| 1085 | <a name="preppingreference"></a> | |
| 1086 | <h1>Prepping Reference</h1> | |
| 1087 | ||
| 1088 | <p>The following is a list of all the prepping functions that are available to use:</p> | |
| 1089 | ||
| 1090 | ||
| 1091 | ||
| 1092 | <table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder"> | |
| 1093 | <tr> | |
| 1094 | <th>Name</th> | |
| 1095 | <th>Parameter</th> | |
| 1096 | <th>Description</th> | |
| 1097 | </tr><tr> | |
| 1098 | ||
| 1099 | <td class="td"><strong>xss_clean</strong></td> | |
| 1100 | <td class="td">No</td> | |
| 1101 | <td class="td">Runs the data through the XSS filtering function, described in the <a href="input.html">Input Class</a> page.</td> | |
| 1102 | </tr><tr> | |
| 1103 | ||
| 1104 | <td class="td"><strong>prep_for_form</strong></td> | |
| 1105 | <td class="td">No</td> | |
| 1106 | <td class="td">Converts special characters so that HTML data can be shown in a form field without breaking it.</td> | |
| 1107 | </tr><tr> | |
| 1108 | ||
| 1109 | <td class="td"><strong>prep_url</strong></td> | |
| 1110 | <td class="td">No</td> | |
| 1111 | <td class="td">Adds "http://" to URLs if missing.</td> | |
| 1112 | </tr><tr> | |
| 1113 | ||
| 1114 | <td class="td"><strong>strip_image_tags</strong></td> | |
| 1115 | <td class="td">No</td> | |
| 1116 | <td class="td">Strips the HTML from image tags leaving the raw URL.</td> | |
| 1117 | </tr><tr> | |
| 1118 | ||
| 1119 | <td class="td"><strong>encode_php_tags</strong></td> | |
| 1120 | <td class="td">No</td> | |
| 1121 | <td class="td">Converts PHP tags to entities.</td> | |
| 1122 | </tr> | |
| 1123 | ||
| 1124 | </table> | |
| 1125 | ||
| 1126 | <p class="important"><strong>Note:</strong> You can also use any native PHP functions that permit one parameter, | |
| 1127 | like <kbd>trim</kbd>, <kbd>htmlspecialchars</kbd>, <kbd>urldecode</kbd>, etc.</p> | |
| 1128 | ||
| 1129 | ||
| 1130 | ||
| 1131 | ||
| 1132 | ||
| 1133 | ||
| 1134 | ||
| 1135 | <p> </p> | |
| 1136 | ||
| 1137 | <a name="functionreference"></a> | |
| 1138 | <h1>Function Reference</h1> | |
| 1139 | ||
| 1140 | <p>The following functions are intended for use in your controller functions.</p> | |
| 1141 | ||
| 1142 | <h2>$this->form_validation->set_rules();</h2> | |
| 1143 | ||
| 1144 | <p>Permits you to set validation rules, as described in the tutorial sections above:</p> | |
| 1145 | ||
| 1146 | <ul> | |
| 1147 | <li><a href="#validationrules">Setting Validation Rules</a></li> | |
| 1148 | <li><a href="#savingtoconfig">Saving Groups of Validation Rules to a Config File</a></li> | |
| 1149 | </ul> | |
| 1150 | ||
| 1151 | ||
| 1152 | <h2>$this->form_validation->run();</h2> | |
| 1153 | ||
| 1154 | <p>Runs the validation routines. Returns boolean TRUE on success and FALSE on failure. You can optionally pass the name of the validation | |
| 1155 | group via the function, as described in: <a href="#savingtoconfig">Saving Groups of Validation Rules to a Config File</a>.</p> | |
| 1156 | ||
| 1157 | ||
| 1158 | <h2>$this->form_validation->set_message();</h2> | |
| 1159 | ||
| 1160 | <p>Permits you to set custom error messages. See <a href="#settingerrors">Setting Error Messages</a> above.</p> | |
| 1161 | ||
| 1162 | ||
| 1163 | <p> </p> | |
| 1164 | ||
| 1165 | <a name="helperreference"></a> | |
| 1166 | <h1>Helper Reference</h1> | |
| 1167 | ||
| 1168 | <p>The following helper functions are available for use in the view files containing your forms. Note that these are procedural functions, so they | |
| 1169 | <strong>do not</strong> require you to prepend them with $this->form_validation.</p> | |
| 1170 | ||
| 1171 | <h2>form_error()</h2> | |
| 1172 | ||
| 1173 | <p>Shows an individual error message associated with the field name supplied to the function. Example:</p> | |
| 1174 | ||
| 1175 | <code><?php echo form_error('username'); ?></code> | |
| 1176 | ||
| 1177 | <p>The error delimiters can be optionally specified. See the <a href="#errordelimiters">Changing the Error Delimiters</a> section above.</p> | |
| 1178 | ||
| 1179 | ||
| 1180 | ||
| 1181 | <h2>validation_errors()</h2> | |
| 1182 | <p>Shows all error messages as a string: Example:</p> | |
| 1183 | ||
| 1184 | <code><?php echo validation_errors(); ?></code> | |
| 1185 | ||
| 1186 | <p>The error delimiters can be optionally specified. See the <a href="#errordelimiters">Changing the Error Delimiters</a> section above.</p> | |
| 1187 | ||
| 1188 | ||
| 1189 | ||
| 1190 | <h2>set_value()</h2> | |
| 1191 | ||
| 1192 | <p>Permits you to set the value of an input form or textarea. You must supply the field name via the first parameter of the function. | |
| 1193 | The second (optional) parameter allows you to set a default value for the form. Example:</p> | |
| 1194 | ||
| 1195 | <code><input type="text" name="quantity" value="<dfn><?php echo set_value('quantity', '0'); ?></dfn>" size="50" /></code> | |
| 1196 | ||
| 1197 | <p>The above form will show "0" when loaded for the first time.</p> | |
| 1198 | ||
| 1199 | <h2>set_select()</h2> | |
| 1200 | ||
| 1201 | <p>If you use a <dfn><select></dfn> menu, this function permits you to display the menu item that was selected. The first parameter | |
| 1202 | must contain the name of the select menu, the second parameter must contain the value of | |
| 1203 | each item, and the third (optional) parameter lets you set an item as the default (use boolean TRUE/FALSE).</p> | |
| 1204 | ||
| 1205 | <p>Example:</p> | |
| 1206 | ||
| 1207 | <code> | |
| 1208 | <select name="myselect"><br /> | |
| 1209 | <option value="one" <dfn><?php echo set_select('myselect', 'one', TRUE); ?></dfn> >One</option><br /> | |
| 1210 | <option value="two" <dfn><?php echo set_select('myselect', 'two'); ?></dfn> >Two</option><br /> | |
| 1211 | <option value="three" <dfn><?php echo set_select('myselect', 'three'); ?></dfn> >Three</option><br /> | |
| 1212 | </select> | |
| 1213 | </code> | |
| 1214 | ||
| 1215 | ||
| 1216 | <h2>set_checkbox()</h2> | |
| 1217 | ||
| 1218 | <p>Permits you to display a checkbox in the state it was submitted. The first parameter | |
| 1219 | must contain the name of the checkbox, the second parameter must contain its value, and the third (optional) parameter lets you set an item as the default (use boolean TRUE/FALSE). Example:</p> | |
| 1220 | ||
| 1221 | <code><input type="checkbox" name="mycheck[]" value="1" <dfn><?php echo set_checkbox('mycheck[]', '1'); ?></dfn> /><br /> | |
| 1222 | <input type="checkbox" name="mycheck[]" value="2" <dfn><?php echo set_checkbox('mycheck[]', '2'); ?></dfn> /></code> | |
| 1223 | ||
| 1224 | ||
| 1225 | <h2>set_radio()</h2> | |
| 1226 | ||
| 1227 | <p>Permits you to display radio buttons in the state they were submitted. This function is identical to the <strong>set_checkbox()</strong> function above.</p> | |
| 1228 | ||
| 1229 | <code><input type="radio" name="myradio" value="1" <dfn><?php echo set_radio('myradio', '1', TRUE); ?></dfn> /><br /> | |
| 1230 | <input type="radio" name="myradio" value="2" <dfn><?php echo set_radio('myradio', '2'); ?></dfn> /></code> | |
| 1231 | ||
| 1232 | ||
| 1233 | ||
| 1234 | </div> | |
| 1235 | <!-- END CONTENT --> | |
| 1236 | ||
| 1237 | ||
| 1238 | <div id="footer"> | |
| 1239 | <p> | |
| 1240 | Previous Topic: <a href="file_uploading.html">File Uploading Class</a> | |
| 1241 | · | |
| 1242 | <a href="#top">Top of Page</a> · | |
| 1243 | <a href="../index.html">User Guide Home</a> · | |
| 1244 | Next Topic: <a href="ftp.html">FTP Class</a> | |
| 1245 | </p> | |
| 1246 | <p><a href="http://codeigniter.com">CodeIgniter</a> · Copyright © 2006 - 2012 · <a href="http://ellislab.com/">EllisLab, Inc.</a></p> | |
| 1247 | </div> | |
| 1248 | ||
| 1249 | </body> | |
| 1250 | </html> |