Merge branch 'refs/heads/develop' into feature/form_error_msgs

Conflicts: system/language/english/form_validation_lang.php user_guide_src/source/libraries/form_validation.rst Signed-off-by: Eric Roberts <eric@cryode.com>
author: Eric Roberts <eric@cryode.com> 2012-12-12 14:02:11 +0100
committer: Eric Roberts <eric@cryode.com> 2012-12-12 14:02:11 +0100
commit: b9e35f21e1c70b6aa67c47e9244ed83195abc00a (patch)
tree: 64f82db362deeac48cc20d1d1afd80651f36f5a5 /user_guide_src/source/libraries/form_validation.rst
parent: 0b05705c52c3bca7f9b3aee657c888e8ad1ff422 (diff)
parent: 545a7c86701875e1412bcde316e9bcc76d9a23a0 (diff)
1 files changed, 185 insertions, 185 deletions
diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst
index 9ff2d0eb3..acf1e5619 100644
--- a/user_guide_src/source/libraries/form_validation.rst
+++ b/user_guide_src/source/libraries/form_validation.rst
@@ -63,7 +63,7 @@ The Form
 ========
 
 Using a text editor, create a form called myform.php. In it, place this
-code and save it to your applications/views/ folder::
+code and save it to your application/views/ folder::
 
 	<html>
 	<head>
@@ -98,7 +98,7 @@ The Success Page
 ================
 
 Using a text editor, create a form called formsuccess.php. In it, place
-this code and save it to your applications/views/ folder::
+this code and save it to your application/views/ folder::
 
 	<html>
 	<head>
@@ -117,7 +117,7 @@ The Controller
 ==============
 
 Using a text editor, create a controller called form.php. In it, place
-this code and save it to your applications/controllers/ folder::
+this code and save it to your application/controllers/ folder::
 
 	<?php
 
@@ -252,30 +252,30 @@ Setting Rules Using an Array
 
 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. If
-you use this approach you must name your array keys as indicated::
+you use this approach, you must name your array keys as indicated::
 
 	$config = array(
-	               array(
-	                     'field'   => 'username', 
-	                     'label'   => 'Username', 
-	                     'rules'   => 'required'
-	                  ),
-	               array(
-	                     'field'   => 'password', 
-	                     'label'   => 'Password', 
-	                     'rules'   => 'required'
-	                  ),
-	               array(
-	                     'field'   => 'passconf', 
-	                     'label'   => 'Password Confirmation', 
-	                     'rules'   => 'required'
-	                  ),   
-	               array(
-	                     'field'   => 'email', 
-	                     'label'   => 'Email', 
-	                     'rules'   => 'required'
-	                  )
-	            );
+		array(
+			'field' => 'username',
+			'label' => 'Username',
+			'rules' => 'required'
+		),
+		array(
+			'field' => 'password',
+			'label' => 'Password',
+			'rules' => 'required'
+		),
+		array(
+			'field' => 'passconf',
+			'label' => 'Password Confirmation',
+			'rules' => 'required'
+		),
+		array(
+			'field' => 'email',
+			'label' => 'Email',
+			'rules' => 'required'
+		)
+	);
 
 	$this->form_validation->set_rules($config);
 
@@ -286,10 +286,9 @@ CodeIgniter lets you pipe multiple rules together. Let's try it. Change
 your rules in the third parameter of rule setting function, like this::
 
 	$this->form_validation->set_rules('username', 'Username', 'required|min_length[5]|max_length[12]|is_unique[users.username]');
-	$this->form_validation->set_rules('password', 'Password', 'required|matches[passconf]');
-	$this->form_validation->set_rules('passconf', 'Password Confirmation', 'required');
+	$this->form_validation->set_rules('password', 'Password', 'required');
+	$this->form_validation->set_rules('passconf', 'Password Confirmation', 'required|matches[password]');
 	$this->form_validation->set_rules('email', 'Email', 'required|valid_email|is_unique[users.email]');
-	
 
 The above code sets the following rules:
 
@@ -302,6 +301,10 @@ Give it a try! Submit your form without the proper data and you'll see
 new error messages that correspond to your new rules. There are numerous
 rules available which you can read about in the validation reference.
 
+.. note:: You can also pass an array of rules to set_rules(), instead of a string. Example::
+
+	$this->form_validation->set_rules('username', 'Username', array('required', 'min_length[5]'));
+
 Prepping Data
 =============
 
@@ -310,8 +313,8 @@ can also prep your data in various ways. For example, you can set up
 rules like this::
 
 	$this->form_validation->set_rules('username', 'Username', 'trim|required|min_length[5]|max_length[12]|xss_clean');
-	$this->form_validation->set_rules('password', 'Password', 'trim|required|matches[passconf]|md5');
-	$this->form_validation->set_rules('passconf', 'Password Confirmation', 'trim|required');
+	$this->form_validation->set_rules('password', 'Password', 'trim|required|md5');
+	$this->form_validation->set_rules('passconf', 'Password Confirmation', 'trim|required|matches[password]');
 	$this->form_validation->set_rules('email', 'Email', 'trim|required|valid_email');
 
 In the above example, we are "trimming" the fields, converting the
@@ -393,7 +396,7 @@ The validation system supports callbacks to your own validation
 functions. This permits you to extend the validation class 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 create a callback function
-that does that. Let's create a example of this.
+that does that. Let's create an example of this.
 
 In your controller, change the "username" rule to this::
 
@@ -431,7 +434,7 @@ Here's how your controller should now look::
 		{
 			if ($str == 'test')
 			{
-				$this->form_validation->set_message('username_check', 'The %s field can not be the word "test"');
+				$this->form_validation->set_message('username_check', 'The {field} field can not be the word "test"');
 				return FALSE;
 			}
 			else
@@ -463,7 +466,7 @@ Setting Error Messages
 ======================
 
 All of the native error messages are located in the following language
-file: system/language/english/form_validation_lang.php
+file: /system/language/english/form_validation_lang.php
 
 To set your own custom message you can either edit that file, or use the
 following function::
@@ -473,7 +476,7 @@ following function::
 Where rule corresponds to the name of a particular rule, and Error
 Message is the text you would like displayed.
 
-If you'd like to include a field's "human" name or the optional 
+If you'd like to include a field's "human" name, or the optional 
 parameter some rules allow for (such as max_length), you can add the 
 **{field}** and **{param}** tags to your message, respectively.
 
@@ -486,16 +489,11 @@ error would display: "Username must have at least 5 characters."
 still work, however it will override the tags above. You should use
 one or the other.
 
-In the "callback" example above, the error message was set by passing
-the name of the function::
+In the callback rule example above, the error message was set by passing
+the name of the function (without the "callback_" prefix)::
 
 	$this->form_validation->set_message('username_check')
 
-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::
-
-	$this->form_validation->set_message('required', 'Your custom message here');
-
 .. _translating-field-names:
 
 Translating Field Names
@@ -552,11 +550,10 @@ globally, individually, or change the defaults in a config file.
 
 #. **Set delimiters in a config file**
    You can add your error delimiters in application/config/form_validation.php as follows::
-   
+
       $config['error_prefix'] = '<div class="error_prefix">';
       $config['error_suffix'] = '</div>';
 
-
 Showing Errors Individually
 ===========================
 
@@ -584,8 +581,8 @@ Try it! Change your form so that it looks like this::
 If there are no errors, nothing will be shown. If there is an error, the
 message will appear.
 
-.. note:: **Important Note:** If you use an array as the name of a form field, you
-must supply it as an array to the function. Example::
+.. important:: If you use an array as the name of a form field, you
+	must supply it as an array to the function. Example::
 
 	<?php echo form_error('options[size]'); ?>
 	<input type="text" name="options[size]" value="<?php echo set_value("options[size]"); ?>" size="50" />
@@ -595,20 +592,20 @@ For more info please see the :ref:`using-arrays-as-field-names` section below.
 Validating an Array (other than $_POST)
 =======================================
 
-Sometimes you may want to validate an array that does not originate from $_POST data.
+Sometimes you may want to validate an array that does not originate from ``$_POST`` data.
 
 In this case, you can specify the array to be validated::
-	
+
 	$data = array(
-			'username' => 'johndoe',
-			'password' => 'mypassword',
-		 	'passconf' => 'mypassword'
-		);
+		'username' => 'johndoe',
+		'password' => 'mypassword',
+		'passconf' => 'mypassword'
+	);
 
 	$this->form_validation->set_data($data);
 
-Creating validation rules, running the validation and retrieving error messages works the same whether you are
-validating $_POST data or an array.
+Creating validation rules, running the validation, and retrieving error messages works the
+same whether you are validating ``$_POST`` data or an array.
 
 **Important Note:** If you want to validate more than one array during a single execution, then you should	
 call the reset_validation() function before setting up rules and validating the new array.
@@ -636,32 +633,32 @@ you will place an array named $config with your rules. As shown earlier,
 the validation array will have this prototype::
 
 	$config = array(
-	               array(
-	                     'field'   => 'username', 
-	                     'label'   => 'Username', 
-	                     'rules'   => 'required'
-	                  ),
-	               array(
-	                     'field'   => 'password', 
-	                     'label'   => 'Password', 
-	                     'rules'   => 'required'
-	                  ),
-	               array(
-	                     'field'   => 'passconf', 
-	                     'label'   => 'Password Confirmation', 
-	                     'rules'   => 'required'
-	                  ),   
-	               array(
-	                     'field'   => 'email', 
-	                     'label'   => 'Email', 
-	                     'rules'   => 'required'
-	                  )
-	            );
+		array(
+			'field' => 'username',
+			'label' => 'Username',
+			'rules' => 'required'
+		),
+		array(
+			'field' => 'password',
+			'label' => 'Password',
+			'rules' => 'required'
+		),
+		array(
+			'field' => 'passconf',
+			'label' => 'Password Confirmation',
+			'rules' => 'required'
+		),
+		array(
+			'field' => 'email',
+			'label' => 'Email',
+			'rules' => 'required'
+		)
+	);
 
 Your validation rule file will be loaded automatically and used when you
-call the run() function.
+call the ``run()`` method.
 
-Please note that you MUST name your array $config.
+Please note that you MUST name your ``$config`` array.
 
 Creating Sets of Rules
 ======================
@@ -672,121 +669,121 @@ rules. We've arbitrarily called these two rules "signup" and "email".
 You can name your rules anything you want::
 
 	$config = array(
-	                 'signup' => array(
-	                                    array(
-	                                            'field' => 'username',
-	                                            'label' => 'Username',
-	                                            'rules' => 'required'
-	                                         ),
-	                                    array(
-	                                            'field' => 'password',
-	                                            'label' => 'Password',
-	                                            'rules' => 'required'
-	                                         ),
-	                                    array(
-	                                            'field' => 'passconf',
-	                                            'label' => 'PasswordConfirmation',
-	                                            'rules' => 'required'
-	                                         ),
-	                                    array(
-	                                            'field' => 'email',
-	                                            'label' => 'Email',
-	                                            'rules' => 'required'
-	                                         )
-	                                    ),
-	                 'email' => array(
-	                                    array(
-	                                            'field' => 'emailaddress',
-	                                            'label' => 'EmailAddress',
-	                                            'rules' => 'required|valid_email'
-	                                         ),
-	                                    array(
-	                                            'field' => 'name',
-	                                            'label' => 'Name',
-	                                            'rules' => 'required|alpha'
-	                                         ),
-	                                    array(
-	                                            'field' => 'title',
-	                                            'label' => 'Title',
-	                                            'rules' => 'required'
-	                                         ),
-	                                    array(
-	                                            'field' => 'message',
-	                                            'label' => 'MessageBody',
-	                                            'rules' => 'required'
-	                                         )
-	                                    )                          
-	               );
+		'signup' => array(
+			array(
+				'field' => 'username',
+				'label' => 'Username',
+				'rules' => 'required'
+			),
+			array(
+				'field' => 'password',
+				'label' => 'Password',
+				'rules' => 'required'
+			),
+			array(
+				'field' => 'passconf',
+				'label' => 'Password Confirmation',
+				'rules' => 'required'
+			),
+			array(
+				'field' => 'email',
+				'label' => 'Email',
+				'rules' => 'required'
+			)
+		),
+		'email' => array(
+			array(
+				'field' => 'emailaddress',
+				'label' => 'EmailAddress',
+				'rules' => 'required|valid_email'
+			),
+			array(
+				'field' => 'name',
+				'label' => 'Name',
+				'rules' => 'required|alpha'
+			),
+			array(
+				'field' => 'title',
+				'label' => 'Title',
+				'rules' => 'required'
+			),
+			array(
+				'field' => 'message',
+				'label' => 'MessageBody',
+				'rules' => 'required'
+			)
+		)
+	);
 
 Calling a Specific Rule Group
 =============================
 
-In order to call a specific group you will pass its name to the run()
-function. For example, to call the signup rule you will do this::
+In order to call a specific group, you will pass its name to the ``run()``
+method. For example, to call the signup rule you will do this::
 
 	if ($this->form_validation->run('signup') == FALSE)
 	{
-	   $this->load->view('myform');
+		$this->load->view('myform');
 	}
 	else
 	{
-	   $this->load->view('formsuccess');
+		$this->load->view('formsuccess');
 	}
 
 Associating a Controller Function with a Rule Group
 ===================================================
 
 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
+name it according to the controller class/method you intend to use it
 with. For example, let's say you have a controller named Member and a
-function named signup. Here's what your class might look like::
+method named signup. Here's what your class might look like::
 
 	<?php
 
 	class Member extends CI_Controller {
 
-	   function signup()
-	   {      
-	      $this->load->library('form_validation');
-
-	      if ($this->form_validation->run() == FALSE)
-	      {
-	         $this->load->view('myform');
-	      }
-	      else
-	      {
-	         $this->load->view('formsuccess');
-	      }
-	   }
+		function signup()
+		{
+			$this->load->library('form_validation');
+
+			if ($this->form_validation->run() == FALSE)
+			{
+				$this->load->view('myform');
+			}
+			else
+			{
+				$this->load->view('formsuccess');
+			}
+		}
 	}
 
 In your validation config file, you will name your rule group
 member/signup::
 
 	$config = array(
-	           'member/signup' => array(
-	                                    array(
-	                                            'field' => 'username',
-	                                            'label' => 'Username',
-	                                            'rules' => 'required'
-	                                         ),
-	                                    array(
-	                                            'field' => 'password',
-	                                            'label' => 'Password',
-	                                            'rules' => 'required'
-	                                         ),
-	                                    array(
-	                                            'field' => 'passconf',
-	                                            'label' => 'PasswordConfirmation',
-	                                            'rules' => 'required'
-	                                         ),
-	                                    array(
-	                                            'field' => 'email',
-	                                            'label' => 'Email',
-	                                            'rules' => 'required'
-	                                         )
-	                                    )
-	               );
+		'member/signup' => array(
+			array(
+				'field' => 'username',
+				'label' => 'Username',
+				'rules' => 'required'
+			),
+			array(
+				'field' => 'password',
+				'label' => 'Password',
+				'rules' => 'required'
+			),
+			array(
+				'field' => 'passconf',
+				'label' => 'PasswordConfirmation',
+				'rules' => 'required'
+			),
+			array(
+				'field' => 'email',
+				'label' => 'Email',
+				'rules' => 'required'
+			)
+		)
+	);
 
 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
@@ -863,8 +860,10 @@ Rule                      Parameter  Description
 ========================= ========== ============================================================================================= =======================
 **required**              No         Returns FALSE if the form element is empty.                                                                          
 **matches**               Yes        Returns FALSE if the form element does not match the one in the parameter.                    matches[form_item]     
-**is_unique**             Yes        Returns FALSE if the form element is not unique to the                                        is_unique[table.field] 
-                                     table and field name in the parameter. is_unique[table.field]                                                        
+**differs**               Yes        Returns FALSE if the form element does not differ from the one in the parameter.              differs[form_item]     
+**is_unique**             Yes        Returns FALSE if the form element is not unique to the table and field name in the            is_unique[table.field] 
+                                     parameter. Note: This rule requires :doc:`Query Builder <../database/query_builder>` to be                             
+                                     enabled in order to work.
 **max_length**            Yes        Returns FALSE if the form element is longer then the parameter value.                         max_length[12]         
 **exact_length**          Yes        Returns FALSE if the form element is not exactly the parameter value.                         exact_length[8]        
 **greater_than**          Yes        Returns FALSE if the form element is less than or equal to the parameter value or not         greater_than[8]
@@ -886,10 +885,11 @@ Rule                      Parameter  Description
                                      0, 1, 2, 3, etc.
 **is_natural_no_zero**    No         Returns FALSE if the form element contains anything other than a natural
                                      number, but not zero: 1, 2, 3, etc.
-**is_unique**             Yes        Returns FALSE if the form element is not unique in a database table.                          is_unique[table.field] 
+**valid_url**             No         Returns FALSE if the form element does not contain a valid URL.
 **valid_email**           No         Returns FALSE if the form element does not contain a valid email address.
 **valid_emails**          No         Returns FALSE if any value provided in a comma separated list is not a valid email.
 **valid_ip**              No         Returns FALSE if the supplied IP is not valid.
+                                     Accepts an optional parameter of 'ipv4' or 'ipv6' to specify an IP format.
 **valid_base64**          No         Returns FALSE if the supplied string contains anything other than valid Base64 characters.
 ========================= ========== ============================================================================================= =======================
 
@@ -919,8 +919,8 @@ Name                 Parameter Description
 **encode_php_tags**  No        Converts PHP tags to entities.
 ==================== ========= ===================================================================================================
 
-.. note:: You can also use any native PHP functions that permit one
-	parameter, like trim, htmlspecialchars, urldecode, etc.
+.. note:: You can also use any native PHP functions that permits one
+	parameter, like ``trim()``, ``htmlspecialchars()``, ``urldecode()``, etc.
 
 .. _function-reference:
 
@@ -934,15 +934,15 @@ The following functions are intended for use in your controller
 functions.
 
 $this->form_validation->set_rules();
-======================================
+====================================
 
 	.. php:method:: set_rules ($field, $label = '', $rules = '')
 
 		:param string $field: The field name
 		:param string $label: The field label
-		:param string $rules: The rules, seperated by a pipe "|"
+		:param mixed $rules: The rules, as a string with rules separated by a pipe "|", or an array or rules.
 		:rtype: Object
-	
+
 		Permits you to set validation rules, as described in the tutorial
 		sections above:
 
@@ -950,19 +950,19 @@ $this->form_validation->set_rules();
 	-  :ref:`saving-groups`
 
 $this->form_validation->run();
-===============================
+==============================
 	
 	.. php:method:: run ($group = '')
 
 		:param string $group: The name of the validation group to run
 		:rtype: Boolean
-	
+
 		Runs the validation routines. Returns boolean TRUE on success and FALSE
 		on failure. You can optionally pass the name of the validation group via
 		the function, as described in: :ref:`saving-groups`
 
 $this->form_validation->set_message();
-========================================
+======================================
 	
 	.. php:method:: set_message ($lang, $val = '')
 
@@ -973,7 +973,7 @@ $this->form_validation->set_message();
 		Permits you to set custom error messages. See :ref:`setting-error-messages`
 
 $this->form_validation->set_data();
-========================================
+===================================
 	
 	.. php:method:: set_data ($data = '')
 
@@ -985,13 +985,13 @@ $this->form_validation->set_data();
 $this->form_validation->reset_validation();
 ===========================================
 
- .. php:method:: reset_validation ()
+	.. php:method:: reset_validation ()
 
-    Permits you to reset the validation when you validate more than one array.
-	This function should be called before validating each new array.
+		Permits you to reset the validation when you validate more than one array.
+		This method should be called before validating each new array.
 
 $this->form_validation->error_array();
-========================================
+======================================
 	
 	.. php:method:: error_array ()
 
@@ -1010,7 +1010,7 @@ containing your forms. Note that these are procedural functions, so they
 **do not** require you to prepend them with $this->form_validation.
 
 form_error()
-=============
+============
 
 Shows an individual error message associated with the field name
 supplied to the function. Example::
@@ -1021,7 +1021,7 @@ The error delimiters can be optionally specified. See the
 :ref:`changing-delimiters` section above.
 
 validation_errors()
-====================
+===================
 
 Shows all error messages as a string: Example::
 
@@ -1031,7 +1031,7 @@ The error delimiters can be optionally specified. See the
 :ref:`changing-delimiters` section above.
 
 set_value()
-============
+===========
 
 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. The
@@ -1043,7 +1043,7 @@ form. Example::
 The above form will show "0" when loaded for the first time.
 
 set_select()
-=============
+============
 
 If you use a <select> menu, this function permits you to display the
 menu item that was selected. The first parameter must contain the name
@@ -1060,7 +1060,7 @@ Example::
 	</select>
 
 set_checkbox()
-===============
+==============
 
 Permits you to display a checkbox in the state it was submitted. The
 first parameter must contain the name of the checkbox, the second
@@ -1071,7 +1071,7 @@ lets you set an item as the default (use boolean TRUE/FALSE). Example::
 	<input type="checkbox" name="mycheck[]" value="2" <?php echo set_checkbox('mycheck[]', '2'); ?> />
 
 set_radio()
-============
+===========
 
 Permits you to display radio buttons in the state they were submitted.
 This function is identical to the **set_checkbox()** function above.
author	Eric Roberts <eric@cryode.com>	2012-12-12 14:02:11 +0100
committer	Eric Roberts <eric@cryode.com>	2012-12-12 14:02:11 +0100
commit	b9e35f21e1c70b6aa67c47e9244ed83195abc00a (patch)
tree	64f82db362deeac48cc20d1d1afd80651f36f5a5 /user_guide_src/source/libraries/form_validation.rst
parent	0b05705c52c3bca7f9b3aee657c888e8ad1ff422 (diff)
parent	545a7c86701875e1412bcde316e9bcc76d9a23a0 (diff)