[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   *  File containing the FormOptionsHelper class and support functions
   4   *
   5   *  (PHP 5)
   6   *
   7   *  @package PHPonTrax
   8   *  @version $Id: form_options_helper.php 243 2006-08-23 05:25:24Z john $
   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   */
  34  if(!array_key_exists('COUNTRIES',$GLOBALS)) {
  35      $GLOBALS['COUNTRIES'] = 
  36          array("Afghanistan", "Albania", "Algeria", "American Samoa", "Andorra", "Angola", "Anguilla", 
  37          "Antarctica", "Antigua And Barbuda", "Argentina", "Armenia", "Aruba", "Australia", 
  38          "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", 
  39          "Belgium", "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", "Bosnia and Herzegowina", 
  40          "Botswana", "Bouvet Island", "Brazil", "British Indian Ocean Territory", 
  41          "Brunei Darussalam", "Bulgaria", "Burkina Faso", "Burma", "Burundi", "Cambodia", 
  42          "Cameroon", "Canada", "Cape Verde", "Cayman Islands", "Central African Republic", 
  43          "Chad", "Chile", "China", "Christmas Island", "Cocos (Keeling) Islands", "Colombia", 
  44          "Comoros", "Congo", "Congo, the Democratic Republic of the", "Cook Islands", 
  45          "Costa Rica", "Cote d'Ivoire", "Croatia", "Cuba", "Cyprus", "Czech Republic", "Denmark", 
  46          "Djibouti", "Dominica", "Dominican Republic", "East Timor", "Ecuador", "Egypt", 
  47          "El Salvador", "England", "Equatorial Guinea", "Eritrea", "Espana", "Estonia", 
  48          "Ethiopia", "Falkland Islands", "Faroe Islands", "Fiji", "Finland", "France", 
  49          "French Guiana", "French Polynesia", "French Southern Territories", "Gabon", "Gambia", 
  50          "Georgia", "Germany", "Ghana", "Gibraltar", "Great Britain", "Greece", "Greenland", 
  51          "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guinea", "Guinea-Bissau", "Guyana", 
  52          "Haiti", "Heard and Mc Donald Islands", "Honduras", "Hong Kong", "Hungary", "Iceland", 
  53          "India", "Indonesia", "Ireland", "Israel", "Italy", "Iran", "Iraq", "Jamaica", "Japan", "Jordan", 
  54          "Kazakhstan", "Kenya", "Kiribati", "Korea, Republic of", "Korea (South)", "Kuwait", 
  55          "Kyrgyzstan", "Lao People's Democratic Republic", "Latvia", "Lebanon", "Lesotho", 
  56          "Liberia", "Liechtenstein", "Lithuania", "Luxembourg", "Macau", "Macedonia", 
  57          "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", 
  58          "Martinique", "Mauritania", "Mauritius", "Mayotte", "Mexico", 
  59          "Micronesia, Federated States of", "Moldova, Republic of", "Monaco", "Mongolia", 
  60          "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", "Nauru", "Nepal", 
  61          "Netherlands", "Netherlands Antilles", "New Caledonia", "New Zealand", "Nicaragua", 
  62          "Niger", "Nigeria", "Niue", "Norfolk Island", "Northern Ireland", 
  63          "Northern Mariana Islands", "Norway", "Oman", "Pakistan", "Palau", "Panama", 
  64          "Papua New Guinea", "Paraguay", "Peru", "Philippines", "Pitcairn", "Poland", 
  65          "Portugal", "Puerto Rico", "Qatar", "Reunion", "Romania", "Russia", "Rwanda", 
  66          "Saint Kitts and Nevis", "Saint Lucia", "Saint Vincent and the Grenadines", 
  67          "Samoa (Indep}ent)", "San Marino", "Sao Tome and Principe", "Saudi Arabia", 
  68          "Scotland", "Senegal", "Serbia and Montenegro", "Seychelles", "Sierra Leone", "Singapore", 
  69          "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa", 
  70          "South Georgia and the South Sandwich Islands", "South Korea", "Spain", "Sri Lanka", 
  71          "St. Helena", "St. Pierre and Miquelon", "Suriname", "Svalbard and Jan Mayen Islands", 
  72          "Swaziland", "Sweden", "Switzerland", "Taiwan", "Tajikistan", "Tanzania", "Thailand", 
  73          "Togo", "Tokelau", "Tonga", "Trinidad", "Trinidad and Tobago", "Tunisia", "Turkey", 
  74          "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Uganda", "Ukraine", 
  75          "United Arab Emirates", "United Kingdom", "United States", 
  76          "United States Minor Outlying Islands", "Uruguay", "Uzbekistan", "Vanuatu", 
  77          "Vatican City State (Holy See)", "Venezuela", "Viet Nam", "Virgin Islands (British)", 
  78          "Virgin Islands (U.S.)", "Wales", "Wallis and Futuna Islands", "Western Sahara", 
  79          "Yemen", "Zambia", "Zimbabwe");
  80  }
  81  
  82  /**
  83   *  @todo Document this class
  84   */
  85  class FormOptionsHelper extends FormHelper {
  86      
  87      /**
  88       *  Generate HTML option tags from a list of choices
  89       *
  90       *  Accepts an array of possible choices and returns a string of
  91       *  option tags.  The value of each array element becomes the
  92       *  visible text of an option, and the key of the element becomes
  93       *  the value returned to the server.  For example:<br />
  94       *  <samp>options_for_select(array('foo','bar'));</samp><br />
  95       *  will return:<br />
  96       *  <samp><option value="0">foo</option>\n</samp><br />
  97       *  <samp><option value="1">bar</option></samp><br />
  98       *
  99       *  The optional second argument specifies the array key of an
 100       *  option to be initially selected.
 101       * 
 102       *  NOTE: Only the option tags are returned, you have to wrap this
 103       *  call in a regular HTML select tag.
 104       *  @param string[]  Choices
 105       *  @param integer   Selected choice
 106       *  @return string
 107       */
 108      function options_for_select($choices, $selected = null) {
 109          $options = array();
 110          if(is_array($choices)) {
 111              foreach($choices as $choice_value => $choice_text) {
 112                  if(!empty($choice_value) || is_numeric($choice_value)) {
 113                      $is_selected = ($choice_value == $selected)
 114                          ? true : false;   
 115                  } else {
 116                      $is_selected = ($choice_text == $selected)
 117                          ? true : false;        
 118                  }
 119                  if($is_selected) {
 120                      $options[] = "<option value=\""
 121                      . htmlspecialchars($choice_value)
 122                      . "\" selected=\"selected\">"
 123                      . htmlspecialchars($choice_text)."</option>";
 124                  } else {
 125                      $options[] = "<option value=\""
 126                      . htmlspecialchars($choice_value)
 127                      . "\">"
 128                      . htmlspecialchars($choice_text)."</option>";
 129                  }                        
 130              }    
 131          }
 132          return implode("\n", $options);
 133      }
 134      
 135      /**
 136       *  Returns a string of option tags that have been compiled by
 137       *  iterating over the +collection+ and assigning the result of a
 138       *  call to the +value_method+ as the option value and the
 139       *  +text_method+ as the option text. If +selected_value+ is
 140       *  specified, the element returning a match on +value_method+ will
 141       *  get the selected option tag. 
 142       *
 143       *  Example (call, result). Imagine a loop iterating over each
 144       *  +person+ in <tt>@project.people</tt> to generate an input tag: 
 145       *   options_from_collection_for_select(@project.people, "id", "name")
 146       *     <option value="#{person.id}">#{person.name}</option>
 147       *
 148       *  NOTE: Only the option tags are returned, you have to wrap this call
 149       *  in a regular HTML select tag. 
 150       *  @todo Document this method
 151       */
 152      function options_from_collection_for_select($collection, $attribute_value,
 153                                                  $attribute_text,
 154                                                  $selected_value = null) {
 155          $options = array();
 156          if(is_array($collection)) {
 157              foreach($collection as $object) {
 158                  if(is_object($object)) {
 159                      $options[$object->send($attribute_value)] =
 160                          $object->send($attribute_text);            
 161                  }
 162              }    
 163          }       
 164          return $this->options_for_select($options, $selected_value);
 165      }
 166      
 167      /**
 168       *  Generate HTML options for world countries
 169       *
 170       *  @param integer  Array key of country initially selected
 171       *  NOTE: Only the option tags are returned, you have to wrap this
 172       *  call in a regular HTML select tag.
 173       *  @todo <b>FIXME:</b> Second argument doesn't work
 174       */
 175      function country_options_for_select($selected = null,
 176                      $priority_countries = array()) {
 177          $country_options = "";
 178          
 179          if(count($priority_countries)) {
 180              $country_options .= $this->options_for_select($priority_countries,
 181                                $selected);
 182              $country_options .= "<option value=\"\">-------------</option>\n";
 183              foreach($priority_countries as $country) { 
 184                  unset($GLOBALS['COUNTRIES'][array_search($country,
 185                               $GLOBALS['COUNTRIES'])]);
 186              }
 187          }
 188          
 189          $country_options .= $this->options_for_select($GLOBALS['COUNTRIES'],
 190                                $selected);
 191   
 192          return $country_options;
 193      }
 194      
 195      /**
 196       *  @todo Document this method
 197       *  @uses add_default_name_and_id()
 198       *  @uses add_options()
 199       *  @uses content_tag()
 200       *  @uses value()
 201       */
 202      function to_select_tag($choices, $options, $html_options) {
 203          $html_options = $this->add_default_name_and_id($html_options);
 204          $value = $this->value();
 205          return $this->error_wrapping(
 206              $this->content_tag(
 207                   "select",
 208                   $this->add_options(
 209                             $this->options_for_select($choices, $value),
 210                             $options),
 211                   $html_options),
 212               $this->object()->errors[$this->attribute_name]);
 213      }
 214      
 215      /**
 216       *  @todo Document this method
 217       *
 218       *  @uses add_default_name_and_id()
 219       *  @uses add_options()
 220       *  @uses content_tag()
 221       *  @uses options_from_collection_for_select()
 222       *  @uses value()
 223       */
 224      function to_collection_select_tag($collection, $attribute_value,
 225                                        $attribute_text, $options,
 226                                        $html_options) {
 227          $html_options = $this->add_default_name_and_id($html_options);
 228          $value = $this->value();
 229          return $this->error_wrapping(
 230              $this->content_tag(
 231                  "select",
 232                  $this->add_options(
 233                      $this->options_from_collection_for_select(
 234                          $collection,
 235                          $attribute_value,
 236                          $attribute_text,
 237                          $value),
 238                      $options),
 239                  $html_options),
 240              $this->object()->errors[$this->attribute_name]);
 241      }
 242      
 243      /**
 244       *  @todo Document this method
 245       *
 246       *  @uses add_default_name_and_id()
 247       *  @uses add_options()
 248       *  @uses content_tag()
 249       *  @uses value
 250       */
 251      function to_country_select_tag($priority_countries,
 252                                     $options, $html_options) {
 253          $html_options = $this->add_default_name_and_id($html_options);
 254          $value = $this->value();
 255          return $this->error_wrapping(
 256              $this->content_tag(
 257                  "select",
 258                  $this->add_options(
 259                          $this->country_options_for_select($value,
 260                                                            $priority_countries),
 261                          $options),
 262                  $html_options),
 263              $this->object()->errors[$this->attribute_name]);
 264      }
 265  
 266      /**
 267       *  @todo Document this method
 268       *
 269       *  @param string
 270       *  @param array
 271       */
 272      private function add_options($option_tags, $options) {
 273          if(array_key_exists("include_blank", $options)
 274             && $options["include_blank"] == true) {
 275              $option_tags = "<option value=\"\"></option>\n" . $option_tags;
 276          } 
 277          if(array_key_exists('prompt', $options)) {
 278              $text = $options['prompt'] ? $options['prompt'] : "Please select";
 279              return ("<option value=\"\">$text</option>\n" . $option_tags);
 280          } else {
 281              return $option_tags;
 282          }        
 283      }
 284  }
 285  
 286  /**
 287   *  Create a new FormOptionsHelper object and call its to_select_tag() method
 288   *
 289   *  Create a select tag and a series of contained option tags for the
 290   *  provided object and method.  The option currently held by the
 291   *  object will be selected, provided that the object is available. 
 292   *  See options_for_select for the required format of the choices parameter.
 293   *
 294   * Example with $post->person_id => 1:
 295   *   $person = new Person;
 296   *   $people = $person->find_all();
 297   *   foreach($people as $person) {
 298   *      $choices[$person->id] = $person->first_name;
 299   *   }
 300   *   select("post", "person_id", $choices, array("include_blank" => true))
 301   *
 302   * could become:
 303   *
 304   *   <select name="post[person_id]">
 305   *     <option></option>
 306   *     <option value="1" selected="selected">David</option>
 307   *     <option value="2">Sam</option>
 308   *     <option value="3">Tobias</option>
 309   *   </select>
 310   *
 311   *  This can be used to provide a functionault set of options in the
 312   *  standard way: before r}ering the create form, a new model instance
 313   *  is assigned the functional options and bound to
 314   *  @model_name. Usually this model is not saved to the
 315   *  database. Instead, a second model object is created when the
 316   *  create request is received.  This allows the user to submit a form
 317   *  page more than once with the expected results of creating multiple
 318   *  records.  In addition, this allows a single partial to be used to
 319   *  generate form inputs for both edit and create forms. 
 320   *  @todo Document this function
 321   */
 322  function select($object_name, $attribute_name, $choices,
 323          $options = array(), $html_options = array()) {
 324      $form = new FormOptionsHelper($object_name, $attribute_name);
 325      return $form->to_select_tag($choices, $options, $html_options);
 326  }
 327  
 328  /**
 329   *  Create a new FormOptionsHelper object and call its to_collection_select_tag() method
 330   *
 331   * Return select and option tags for the given object and method using 
 332   * options_from_collection_for_select to generate the list of option tags.
 333   *
 334   * Example with $post->person_id => 1:
 335   *   $person = new Person;
 336   *   $people = $person->find_all();
 337   *   collection_select("post", "person_id", $people, "id", "first_name", array("include_blank" => true))
 338   *
 339   * could become:
 340   *
 341   *   <select name="post[person_id]">
 342   *     <option></option>
 343   *     <option value="1" selected="selected">David</option>
 344   *     <option value="2">Sam</option>
 345   *     <option value="3">Tobias</option>
 346   *   </select>
 347   *
 348   *  @todo Document this function
 349   *  @uses FormOptionsHelper::to_collection_select_tag()
 350   */
 351  function collection_select($object_name, $attribute_name, $collection,
 352                             $attribute_value, $attribute_text,
 353                             $options = array(), $html_options = array()) {
 354      $form = new FormOptionsHelper($object_name, $attribute_name);
 355      return $form->to_collection_select_tag($collection, $attribute_value,
 356                                             $attribute_text, $options,
 357                                             $html_options);
 358  }
 359  
 360  /**
 361   *  Create a new FormOptionsHelper object and call its to_country_select_tag() method
 362   *
 363   * Return select and option tags for the given object and method, using country_options_for_select to generate the list of option tags.
 364   *  @todo Document this function
 365   *  @uses FormOptionsHelper::country_select()
 366   */
 367  function country_select($object_name, $attribute_name, $priority_countries = null, $options = array(), $html_options = array()) {
 368      $form = new FormOptionsHelper($object_name, $attribute_name);
 369      return $form->to_country_select_tag($priority_countries, $options, $html_options);
 370  }
 371  
 372  /**
 373   *  Create a new FormOptionsHelper object and call its options_for_select() method
 374   *
 375   *  @param string[]  List of choices
 376   *  @param integer   Index of the selected choice
 377   *  @uses FormOptionsHelper::options_for_select()
 378   */
 379  function options_for_select($choices, $selected = null) {
 380      $form = new FormOptionsHelper();
 381      return $form->options_for_select($choices, $selected);    
 382  }
 383  
 384  // -- set Emacs parameters --
 385  // Local variables:
 386  // tab-width: 4
 387  // c-basic-offset: 4
 388  // c-hanging-comment-ender-p: nil
 389  // indent-tabs-mode: nil
 390  // End:
 391  ?>