Select

Syntax:

$form_options_helper->select ($object_name,$column_name,$choices,
    [ $options ],[ $html_options ])

Description:
Creates a select tag and a series of contained option tags for the provided object and method. The option currently held by the object will be selected, provided that the object is available. This can be used to provide a default set of options in the standard way: before rendering the create form, a new model instance is assigned the default options and bound to $this→model_name. Usually this model is not saved to the database. Instead, a second model object is created when the create request is received. This allows the user to submit a form page more than once with the expected results of creating multiple records. In addition, this allows a single partial to be used to generate form inputs for both edit and create forms.

• $choices is defined in the API as the function $form_options_helper→options_for_select. It is this array: ( $container, [ $selected = array()], [ $options = array()]).
  • $container is an array of the values and keys (notice the reverse order) that go into the option tags.

    Array('Dollar'=>'$', 'Kroner'=>'DKK')

    will yield

    <option value="$">Dollar</option><option value="DKK">Kroner</option>

  • $selected specifies which container item will be selected. It is an array, so that more than one value may be selected in the case of a multiple select.
    

Examples of $choices:

• (array('VISA', 'MasterCard'), 'MasterCard');

  yields

<option value="VISA">VISA</option><option selected="selected" value="MasterCard">MasterCard</option>

• (array('Basic'=>'$20','Plus'=>'$40'), '$40');

  yields

<option value="$20">Basic</option><option selected="selected" value="$40">Plus</option>

• (array('VISA','MasterCard','Discover'), array('VISA','Discover'));

  yields

<option selected="selected" value="VISA">VISA</option>
<option value="MasterCard">MasterCard</option>
<option selected="selected" value="Discover">Discover</option>

• $options = array() Two mutually exclusive options are:
  
  • 'include_blank' ⇒ true This causes the first option element to be blank.
  • 'prompt' ⇒ true This causes the first option element to be a prompt string. Set to true will give a generic “Please select”, alternatively you can enter your own text as a value. (Note: the default 'Please select' can be localized. It's in /locales/helpers/form/)
    
• $html_options = array()
  
  

Example:

$form_options_helper->select(
  'post',                                            $object_name 
  'person_id',                                       $column_name
  $Person->collect($Person->find(), 'name', 'id'),   $choices
  array('include_blank'=>true));                     $options
                                                     $html_options have been omitted

Example notes:

• $choices:

$Person is a class referring to the people table. This table belongs_to the $object_name.

• selected:

$post.person_id is the selected option, by default. To select 'identifier' as the the option, the $options clause would be modified to look like this:

array('include_blank'=>true,'selected' => $post.identifier));

If you wish to have no option selected, the $options clause would look like this:

array('include_blank'=>true,'selected' => null));

Example:

$form_options_helper->select('post','category', $Post->categories, array('include_blank'=>true));

Syntax:

$form_tag_helper->select_tag($name,[ $option_tags],[ $options ])

Description:
Creates a dropdown selection box, or if the 'multiple' => true, a multiple choice selection box.
$option_tags is a string containing the option tags for the select box:
$options array:

• 'multiple' ⇒ true - If set to true the selection will allow multiple choices.
• 'include_blank' ⇒ true This causes the first option element to be blank.
• 'prompt' ⇒ true This causes the first option element to be a prompt string. Set to true will give a generic “Please select”, alternatively you can enter your own text as a value. (Note: the default 'Please select' can be localized. It's in /locales/helpers/form/)
  
  

Example:

$form_tag_helper->select_tag('people', '<option>David</option><option>Goliath</option>');

produces

<select id="people" name="people"><option>David</option><option>Goliath</option></select>

Syntax:

$form_options_helper->collection_select($object_name,$column_name,$collection,
    $value_column_name,$text_column_name,[ $selected_value ],[ $options ],[ $html_options ])

Description:
Returns select and option tags for the given object and column_name that have been compiled by iterating over the $collection and assigning the the result of a call to the $value_column_name and the $text_column_name.

• $selected_value If it is specified, it will be matched against the contents of the $value_column_name to determine the selected option tag.
• $collection, $value_column_name, $text_column_name, $selected_value, $options, and $html_options are all arrays. The fact that $selected_value is an array means that more than one value may be selected in the case of a multiple select.
  
• $options = array() Two mutually exclusive options are:
  
  • 'include_blank' ⇒ true Causes the first option element to be blank.
  • 'prompt' ⇒ true This causes the first option element to be a prompt string. Set to true will give a generic “Please select”, alternatively you can enter your own text as a value. (Note: the default 'Please select' can be localized. It's in /locales/helpers/form/)
    
• $html_options = array()
  
  

Syntax:

$form_options_helper->option_groups_from_collection_for_select(
    $collection,$group_method,$group_label_method,$option_key_method,$option_value_method,[ $selected_key ])

Description:
Returns a string of option tags surrounded by <optgroup> tags.
An array of group objects are passed. Each group should return

• an array of options when calling group_method
• its name when calling group_label_method.

Example:
Given objects of the following classes:

class Continent
{ 
    function Continent($p_name, $p_countries) 
    { 
        $this->continent_name = $p_name; 
        $this->countries = $p_countries;
    } 
    function getContinentName() 
    { 
        return $this->continent_name; 
    } 
    function getCountries() 
    { 
        return $this->countries; 
    } 
} 
class Country 
{ 
    function Country($id, $name) 
    { 
        $this->id = $id; 
        $this->name = $name; 
    } 
    function getCountryId()
    { 
        return $this->id; 
    } 
    function getCountryName()
    { 
        return $this->name;
    } 
}

In the template, write

<select name="continents">
<?php $form_options_helper->option_groups_from_collection_for_select(
    $continents, 'getCountries', 'getContinentName', 'getCountryId', 
    'getCountryName', $selected_country->id); ?>
</select>

Depending on the data, the result could be:

<select name="continents">
    <optgroup label="Africa"> 
        <option value="EGP">Egypt</option> 
        <option value="RWD">Rwanda</option>
    </optgroup>
    <optgroup label="Asia"> 
        <option value="ZHN">China</option> 
        <option value="IND">India</option> 
        <option selected="selected" value="JPN">Japan</option>
    </optgroup>
</select>

Syntax:

$form_options_helper->country_select ($object_name,$column_name,
    [ $priority_countries ],[ $options ],[ $html_options ])

Description:
Return select and option tags for the given $object_name and $column_name.

• $priority_countries There are certain countries that the application expects most of the time. $priority_countries will put these at the top of the drop down list. An example shows the format:

array('Finland'=>'FIN','Germany'=>'DEU','United States'=>'USA')

A list of available countries may be created by referencing AkCountries.php

• $options = array() Two mutually exclusive options are:
  
  • 'include_blank' ⇒ true Causes the first option element to be blank.
  • 'prompt' ⇒ true This causes the first option element to be a prompt string. Set to true will give a generic “Please select”, alternatively you can enter your own text as a value. (Note: the default 'Please select' can be localized. It's in /locales/helpers/form/)
    
    

Syntax:

$form_options_helper->time_zone_select ( 
    $object_name,$column_name,[ $priority_zones ],[ $options ],[ $html_options ])

Description:
Return select and option tags for the given $object_name and $column_name.

• $priority_zones = names Supply an array of names from AkTimeZone.php to have them listed at the top of the (long) list.
• $options = array() Two mutually exclusive options are:
  
  • 'include_blank' ⇒ true Causes the first option element to be blank.
  • 'model' ⇒ 'AkTimeZone' Change the model for different information.
  • 'prompt' ⇒ true This causes the first option element to be a prompt string. Set to true will give a generic “Please select”, alternatively you can enter your own text as a value. (Note: the default 'Please select' can be localized. It's in /locales/helpers/form/)
    
• $html_options = array()
  
  

Syntax:

$form_options_helper->time_zone_options_for_select(
    [ $selected ],[ $priority_zones ],[ $model ])

Description:
Returns a string of option tags for pretty much any time zone in the world.

• $selected = name Supply a name from AkTimeZone.php to have it marked as the selected option tag.
• $priority_zones = names Supply an array of names from AkTimeZone.php to have them listed at the top of the (long) list.
• $model = 'AkTimeZone' The model may be changed to get different information. The only requirement is that the $model parameter be an object that responds to #all, and returns an object with a toString() method and the TimeZone name provided be a 'name' attribute.
  

In the template, type

<select>
<?php $form_options_helper->time_zone_options_for_select(
    [ $selected ], [ $priority_zones ], [ $model ]); ?>
</select>

Date/Time select