Show
Ignore:
Timestamp:
02/23/06 20:09:13 (6 years ago)
Author:
john
Message:

added in phpDoc commenting tests docs - Walt

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/trax/vendor/trax/action_view/helpers/form_options_helper.php

    r117 r138  
    11<?php 
    2 # $Id$ 
    3 # 
    4 # Copyright (c) 2005 John Peterson 
    5 # 
    6 # Permission is hereby granted, free of charge, to any person obtaining 
    7 # a copy of this software and associated documentation files (the 
    8 # "Software"), to deal in the Software without restriction, including 
    9 # without limitation the rights to use, copy, modify, merge, publish, 
    10 # distribute, sublicense, and/or sell copies of the Software, and to 
    11 # permit persons to whom the Software is furnished to do so, subject to 
    12 # the following conditions: 
    13 # 
    14 # The above copyright notice and this permission notice shall be 
    15 # included in all copies or substantial portions of the Software. 
    16 # 
    17 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
    18 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
    19 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
    20 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 
    21 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
    22 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 
    23 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 
    24  
    25 # All the countries included in the country_options output. 
     2/** 
     3 *  File containing the FormOptionsHelper class and support functions 
     4 * 
     5 *  (PHP 5) 
     6 * 
     7 *  @package PHPonTrax 
     8 *  @version $Id$ 
     9 *  @copyright (c) 2005 John Peterson 
     10 * 
     11 *  Permission is hereby granted, free of charge, to any person obtaining 
     12 *  a copy of this software and associated documentation files (the 
     13 *  "Software"), to deal in the Software without restriction, including 
     14 *  without limitation the rights to use, copy, modify, merge, publish, 
     15 *  distribute, sublicense, and/or sell copies of the Software, and to 
     16 *  permit persons to whom the Software is furnished to do so, subject to 
     17 *  the following conditions: 
     18 * 
     19 *  The above copyright notice and this permission notice shall be 
     20 *  included in all copies or substantial portions of the Software. 
     21 * 
     22 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
     23 *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
     24 *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
     25 *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 
     26 *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
     27 *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 
     28 *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 
     29 */ 
     30 
     31/** 
     32 * All the countries included in the country_options output. 
     33 */ 
    2634if(!$GLOBALS['COUNTRIES']) { 
    2735    $GLOBALS['COUNTRIES'] =  
    … …  
    7280} 
    7381 
     82/** 
     83 * 
     84 *  @package PHPonTrax 
     85 */ 
    7486class FormOptionsHelper extends FormHelper { 
    7587     
    76     # Accepts a container (hash, array, enumerable, your type) and returns a string of option tags. Given a container 
    77     # where the elements respond to first and last (such as a two-element array), the "lasts" serve as option values and 
    78     # the "firsts" as option text. Hashes are turned into this form automatically, so the keys become "firsts" and values 
    79     # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag.  +Selected+ 
    80     # may also be an array of values to be selected when using a multiple select. 
    81     # 
    82     # Examples (call, result): 
    83     #   options_for_select([["Dollar", "$"], ["Kroner", "DKK"]]) 
    84     #     <option value="$">Dollar</option>\n<option value="DKK">Kroner</option> 
    85     # 
    86     #   options_for_select([ "VISA", "MasterCard" ], "MasterCard") 
    87     #     <option>VISA</option>\n<option selected="selected">MasterCard</option> 
    88     # 
    89     #   options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40") 
    90     #     <option value="$20">Basic</option>\n<option value="$40" selected="selected">Plus</option> 
    91     # 
    92     #   options_for_select([ "VISA", "MasterCard", "Discover" ], ["VISA", "Discover"]) 
    93     #     <option selected="selected">VISA</option>\n<option>MasterCard</option>\n<option selected="selected">Discover</option> 
    94     # 
    95     # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag. 
     88    /** 
     89     *  Accepts a container (hash, array, enumerable, your type) and returns a string of option tags. Given a container 
     90     *  where the elements respond to first and last (such as a two-element array), the "lasts" serve as option values and 
     91     *  the "firsts" as option text. Hashes are turned into this form automatically, so the keys become "firsts" and values 
     92     *  become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag.  +Selected+ 
     93     *  may also be an array of values to be selected when using a multiple select. 
     94     *  
     95     *  Examples (call, result): 
     96     *    options_for_select([["Dollar", "$"], ["Kroner", "DKK"]]) 
     97     *      <option value="$">Dollar</option>\n<option value="DKK">Kroner</option> 
     98     *  
     99     *    options_for_select([ "VISA", "MasterCard" ], "MasterCard") 
     100     *      <option>VISA</option>\n<option selected="selected">MasterCard</option> 
     101     *  
     102     *    options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40") 
     103     *      <option value="$20">Basic</option>\n<option value="$40" selected="selected">Plus</option> 
     104     *  
     105     *    options_for_select([ "VISA", "MasterCard", "Discover" ], ["VISA", "Discover"]) 
     106     *      <option selected="selected">VISA</option>\n<option>MasterCard</option>\n<option selected="selected">Discover</option> 
     107     *  
     108     *  NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag. 
     109     */ 
    96110    function options_for_select($choices, $selected = null) { 
    97111        $options = array(); 
    … …  
    113127    } 
    114128     
    115     # Returns a string of option tags that have been compiled by iterating over the +collection+ and assigning the 
    116     # the result of a call to the +value_method+ as the option value and the +text_method+ as the option text. 
    117     # If +selected_value+ is specified, the element returning a match on +value_method+ will get the selected option tag. 
    118     # 
    119     # Example (call, result). Imagine a loop iterating over each +person+ in <tt>@project.people</tt> to generate an input tag: 
    120     #   options_from_collection_for_select(@project.people, "id", "name") 
    121     #     <option value="#{person.id}">#{person.name}</option> 
    122     # 
    123     # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag. 
     129    /** 
     130     * Returns a string of option tags that have been compiled by iterating over the +collection+ and assigning the 
     131     * the result of a call to the +value_method+ as the option value and the +text_method+ as the option text. 
     132     * If +selected_value+ is specified, the element returning a match on +value_method+ will get the selected option tag. 
     133     * 
     134     * Example (call, result). Imagine a loop iterating over each +person+ in <tt>@project.people</tt> to generate an input tag: 
     135     *   options_from_collection_for_select(@project.people, "id", "name") 
     136     *     <option value="#{person.id}">#{person.name}</option> 
     137     * 
     138     * NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag. 
     139     */ 
    124140    function options_from_collection_for_select($collection, $attribute_value, $attribute_text, $selected_value = null) { 
    125141        $options = array(); 
    … …  
    134150    } 
    135151     
    136     # Returns a string of option tags for pretty much any country in the world. Supply a country name as +selected+ to 
    137     # have it marked as the selected option tag. You can also supply an array of countries as +priority_countries+, so 
    138     # that they will be listed above the rest of the (long) list. 
    139     # 
    140     # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag. 
     152    /** 
     153     *  Returns a string of option tags for pretty much any country in the world. Supply a country name as +selected+ to 
     154     *  have it marked as the selected option tag. You can also supply an array of countries as +priority_countries+, so 
     155     *  that they will be listed above the rest of the (long) list. 
     156     * 
     157     *  NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag. 
     158     */ 
    141159    function country_options_for_select($selected = null, $priority_countries = array()) { 
    142160        $country_options = ""; 
    … …  
    155173    } 
    156174     
     175    /** 
     176     * 
     177     */ 
    157178    function to_select_tag($choices, $options, $html_options) { 
    158179        $html_options = $this->add_default_name_and_id($html_options); 
    … …  
    160181    } 
    161182     
     183    /** 
     184     * 
     185     */ 
    162186    function to_collection_select_tag($collection, $attribute_value, $attribute_text, $options, $html_options) { 
    163187        $html_options = $this->add_default_name_and_id($html_options); 
    … …  
    165189    } 
    166190     
     191    /** 
     192     * 
     193     */ 
    167194    function to_country_select_tag($priority_countries, $options, $html_options) { 
    168195        $html_options = $this->add_default_name_and_id($html_options); 
    … …  
    170197    } 
    171198 
     199    /** 
     200     * 
     201     */ 
    172202    private function add_options($option_tags, $options, $value = null) { 
    173203        if($options["include_blank"] == true) { 
    … …  
    184214} 
    185215 
    186 ################################################################################################ 
    187 ## Avialble functions for use in views 
    188 ################################################################################################ 
    189 # Create a select tag and a series of contained option tags for the provided object and method. 
    190 # The option currently held by the object will be selected, provided that the object is available. 
    191 # See options_for_select for the required format of the choices parameter. 
    192 # 
    193 # Example with @post.person_id => 1: 
    194 #   select("post", "person_id", Person.find_all.collect {|p| [ p.name, p.id ] }, { :include_blank => true }) 
    195 # 
    196 # could become: 
    197 # 
    198 #   <select name="post[person_id"> 
    199 #     <option></option> 
    200 #     <option value="1" selected="selected">David</option> 
    201 #     <option value="2">Sam</option> 
    202 #     <option value="3">Tobias</option> 
    203 #   </select> 
    204 # 
    205 # This can be used to provide a functionault set of options in the standard way: before r}ering the create form, a 
    206 # new model instance is assigned the functionault options and bound to @model_name. Usually this model is not saved 
    207 # to the database. Instead, a second model object is created when the create request is received. 
    208 # This allows the user to submit a form page more than once with the expected results of creating multiple records. 
    209 # In addition, this allows a single partial to be used to generate form inputs for both edit and create forms. 
     216/** 
     217 * Avialble functions for use in views 
     218 * Create a select tag and a series of contained option tags for the provided object and method. 
     219 * The option currently held by the object will be selected, provided that the object is available. 
     220 * See options_for_select for the required format of the choices parameter. 
     221# 
     222 * Example with @post.person_id => 1: 
     223 *   select("post", "person_id", Person.find_all.collect {|p| [ p.name, p.id ] }, { :include_blank => true }) 
     224# 
     225 * could become: 
     226# 
     227 *   <select name="post[person_id"> 
     228 *     <option></option> 
     229 *     <option value="1" selected="selected">David</option> 
     230 *     <option value="2">Sam</option> 
     231 *     <option value="3">Tobias</option> 
     232 *   </select> 
     233# 
     234 * This can be used to provide a functionault set of options in the standard way: before r}ering the create form, a 
     235 * new model instance is assigned the functionault options and bound to @model_name. Usually this model is not saved 
     236 * to the database. Instead, a second model object is created when the create request is received. 
     237 * This allows the user to submit a form page more than once with the expected results of creating multiple records. 
     238 * In addition, this allows a single partial to be used to generate form inputs for both edit and create forms. 
     239 */ 
    210240function select($object_name, $attribute_name, $choices, $options = array(), $html_options = array()) { 
    211241    $form = new FormOptionsHelper($object_name, $attribute_name); 
    … …  
    213243} 
    214244 
    215 # Return select and option tags for the given object and method using  
    216 # options_from_collection_for_select to generate the list of option tags. 
     245/** 
     246 * Return select and option tags for the given object and method using  
     247 * options_from_collection_for_select to generate the list of option tags. 
     248 */ 
    217249function collection_select($object_name, $attribute_name, $collection, $attribute_value, $attribute_text, $options = array(), $html_options = array()) { 
    218250    $form = new FormOptionsHelper($object_name, $attribute_name); 
    … …  
    220252} 
    221253 
    222 # Return select and option tags for the given object and method, using country_options_for_select to generate the list of option tags. 
     254/** 
     255 * Return select and option tags for the given object and method, using country_options_for_select to generate the list of option tags. 
     256 */ 
    223257function country_select($object_name, $attribute_name, $priority_countries = null, $options = array(), $html_options = array()) { 
    224258    $form = new FormOptionsHelper($object_name, $attribute_name);