diff options
| -rw-r--r-- | user_guide_src/source/helpers/form_helper.rst | 768 |
1 files 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 + + <div class="custom-index container"></div> 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:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" /> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" /> -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:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform" /> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform" /> -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 method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> - <input type="hidden" name="username" value="Joe" /> - <input type="hidden" name="member_id" value="234" /> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> + <input type="hidden" name="username" value="Joe" /> + <input type="hidden" name="member_id" value="234" /> -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: <input type="hidden" name="username" value="johndoe" /> + form_hidden('username', 'johndoe'); + // Would produce: <input type="hidden" name="username" value="johndoe" /> -... 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: - <input type="hidden" name="name" value="John Doe" /> - <input type="hidden" name="email" value="john@example.com" /> - <input type="hidden" name="url" value="http://example.com" /> - */ + /* + Would produce: + <input type="hidden" name="name" value="John Doe" /> + <input type="hidden" name="email" value="john@example.com" /> + <input type="hidden" name="url" value="http://example.com" /> + */ -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: - <input type="hidden" name="my_array[name]" value="John Doe" /> - <input type="hidden" name="my_array[email]" value="john@example.com" /> - <input type="hidden" name="my_array[url]" value="http://example.com" /> - */ + <input type="hidden" name="my_array[name]" value="John Doe" /> + <input type="hidden" name="my_array[email]" value="john@example.com" /> + <input type="hidden" name="my_array[url]" value="http://example.com" /> + */ -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: - <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> - */ + <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> + */ -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: - <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> - */ + <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> + */ -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: - - <select name="shirts"> - <option value="small">Small Shirt</option> - <option value="med">Medium Shirt</option> - <option value="large" selected="selected">Large Shirt</option> - <option value="xlarge">Extra Large Shirt</option> - </select> - */ + 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', + ); - <select name="shirts" multiple="multiple"> - <option value="small" selected="selected">Small Shirt</option> - <option value="med">Medium Shirt</option> - <option value="large" selected="selected">Large Shirt</option> - <option value="xlarge">Extra Large Shirt</option> - </select> - */ + $shirts_on_sale = array('small', 'large'); + echo form_dropdown('shirts', $options, 'large'); + + /* + Would produce: + + <select name="shirts"> + <option value="small">Small Shirt</option> + <option value="med">Medium Shirt</option> + <option value="large" selected="selected">Large Shirt</option> + <option value="xlarge">Extra Large Shirt</option> + </select> + */ + + echo form_dropdown('shirts', $options, $shirts_on_sale); -If you would like the opening <select> to contain additional data, like -an id attribute or JavaScript, you can pass it as a string in the fourth -parameter:: + /* + Would produce: - $js = 'id="shirts" onChange="some_function();"'; - echo form_dropdown('shirts', $options, 'large', $js); + <select name="shirts" multiple="multiple"> + <option value="small" selected="selected">Small Shirt</option> + <option value="med">Medium Shirt</option> + <option value="large" selected="selected">Large Shirt</option> + <option value="xlarge">Extra Large Shirt</option> + </select> + */ -If the array passed as ``$options`` is a multidimensional array, then -``form_dropdown()`` will produce an <optgroup> with the array key as the -label. + If you would like the opening <select> to contain additional data, like + an id attribute or JavaScript, you can pass it as a string in the fourth + parameter:: -form_multiselect() -================== + $js = 'id="shirts" onChange="some_function();"'; + echo form_dropdown('shirts', $options, 'large', $js); -.. function:: form_multiselect($name = '', $options = array(), $selected = array(), $extra = '') + If the array passed as ``$options`` is a multidimensional array, then + ``form_dropdown()`` will produce an <optgroup> with the array key as the + label. + + +.. function:: form_multiselect([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]]) :param string $name: Field name :param array $options: An associative array of options to be listed @@ -313,84 +301,78 @@ form_multiselect() :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -Lets you create a standard multiselect 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 or values you wish to be selected. + Lets you create a standard multiselect 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 or values you wish to be selected. -The parameter usage is identical to using :func:`form_dropdown()` above, -except of course that the name of the field will need to use POST array -syntax, e.g. foo[]. + The parameter usage is identical to using :func:`form_dropdown()` above, + except of course that the name of the field will need to use POST array + syntax, e.g. foo[]. -form_fieldset() -=============== -.. function:: form_fieldset($legend_text = '', $attributes = array()) +.. function:: form_fieldset([$legend_text = ''[, $attributes = array()]]) :param string $legend_text: Text to put in the <legend> tag :param array $attributes: Attributes to be set on the <fieldset> tag :returns: string -Lets you generate fieldset/legend fields. + Lets you generate fieldset/legend fields. -Example:: + Example:: - echo form_fieldset('Address Information'); - echo "<p>fieldset content here</p>\n"; - echo form_fieldset_close(); + echo form_fieldset('Address Information'); + echo "<p>fieldset content here</p>\n"; + echo form_fieldset_close(); - /* - Produces: + /* + Produces: - <fieldset> - <legend>Address Information</legend> - <p>form content here</p> - </fieldset> - */ + <fieldset> + <legend>Address Information</legend> + <p>form content here</p> + </fieldset> + */ -Similar to other functions, you can submit an associative array in the -second parameter if you prefer to set additional attributes:: + Similar to other functions, you can submit an associative array in the + second parameter if you prefer to set additional attributes:: - $attributes = array( - 'id' => 'address_info', - 'class' => 'address_info' - ); + $attributes = array( + 'id' => 'address_info', + 'class' => 'address_info' + ); - echo form_fieldset('Address Information', $attributes); - echo "<p>fieldset content here</p>\n"; - echo form_fieldset_close(); + echo form_fieldset('Address Information', $attributes); + echo "<p>fieldset content here</p>\n"; + echo form_fieldset_close(); - /* - Produces: + /* + Produces: - <fieldset id="address_info" class="address_info"> - <legend>Address Information</legend> - <p>form content here</p> - </fieldset> - */ + <fieldset id="address_info" class="address_info"> + <legend>Address Information</legend> + <p>form content here</p> + </fieldset> + */ -form_fieldset_close() -===================== -.. function:: form_fieldset_close($extra = '') +.. function:: form_fieldset_close([$extra = '']) :param string $extra: Anything to append after the closing tag, *as is* :returns: string -Produces a closing </fieldset> tag. The only advantage to using this -function is it permits you to pass data to it which will be added below -the tag. For example + Produces a closing </fieldset> tag. The only advantage to using this + function is it permits you to pass data to it which will be added below + the tag. For example -:: + :: - $string = '</div></div>'; - echo form_fieldset_close($string); - // Would produce: </fieldset></div></div> + $string = '</div></div>'; + echo form_fieldset_close($string); + // Would produce: </fieldset></div></div> -form_checkbox() -=============== -.. function:: form_checkbox($data = '', $value = '', $checked = FALSE, $extra = '') +.. function:: form_checkbox([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]]) :param array $data: Field attributes data :param string $value: Field value @@ -398,41 +380,39 @@ form_checkbox() :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -Lets you generate a checkbox field. Simple example:: + Lets you generate a checkbox field. Simple example:: - echo form_checkbox('newsletter', 'accept', TRUE); - // Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" /> + echo form_checkbox('newsletter', 'accept', TRUE); + // Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" /> -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: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" /> + echo form_checkbox($data); + // Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" /> -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 <label> tag :param string $id: ID of the form element that we're making a label for :param string $attributes: HTML attributes :returns: string -Lets you generate a <label>. Simple example:: + Lets you generate a <label>. Simple example:: - echo form_label('What is your Name', 'username'); - // Would produce: <label for="username">What is your Name</label> + echo form_label('What is your Name', 'username'); + // Would produce: <label for="username">What is your Name</label> -Similar to other functions, you can submit an associative array in the -third parameter if you prefer to set additional attributes. + Similar to other functions, you can submit an associative array in the + third parameter if you prefer to set additional attributes. -Example:: + Example:: - $attributes = array( - 'class' => 'mycustomclass', - 'style' => 'color: #000;' - ); + $attributes = array( + 'class' => 'mycustomclass', + 'style' => 'color: #000;' + ); - echo form_label('What is your Name', 'username', $attributes); - // Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label> + echo form_label('What is your Name', 'username', $attributes); + // Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label> -form_submit() -============= -.. function:: form_submit($data = '', $value = '', $extra = '') +.. function:: form_submit([$data = ''[, $value = ''[, $extra = '']]]) :param string $data: Button name :param string $value: Button value :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -Lets you generate a standard submit button. Simple example:: + Lets you generate a standard submit button. Simple example:: - echo form_submit('mysubmit', 'Submit Post!'); - // Would produce: <input type="submit" name="mysubmit" value="Submit Post!" /> + echo form_submit('mysubmit', 'Submit Post!'); + // Would produce: <input type="submit" name="mysubmit" value="Submit Post!" /> -Similar to other functions, you can submit an associative array in the -first parameter if you prefer to set your own attributes. The third -parameter lets you add extra data to your form, like JavaScript. + Similar to other functions, you can submit an associative array in the + first parameter if you prefer to set your own attributes. The third + parameter lets you add extra data to your form, like JavaScript. -form_reset() -============ -.. function:: form_reset($data = '', $value = '', $extra = '') +.. function:: form_reset([$data = ''[, $value = ''[, $extra = '']]]) :param string $data: Button name :param string $value: Button value :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -Lets you generate a standard reset button. Use is identical to -:func:`form_submit()`. + Lets you generate a standard reset button. Use is identical to + :func:`form_submit()`. -form_button() -============= -.. function:: form_button($data = '', $content = '', $extra = '') +.. function:: form_button([$data = ''[, $content = ''[, $extra = '']]]) :param string $data: Button name :param string $content: Button label :param string $extra: Extra attributes to be added to the tag *as is* :returns: string -Lets you generate a standard button element. You can minimally pass the -button name and content in the first and second parameter:: + Lets you generate a standard button element. You can minimally pass the + button name and content in the first and second parameter:: - echo form_button('name','content'); - // Would produce: <button name="name" type="button">Content</button> + echo form_button('name','content'); + // Would produce: <button name="name" type="button">Content</button> -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' => 'button', - 'id' => 'button', - 'value' => 'true', - 'type' => 'reset', - 'content' => 'Reset' - ); + $data = array( + 'name' => 'button', + 'id' => 'button', + 'value' => 'true', + 'type' => 'reset', + 'content' => 'Reset' + ); - echo form_button($data); - // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button> + echo form_button($data); + // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button> -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_button('mybutton', 'Click Me', $js); + $js = 'onClick="some_function()"'; + echo form_button('mybutton', 'Click Me', $js); -form_close() -============ -.. function:: form_close($extra = '') +.. function:: form_close([$extra = '']) :param string $extra: Anything to append after the closing tag, *as is* :returns: string -Produces a closing </form> tag. The only advantage to using this -function is it permits you to pass data to it which will be added below -the tag. For example:: + Produces a closing </form> tag. The only advantage to using this + function is it permits you to pass data to it which will be added below + the tag. For example:: - $string = '</div></div>'; - echo form_close($string); - // Would produce: </form> </div></div> + $string = '</div></div>'; + echo form_close($string); + // Would produce: </form> </div></div> -form_prep() -=========== -.. function:: form_prep($str = '', $is_textarea = FALSE) +.. function:: form_prep([$str = ''[, $is_textarea = FALSE]]) :param string $str: Value to escape :param bool $is_textarea: Whether we're preparing for <textarea> or a regular input tag :returns: string -Allows you to safely use HTML and characters such as quotes within form -elements without breaking out of the form. + Allows you to safely use HTML and characters such as quotes within form + elements without breaking out of the form. -Consider this example:: + Consider this example:: - $string = 'Here is a string containing "quoted" text.'; - <input type="text" name="myform" value="$string" /> + $string = 'Here is a string containing "quoted" text.'; + <input type="text" name="myform" value="$string" /> -Since the above string contains a set of quotes it will cause the form -to break. The ``form_prep()`` function converts HTML so that it can be used -safely:: + Since the above string contains a set of quotes it will cause the form + to break. The ``form_prep()`` function converts HTML so that it can be used + safely:: - <input type="text" name="myform" value="<?php echo form_prep($string); ?>" /> + <input type="text" name="myform" value="<?php echo form_prep($string); ?>" /> -.. note:: If you use any of the form helper functions listed in this page the form - values will be prepped automatically, so there is no need to call this - function. Use it only if you are creating your own form elements. + .. note:: If you use any of the form helper functions listed in this page the form + values will be prepped automatically, so there is no need to call this + function. Use it only if you are creating your own form elements. -set_value() -=========== -.. function:: set_value($field = '', $default = '', $is_textarea = FALSE) +.. function:: set_value([$field = ''[, $default = ''[, $is_textarea = FALSE]]]) :param string $field: Field name :param string $default: Default value :param bool $is_textarea: Whether we're setting <textarea> content :returns: string -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 -second (optional) parameter allows you to set a default value for the -form. + 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 + second (optional) parameter allows you to set a default value for the + form. -Example:: + Example:: - <input type="text" name="quantity" value="<?=set_value('quantity', '0');?>" size="50" /> + <input type="text" name="quantity" value="<?=set_value('quantity', '0');?>" size="50" /> -The above form will show "0" when loaded for the first time. + The above form will show "0" when loaded for the first time. -set_select() -============ -.. function:: set_select($field = '', $value = '', $default = FALSE) +.. function:: set_select([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one :returns: string -If you use a <select> menu, this function permits you to display the -menu item that was selected. + 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 of the select menu, the second -parameter must contain the value of each item, and the third (optional) -parameter lets you set an item as the default (use boolean TRUE/FALSE). + The first parameter must contain the name of the select menu, the second + parameter must contain the value of each item, and the third (optional) + parameter lets you set an item as the default (use boolean TRUE/FALSE). -Example:: + Example:: - <select name="myselect"> - <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> - <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> - <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> - </select> + <select name="myselect"> + <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> + <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> + <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> + </select> -set_checkbox() -============== -.. function:: set_checkbox($field = '', $value = '', $default = FALSE) +.. function:: set_checkbox([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one :returns: string -Permits you to display a checkbox in the state it was submitted. + Permits you to display a checkbox in the state it was submitted. -The first parameter 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). + The first parameter 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:: + Example:: - <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> /> - <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> /> + <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> /> + <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> /> -set_radio() -=========== -.. function:: set_radio($field = '', $value = '', $default = FALSE) +.. function:: set_radio([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one :returns: string -Permits you to display radio buttons in the state they were submitted. -This function is identical to the :func:`set_checkbox()` function above. + Permits you to display radio buttons in the state they were submitted. + This function is identical to the :func:`set_checkbox()` function above. -Example:: + Example:: - <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> - <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> + <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> + <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> -.. note:: If you are using the Form Validation class, you must always specify - a rule for your field, even if empty, in order for the ``set_*()`` - functions to work. This is because if a Form Validation object is - defined, the control for ``set_*()`` is handed over to a method of the - class instead of the generic helper function. + .. note:: If you are using the Form Validation class, you must always specify + a rule for your field, even if empty, in order for the ``set_*()`` + functions to work. This is because if a Form Validation object is + defined, the control for ``set_*()`` is handed over to a method of the + class instead of the generic helper function. -form_error() -============ -.. function:: form_error($field = '', $prefix = '', $suffix = '') +.. function:: form_error([$field = ''[, $prefix = ''[, $suffix = '']]]) :param string $field: Field name :param string $prefix: Error opening tag :param string $suffix: Error closing tag :returns: string -Returns a validation error message from the :doc:`Form Validation Library -<../libraries/form_validation>`, associated with the specified field name. -You can optionally specify opening and closing tag(s) to put around the error -message. + Returns a validation error message from the :doc:`Form Validation Library + <../libraries/form_validation>`, associated with the specified field name. + You can optionally specify opening and closing tag(s) to put around the error + message. -Example:: + Example:: - // Assuming that the 'username' field value was incorrect: - echo form_error('myfield', '<div class="error">', '</div>'); + // Assuming that the 'username' field value was incorrect: + echo form_error('myfield', '<div class="error">', '</div>'); - // Would produce: <div class="error">Error message associated with the "username" field.</div> + // Would produce: <div class="error">Error message associated with the "username" field.</div> -validation_errors() -=================== -.. function:: validation_errors($prefix = '', $suffix = '') +.. function:: validation_errors([$prefix = ''[, $suffix = '']]) :param string $prefix: Error opening tag :param string $suffix: Error closing tag :returns: string -Similarly to the :func:`form_error()` function, returns all validation -error messages produced by the :doc:`Form Validation Library -<../libraries/form_validation>`, with optional opening and closing tags -around each of the messages. + Similarly to the :func:`form_error()` function, returns all validation + error messages produced by the :doc:`Form Validation Library + <../libraries/form_validation>`, with optional opening and closing tags + around each of the messages. -Example:: + Example:: - echo validation_errors('<span class="error">', '</span>'); + echo validation_errors('<span class="error">', '</span>'); - /* - Would produce, e.g.: + /* + Would produce, e.g.: - <span class="error">The "email" field doesn't contain a valid e-mail address!</span> - <span class="error">The "password" field doesn't match the "repeat_password" field!</span> + <span class="error">The "email" field doesn't contain a valid e-mail address!</span> + <span class="error">The "password" field doesn't match the "repeat_password" field!</span> - */
\ No newline at end of file + */
\ No newline at end of file |