From 3530fc0d3a67cac0bb0679ef4e50271f6f658adf Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 11:14:53 -0700 Subject: Update Form helper docs --- user_guide_src/source/helpers/form_helper.rst | 768 ++++++++++++-------------- 1 file changed, 362 insertions(+), 406 deletions(-) diff --git a/user_guide_src/source/helpers/form_helper.rst b/user_guide_src/source/helpers/form_helper.rst index fd66f0191..5bc5887aa 100644 --- a/user_guide_src/source/helpers/form_helper.rst +++ b/user_guide_src/source/helpers/form_helper.rst @@ -5,7 +5,12 @@ Form Helper The Form Helper file contains functions that assist in working with forms. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + +
Loading this Helper =================== @@ -14,233 +19,218 @@ This helper is loaded using the following code:: $this->load->helper('form'); +Available Functions +=================== + The following functions are available: -form_open() -=========== -.. function:: form_open($action = '', $attributes = '', $hidden = array()) +.. function:: form_open([$action = ''[, $attributes = ''[, $hidden = array()]]]) :param string $action: Form action/target URI string :param string $attributes: HTML attributes :param array $hidden: An array of hidden fields' definitions :returns: string -Creates an opening form tag with a base URL **built from your config preferences**. -It will optionally let you add form attributes and hidden input fields, and -will always add the `accept-charset` attribute based on the charset value in your -config file. + Creates an opening form tag with a base URL **built from your config preferences**. + It will optionally let you add form attributes and hidden input fields, and + will always add the `accept-charset` attribute based on the charset value in your + config file. -The main benefit of using this tag rather than hard coding your own HTML is that -it permits your site to be more portable in the event your URLs ever change. + The main benefit of using this tag rather than hard coding your own HTML is that + it permits your site to be more portable in the event your URLs ever change. -Here's a simple example:: + Here's a simple example:: - echo form_open('email/send'); + echo form_open('email/send'); -The above example would create a form that points to your base URL plus the -"email/send" URI segments, like this:: + The above example would create a form that points to your base URL plus the + "email/send" URI segments, like this:: -
+ -Adding Attributes -^^^^^^^^^^^^^^^^^ + **Adding Attributes** -Attributes can be added by passing an associative array to the second -parameter, like this:: + Attributes can be added by passing an associative array to the second + parameter, like this:: - $attributes = array('class' => 'email', 'id' => 'myform'); - echo form_open('email/send', $attributes); + $attributes = array('class' => 'email', 'id' => 'myform'); + echo form_open('email/send', $attributes); -The above example would create a form similar to this:: + The above example would create a form similar to this:: - + -Adding Hidden Input Fields -^^^^^^^^^^^^^^^^^^^^^^^^^^ + **Adding Hidden Input Fields** -Hidden fields can be added by passing an associative array to the -third parameter, like this:: + Hidden fields can be added by passing an associative array to the + third parameter, like this:: - $hidden = array('username' => 'Joe', 'member_id' => '234'); - echo form_open('email/send', '', $hidden); + $hidden = array('username' => 'Joe', 'member_id' => '234'); + echo form_open('email/send', '', $hidden); -The above example would create a form similar to this:: + The above example would create a form similar to this:: - - - + + + -form_open_multipart() -===================== -.. function:: form_open_multipart($action = '', $attributes = array(), $hidden = array()) +.. function:: form_open_multipart([$action = ''[, $attributes = array()[, $hidden = array()]]) :param string $action: Form action/target URI string :param string $attributes: HTML attributes :param array $hidden: An array of hidden fields' definitions :returns: string -This function is absolutely identical to :func:`form_open()` above, -except that it adds a *multipart* attribute, which is necessary if you -would like to use the form to upload files with. + This function is absolutely identical to :func:`form_open()` above, + except that it adds a *multipart* attribute, which is necessary if you + would like to use the form to upload files with. -form_hidden() -============= -.. function:: form_hidden($name, $value = '') +.. function:: form_hidden($name[, $value = '']) :param string $name: Field name :param string $value: Field value :returns: string -Lets you generate hidden input fields. You can either submit a -name/value string to create one field:: + Lets you generate hidden input fields. You can either submit a + name/value string to create one field:: - form_hidden('username', 'johndoe'); - // Would produce: + form_hidden('username', 'johndoe'); + // Would produce: -... or you can submit an associative array to create multiple fields:: + ... or you can submit an associative array to create multiple fields:: - $data = array( - 'name' => 'John Doe', - 'email' => 'john@example.com', - 'url' => 'http://example.com' - ); + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); - echo form_hidden($data); + echo form_hidden($data); - /* - Would produce: - - - - */ + /* + Would produce: + + + + */ -You can also pass an associative array to the value field:: + You can also pass an associative array to the value field:: - $data = array( - 'name' => 'John Doe', - 'email' => 'john@example.com', - 'url' => 'http://example.com' - ); + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); - echo form_hidden('my_array', $data); + echo form_hidden('my_array', $data); - /* - Would produce: + /* + Would produce: - - - - */ + + + + */ -If you want to create hidden input fields with extra attributes:: + If you want to create hidden input fields with extra attributes:: - $data = array( - 'type' => 'hidden', - 'name' => 'email', - 'id' => 'hiddenemail', - 'value' => 'john@example.com', - 'class' => 'hiddenemail' - ); + $data = array( + 'type' => 'hidden', + 'name' => 'email', + 'id' => 'hiddenemail', + 'value' => 'john@example.com', + 'class' => 'hiddenemail' + ); - echo form_input($data); + echo form_input($data); - /* - Would produce: + /* + Would produce: - - */ + + */ -form_input() -============ -.. function:: form_input($data = '', $value = '', $extra = '') +.. function:: form_input([$data = ''[, $value = ''[, $extra = '']]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -Lets you generate a standard text input field. You can minimally pass -the field name and value in the first and second parameter:: + Lets you generate a standard text input field. You can minimally pass + the field name and value in the first and second parameter:: - echo form_input('username', 'johndoe'); + echo form_input('username', 'johndoe'); -Or you can pass an associative array containing any data you wish your -form to contain:: + Or you can pass an associative array containing any data you wish your + form to contain:: - $data = array( - 'name' => 'username', - 'id' => 'username', - 'value' => 'johndoe', - 'maxlength' => '100', - 'size' => '50', - 'style' => 'width:50%' - ); + $data = array( + 'name' => 'username', + 'id' => 'username', + 'value' => 'johndoe', + 'maxlength' => '100', + 'size' => '50', + 'style' => 'width:50%' + ); - echo form_input($data); + echo form_input($data); - /* - Would produce: + /* + Would produce: - - */ + + */ -If you would like your form to contain some additional data, like -JavaScript, you can pass it as a string in the third parameter:: + If you would like your form to contain some additional data, like + JavaScript, you can pass it as a string in the third parameter:: - $js = 'onClick="some_function()"'; - echo form_input('username', 'johndoe', $js); + $js = 'onClick="some_function()"'; + echo form_input('username', 'johndoe', $js); -form_password() -=============== -.. function:: form_password($data = '', $value = '', $extra = '') +.. function:: form_password([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -This function is identical in all respects to the :func:`form_input()` -function above except that it uses the "password" input type. + This function is identical in all respects to the :func:`form_input()` + function above except that it uses the "password" input type. -form_upload() -============= -.. function:: form_upload($data = '', $value = '', $extra = '') +.. function:: form_upload([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -This function is identical in all respects to the :func:`form_input()` -function above except that it uses the "file" input type, allowing it to -be used to upload files. + This function is identical in all respects to the :func:`form_input()` + function above except that it uses the "file" input type, allowing it to + be used to upload files. -form_textarea() -=============== -.. function:: form_textarea($data = '', $value = '', $extra = '') +.. function:: form_textarea([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -This function is identical in all respects to the :func:`form_input()` -function above except that it generates a "textarea" type. + This function is identical in all respects to the :func:`form_input()` + function above except that it generates a "textarea" type. -.. note: Instead of the *maxlength* and *size* attributes in the above example, - you will instead specify *rows* and *cols*. + .. note:: Instead of the *maxlength* and *size* attributes in the above example, + you will instead specify *rows* and *cols*. -form_dropdown() -=============== -.. function:: form_dropdown($name = '', $options = array(), $selected = array(), $extra = '') +.. function:: form_dropdown([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]]) :param string $name: Field name :param array $options: An associative array of options to be listed @@ -248,64 +238,62 @@ form_dropdown() :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -Lets you create a standard drop-down field. The first parameter will -contain the name of the field, the second parameter will contain an -associative array of options, and the third parameter will contain the -value you wish to be selected. You can also pass an array of multiple -items through the third parameter, and CodeIgniter will create a -multiple select for you. - -Example:: - - $options = array( - 'small' => 'Small Shirt', - 'med' => 'Medium Shirt', - 'large' => 'Large Shirt', - 'xlarge' => 'Extra Large Shirt', - ); - - $shirts_on_sale = array('small', 'large'); - echo form_dropdown('shirts', $options, 'large'); - - /* - Would produce: - - - */ + Lets you create a standard drop-down field. The first parameter will + contain the name of the field, the second parameter will contain an + associative array of options, and the third parameter will contain the + value you wish to be selected. You can also pass an array of multiple + items through the third parameter, and CodeIgniter will create a + multiple select for you. - echo form_dropdown('shirts', $options, $shirts_on_sale); + Example:: - /* - Would produce: + $options = array( + 'small' => 'Small Shirt', + 'med' => 'Medium Shirt', + 'large' => 'Large Shirt', + 'xlarge' => 'Extra Large Shirt', + ); - - */ + $shirts_on_sale = array('small', 'large'); + echo form_dropdown('shirts', $options, 'large'); + + /* + Would produce: + + + */ + + echo form_dropdown('shirts', $options, $shirts_on_sale); -If you would like the opening + + + + + + */ -If the array passed as ``$options`` is a multidimensional array, then -``form_dropdown()`` will produce an with the array key as the -label. + If you would like the opening + echo form_checkbox('newsletter', 'accept', TRUE); + // Would produce: -The third parameter contains a boolean TRUE/FALSE to determine whether -the box should be checked or not. + The third parameter contains a boolean TRUE/FALSE to determine whether + the box should be checked or not. -Similar to the other form functions in this helper, you can also pass an -array of attributes to the function + Similar to the other form functions in this helper, you can also pass an + array of attributes to the function -:: + :: - $data = array( - 'name' => 'newsletter', - 'id'      => 'newsletter', - 'value'   => 'accept', - 'checked' => TRUE, - 'style'   => 'margin:10px' - ); + $data = array( + 'name' => 'newsletter', + 'id'      => 'newsletter', + 'value'   => 'accept', + 'checked' => TRUE, + 'style'   => 'margin:10px' + ); - echo form_checkbox($data); - // Would produce: + echo form_checkbox($data); + // Would produce: -Also as with other functions, if you would like the tag to contain -additional data like JavaScript, you can pass it as a string in the -fourth parameter:: + Also as with other functions, if you would like the tag to contain + additional data like JavaScript, you can pass it as a string in the + fourth parameter:: - $js = 'onClick="some_function()"'; - echo form_checkbox('newsletter', 'accept', TRUE, $js) + $js = 'onClick="some_function()"'; + echo form_checkbox('newsletter', 'accept', TRUE, $js) -form_radio() -============ -.. function:: form_radio($data = '', $value = '', $checked = FALSE, $extra = '') +.. function:: form_radio([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]]) :param array $data: Field attributes data :param string $value: Field value @@ -440,283 +420,259 @@ form_radio() :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -This function is identical in all respects to the :func:`form_checkbox()` -function above except that it uses the "radio" input type. + This function is identical in all respects to the :func:`form_checkbox()` + function above except that it uses the "radio" input type. -form_label() -============ -.. function:: form_label($label_text = '', $id = '', $attributes = array()) +.. function:: form_label([$label_text = ''[, $id = ''[, $attributes = array()]]]) :param string $label_text: Text to put in the