PHPonTrax
[ class tree: PHPonTrax ] [ index: PHPonTrax ] [ all elements ]

Source for file form_options_helper.php

Documentation is available at form_options_helper.php

  1. <?php
  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. */
  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. * Generate HTML option tags from a list of choices
  88. *
  89. * Accepts an array of possible choices and returns a string of
  90. * option tags. The value of each array element becomes the
  91. * visible text of an option, and the key of the element becomes
  92. * the value returned to the server. For example:<br />
  93. * <samp>options_for_select(array('foo','bar'));</samp><br />
  94. * will return:<br />
  95. * <samp><option value="0">foo</option>\n</samp><br />
  96. * <samp><option value="1">bar</option></samp><br />
  97. *
  98. * The optional second argument specifies the array key of an
  99. * option to be initially selected.
  100. *
  101. * NOTE: Only the option tags are returned, you have to wrap this
  102. * call in a regular HTML select tag.
  103. * @param string[] Choices
  104. * @param integer Selected choice
  105. * @return string
  106. */
  107. function options_for_select($choices, $selected = null) {
  108. $options = array();
  109. if(is_array($choices)) {
  110. foreach($choices as $choice_value => $choice_text) {
  111. if(!empty($choice_value)) {
  112. $is_selected = ($choice_value == $selected)
  113. ? true : false;
  114. } else {
  115. $is_selected = ($choice_text == $selected)
  116. ? true : false;
  117. }
  118. if($is_selected) {
  119. $options[] = "<option value=\""
  120. . htmlspecialchars($choice_value)
  121. . "\" selected=\"selected\">"
  122. . htmlspecialchars($choice_text)."</option>";
  123. } else {
  124. $options[] = "<option value=\""
  125. . htmlspecialchars($choice_value)
  126. . "\">"
  127. . htmlspecialchars($choice_text)."</option>";
  128. }
  129. }
  130. }
  131. return implode("\n", $options);
  132. }
  133. /**
  134. * Returns a string of option tags that have been compiled by
  135. * iterating over the +collection+ and assigning the result of a
  136. * call to the +value_method+ as the option value and the
  137. * +text_method+ as the option text. If +selected_value+ is
  138. * specified, the element returning a match on +value_method+ will
  139. * get the selected option tag.
  140. *
  141. * Example (call, result). Imagine a loop iterating over each
  142. * +person+ in <tt>@project.people</tt> to generate an input tag:
  143. * options_from_collection_for_select(@project.people, "id", "name")
  144. * <option value="#{person.id}">#{person.name}</option>
  145. *
  146. * NOTE: Only the option tags are returned, you have to wrap this call
  147. * in a regular HTML select tag.
  148. * @todo Document this method
  149. */
  150. function options_from_collection_for_select($collection, $attribute_value,
  151. $attribute_text,
  152. $selected_value = null) {
  153. $options = array();
  154. if(is_array($collection)) {
  155. foreach($collection as $object) {
  156. if(is_object($object)) {
  157. $options[$object->send($attribute_value)] =
  158. $object->send($attribute_text);
  159. }
  160. }
  161. }
  162. return $this->options_for_select($options, $selected_value);
  163. }
  164. /**
  165. * Generate HTML options for world countries
  166. *
  167. * @param integer Array key of country initially selected
  168. * NOTE: Only the option tags are returned, you have to wrap this
  169. * call in a regular HTML select tag.
  170. * @todo <b>FIXME:</b> Second argument doesn't work
  171. */
  172. function country_options_for_select($selected = null,
  173. $priority_countries = array()) {
  174. $country_options = "";
  175. if(count($priority_countries)) {
  176. $country_options .= $this->options_for_select($priority_countries,
  177. $selected);
  178. $country_options .= "<option value=\"\">-------------</option>\n";
  179. foreach($priority_countries as $country) {
  180. unset($GLOBALS['COUNTRIES'][array_search($country,
  181. $GLOBALS['COUNTRIES'])]);
  182. }
  183. }
  184. $country_options .= $this->options_for_select($GLOBALS['COUNTRIES'],
  185. $selected);
  186. return $country_options;
  187. }
  188. /**
  189. * @todo Document this method
  190. * @uses add_default_name_and_id()
  191. * @uses add_options()
  192. * @uses content_tag()
  193. * @uses value()
  194. */
  195. function to_select_tag($choices, $options, $html_options) {
  196. $html_options = $this->add_default_name_and_id($html_options);
  197. return $this->content_tag(
  198. "select",
  199. $this->add_options(
  200. $this->options_for_select($choices, $this->value()),
  201. $options,
  202. $this->value()),
  203. $html_options);
  204. }
  205. /**
  206. * @todo Document this method
  207. *
  208. * @uses add_default_name_and_id()
  209. * @uses add_options()
  210. * @uses content_tag()
  211. * @uses options_from_collection_for_select()
  212. * @uses value()
  213. */
  214. function to_collection_select_tag($collection, $attribute_value,
  215. $attribute_text, $options,
  216. $html_options) {
  217. $html_options = $this->add_default_name_and_id($html_options);
  218. return $this->content_tag(
  219. "select",
  220. $this->add_options(
  221. $this->options_from_collection_for_select($collection,
  222. $attribute_value,
  223. $attribute_text,
  224. $this->value()),
  225. $options,
  226. $this->value()),
  227. $html_options);
  228. }
  229. /**
  230. * @todo Document this method
  231. *
  232. * @uses add_default_name_and_id()
  233. * @uses add_options()
  234. * @uses content_tag()
  235. * @uses value
  236. */
  237. function to_country_select_tag($priority_countries,
  238. $options, $html_options) {
  239. $html_options = $this->add_default_name_and_id($html_options);
  240. return $this->content_tag(
  241. "select",
  242. $this->add_options(
  243. $this->country_options_for_select($this->value(),
  244. $priority_countries),
  245. $options,
  246. $this->value),
  247. $html_options);
  248. }
  249.  
  250. /**
  251. * @todo Document this method
  252. *
  253. * @param string
  254. * @param string[]
  255. * @param string
  256. * @todo <b>FIXME:</b> Why the third argument? It's overwritten!
  257. * @uses value()
  258. */
  259. private function add_options($option_tags, $options, $value = null) {
  260. if(array_key_exists("include_blank", $options)
  261. && $options["include_blank"] == true) {
  262. $option_tags = "<option value=\"\"></option>\n" . $option_tags;
  263. }
  264. $value = $this->value();
  265. if(empty($value) && array_key_exists('prompt', $options)) {
  266. $text = $options['prompt'] ? $options['prompt'] : "Please select";
  267. return ("<option value=\"\">$text</option>\n" . $option_tags);
  268. } else {
  269. return $option_tags;
  270. }
  271. }
  272. }
  273.  
  274. /**
  275. * Create a new FormOptionsHelper object and call its to_select_tag() method
  276. *
  277. * Create a select tag and a series of contained option tags for the
  278. * provided object and method. The option currently held by the
  279. * object will be selected, provided that the object is available.
  280. * See options_for_select for the required format of the choices parameter.
  281. *
  282. * Example with $post->person_id => 1:
  283. * $person = new Person;
  284. * $people = $person->find_all();
  285. * foreach($people as $person) {
  286. * $choices[$person->id] = $person->first_name;
  287. * }
  288. * select("post", "person_id", $choices, array("include_blank" => true))
  289. *
  290. * could become:
  291. *
  292. * <select name="post[person_id]">
  293. * <option></option>
  294. * <option value="1" selected="selected">David</option>
  295. * <option value="2">Sam</option>
  296. * <option value="3">Tobias</option>
  297. * </select>
  298. *
  299. * This can be used to provide a functionault set of options in the
  300. * standard way: before r}ering the create form, a new model instance
  301. * is assigned the functional options and bound to
  302. * @model_name. Usually this model is not saved to the
  303. * database. Instead, a second model object is created when the
  304. * create request is received. This allows the user to submit a form
  305. * page more than once with the expected results of creating multiple
  306. * records. In addition, this allows a single partial to be used to
  307. * generate form inputs for both edit and create forms.
  308. * @todo Document this function
  309. */
  310. function select($object_name, $attribute_name, $choices,
  311. $options = array(), $html_options = array()) {
  312. $form = new FormOptionsHelper($object_name, $attribute_name);
  313. return $form->to_select_tag($choices, $options, $html_options);
  314. }
  315.  
  316. /**
  317. * Create a new FormOptionsHelper object and call its to_collection_select_tag() method
  318. *
  319. * Return select and option tags for the given object and method using
  320. * options_from_collection_for_select to generate the list of option tags.
  321. *
  322. * Example with $post->person_id => 1:
  323. * $person = new Person;
  324. * $people = $person->find_all();
  325. * collection_select("post", "person_id", $people, "id", "first_name", array("include_blank" => true))
  326. *
  327. * could become:
  328. *
  329. * <select name="post[person_id]">
  330. * <option></option>
  331. * <option value="1" selected="selected">David</option>
  332. * <option value="2">Sam</option>
  333. * <option value="3">Tobias</option>
  334. * </select>
  335. *
  336. * @todo Document this function
  337. * @uses FormOptionsHelper::to_collection_select_tag()
  338. */
  339. function collection_select($object_name, $attribute_name, $collection,
  340. $attribute_value, $attribute_text,
  341. $options = array(), $html_options = array()) {
  342. $form = new FormOptionsHelper($object_name, $attribute_name);
  343. return $form->to_collection_select_tag($collection, $attribute_value,
  344. $attribute_text, $options,
  345. $html_options);
  346. }
  347.  
  348. /**
  349. * Create a new FormOptionsHelper object and call its to_country_select_tag() method
  350. *
  351. * Return select and option tags for the given object and method, using country_options_for_select to generate the list of option tags.
  352. * @todo Document this function
  353. * @uses FormOptionsHelper::country_select()
  354. */
  355. function country_select($object_name, $attribute_name, $priority_countries = null, $options = array(), $html_options = array()) {
  356. $form = new FormOptionsHelper($object_name, $attribute_name);
  357. return $form->to_country_select_tag($priority_countries, $options, $html_options);
  358. }
  359.  
  360. /**
  361. * Create a new FormOptionsHelper object and call its options_for_select() method
  362. *
  363. * @param string[] List of choices
  364. * @param integer Index of the selected choice
  365. * @uses FormOptionsHelper::options_for_select()
  366. */
  367. function options_for_select($choices, $selected = null) {
  368. $form = new FormOptionsHelper();
  369. return $form->options_for_select($choices, $selected);
  370. }
  371.  
  372. // -- set Emacs parameters --
  373. // Local variables:
  374. // tab-width: 4
  375. // c-basic-offset: 4
  376. // c-hanging-comment-ender-p: nil
  377. // indent-tabs-mode: nil
  378. // End:
  379. ?>

Documentation generated on Thu, 04 May 2006 19:47:42 -0600 by phpDocumentor 1.3.0RC4