Changeset 1466

Timestamp:

06/16/06 16:56:47 (2 years ago)

Author:

fabien

Message:

added API documentation (patch from slickrick)

Files:

• trunk/lib/helper/FormHelper.php (modified) (9 diffs)

trunk/lib/helper/FormHelper.php

@@ -22 +22 @@
- */
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-*/
-function options_for_select($options = array(), $selected = '', $html_options = array())
@@ -96 +108 @@
-}
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-*/
-function form_tag($url_for_options = '', $options = array())
@@ -124 +147 @@
-}
-
+/**
+* Returns a <select> tag, optionally comprised of <option> tags.
+*
+* The select tag does not generate <option> tags by default.  
+* To do so, you must populate the <i>$option_tags</i> variable with a string of valid HTML compliant <option> tags.
+* Fortunately, Symfony provides a handy helper function to convert an array of data into option tags (see options_for_select). 
+* If you need to create a "multiple" select tag (ability to select multiple options), set the <i>multiple</i> option to true.  
+* Doing so will automatically convert the name field to an array type variable (i.e. name="name" becomes name="name[]").
+* 
+* <b>Options:</b>
+* - multiple - If set to true, the select tag will allow multiple options to be selected at once.
+*
+* <b>Examples:</b>
+* <code>
+*  $person_list = array(1 => 'Larry', 2 => 'Moe', 3 => 'Curly');
+*  echo select_tag('person', options_for_select($person_list, $sf_params->get('person')), array('class' => 'full'));
+* </code>
+*
+* <code>
+*  echo select_tag('department', options_for_select($department_list), array('multiple' => true));
+* </code>
+*
+* <code>
+*  echo select_tag('url', options_for_select($url_list), array('onChange' => 'Javascript:this.form.submit();'));
+* </code>
+*
+* @param  string field name 
+* @param  string contains a string of valid <option></option> tags
+* @param  array  additional HTML compliant <select> tag parameters
+* @return string <select> tag optionally comprised of <option> tags.
+* @see options_for_select, content_tag
+*/
-function select_tag($name, $option_tags = null, $options = array())
-{
@@ -136 +191 @@
-}
-
+/**
+* Returns a <select> tag populated with all the countries in the world.
+*
+* The select_country_tag builds off the traditional select_tag function, and is conveniently populated with 
+* all the countries in the world (sorted alphabetically). Each option in the list has a two-character country 
+* code for its value and the country's name as its display title.  The country data is retrieved via the sfCultureInfo
+* class, which stores a wide variety of i18n and i10n settings for various countries and cultures throughout the world.
+* Here's an example of an <option> tag generated by the select_country_tag:
+*
+* <samp>
+*  <option value="US">United States</option>
+* </samp>
+*
+* <b>Examples:</b>
+* <code>
+*  echo select_country_tag('country', 'FR');
+* </code>
+*
+* @param  string field name 
+* @param  string selected field value (two-character country code)
+* @param  array  additional HTML compliant <select> tag parameters
+* @return string <select> tag populated with all the countries in the world.
+* @see select_tag, options_for_select, sfCultureInfo
+*/
-function select_country_tag($name, $value, $options = array())
-{
@@ -159 +238 @@
-}
-
+/**
+* Returns a <select> tag populated with all the languages in the world (or almost).
+*
+* The select_language_tag builds off the traditional select_tag function, and is conveniently populated with 
+* all the languages in the world (sorted alphabetically). Each option in the list has a two or three character 
+* language/culture code for its value and the language's name as its display title.  The country data is 
+* retrieved via the sfCultureInfo class, which stores a wide variety of i18n and i10n settings for various 
+* countries and cultures throughout the world. Here's an example of an <option> tag generated by the select_country_tag:
+*
+* <samp>
+*  <option value="en">English</option>
+* </samp>
+*
+* <b>Examples:</b>
+* <code>
+*  echo select_language_tag('language', 'de');
+* </code>
+*
+* @param  string field name 
+* @param  string selected field value (two or threecharacter language/culture code)
+* @param  array  additional HTML compliant <select> tag parameters
+* @return string <select> tag populated with all the languages in the world.
+* @see select_tag, options_for_select, sfCultureInfo
+*/
-function select_language_tag($name, $value, $options = array())
-{
@@ -182 +285 @@
-}
-
+/**
+* Returns an XHTML compliant <input> tag with type="text".
+*
+* The input_tag helper generates your basic XHTML <input> tag and can utilize any standard <input> tag parameters 
+* passed in the optional <i>$options</i> variable.
+*
+* <b>Examples:</b>
+* <code>
+*  echo input_tag('name');
+* </code>
+*
+* <code>
+*  echo input_tag('amount', $sf_params->get('amount'), array('size' => 8, 'maxlength' => 8));
+* </code>
+*
+* @param  string field name 
+* @param  string selected field value
+* @param  array  additional HTML compliant <input> tag parameters
+* @return string XHTML compliant <input> tag with type="text"
+*/
-function input_tag($name, $value = null, $options = array())
-{
@@ -187 +310 @@
-}
-
+/**
+* Returns an XHTML compliant <input> tag with type="hidden".
+*
+* Similar to the input_tag helper, the input_hidden_tag helper generates an XHTML <input> tag and can utilize 
+* any standard <input> tag parameters passed in the optional <i>$options</i> variable.  The only difference is 
+* that it creates the tag with type="hidden", meaning that is not visible on the page.
+*
+* <b>Examples:</b>
+* <code>
+*  echo input_hidden_tag('id', $id);
+* </code>
+*
+* @param  string field name 
+* @param  string populated field value
+* @param  array  additional HTML compliant <input> tag parameters
+* @return string XHTML compliant <input> tag with type="hidden"
+*/
-function input_hidden_tag($name, $value = null, $options = array())
-{
@@ -195 +335 @@
-}
-
+/**
+* Returns an XHTML compliant <input> tag with type="file".
+*
+* Similar to the input_tag helper, the input_hidden_tag helper generates your basic XHTML <input> tag and can utilize
+* any standard <input> tag parameters passed in the optional <i>$options</i> variable.  The only difference is that it 
+* creates the tag with type="file", meaning that next to the field will be a "browse" (or similar) button. 
+* This gives the user the ability to choose a file from there computer to upload to the web server.  Remember, if you 
+* plan to upload files to your website, be sure to set the <i>multipart</i> option form_tag helper function to true 
+* or your files will not be properly uploaded to the web server.
+*
+* <b>Examples:</b>
+* <code>
+*  echo input_file_tag('filename', array('size' => 30));
+* </code>
+*
+* @param  string field name 
+* @param  array  additional HTML compliant <input> tag parameters
+* @return string XHTML compliant <input> tag with type="file"
+* @see input_tag, form_tag
+*/
-function input_file_tag($name, $options = array())
-{
@@ -203 +363 @@
-}
-
+/**
+* Returns an XHTML compliant <input> tag with type="password".
+*
+* Similar to the input_tag helper, the input_hidden_tag helper generates your basic XHTML <input> tag and can utilize
+* any standard <input> tag parameters passed in the optional <i>$options</i> variable.  The only difference is that it 
+* creates the tag with type="password", meaning that the text entered into this field will not be visible to the end user.
+* In most cases it is replaced by ********.  Even though this text is not readable, it is recommended that you do not 
+* populate the optional <i>$value</i> option with a plain-text password or any other sensitive information, as this is a 
+* potential security risk.
+*
+* <b>Examples:</b>
+* <code>
+*  echo input_password_tag('password');
+*  echo input_password_tag('password_confirm');
+* </code>
+*
+* @param  string field name
+* @param  string populated field value
+* @param  array  additional HTML compliant <input> tag parameters
+* @return string XHTML compliant <input> tag with type="password"
+* @see input_tag
+*/
-function input_password_tag($name = 'password', $value = null, $options = array())
-{