Skip to content

Commit

Permalink
[Form] Adding PHPDoc to many Field objects and making other small cha…
Browse files Browse the repository at this point in the history 
…nges:

 * Added empty_value option on CountryField, LanguageField, LocaleField, TimezoneField
 * Added missing date_pattern to DateTimeField
 * Made the currency option on MoneyField required.
  • Loading branch information
@weaverryan @fabpot
weaverryan authored and fabpot committed Jan 25, 2011
1 parent b38519b commit d341e8b
Show file tree
Hide file tree
Showing 22 changed files with 369 additions and 58 deletions.
5 changes: 4 additions & 1 deletion src/Symfony/Component/Form/CheckboxField.php
View file
Expand Up @@ -19,7 +19,10 @@
class CheckboxField extends ToggleField
{
/**
* {@inheritDoc}
* Available options:
*
* * value: The value of the input checkbox. If the checkbox is checked,
* this value will be posted as the value of the field.
*/
protected function configure()
{
Expand Down
12 changes: 6 additions & 6 deletions src/Symfony/Component/Form/ChoiceField.php
View file
Expand Up @@ -18,17 +18,17 @@
*
* Available options:
*
* * choices: An array of key-value pairs that will represent the choices.
* * choices: An array of key-value pairs that will represent the choices
* * preferred_choices: An array of choices (by key) that should be displayed
* above all other options in the field.
* above all other options in the field
*
* The multiple and expanded options control exactly which HTML element
* that should be used to render this field:
*
* * expanded = false, multiple = false a drop-down select element;
* * expanded = false, multiple = true a multiple select element;
* * expanded = true, multiple = false a series of input radio elements;
* * expanded = true, multiple = true a series of input checkboxes.
* * expanded = false, multiple = false A drop-down select element
* * expanded = false, multiple = true A multiple select element
* * expanded = true, multiple = false A series of input radio elements
* * expanded = true, multiple = true A series of input checkboxes
*
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
Expand Down
18 changes: 17 additions & 1 deletion src/Symfony/Component/Form/CollectionField.php
View file
Expand Up @@ -15,6 +15,13 @@
use Symfony\Component\Form\Exception\UnexpectedTypeException;

/**
* A field group that repeats the given field multiple times over a collection
* specified by the property path if the field.
*
* Example usage:
*
* $form->add(new CollectionField(new TextField('emails')));
*
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
class CollectionField extends FieldGroup
Expand All @@ -32,7 +39,7 @@ class CollectionField extends FieldGroup
protected $removedFields = array();

/**
* Repeats the given field twice to verify the user's input
* Repeats the given field multiple times based in the internal collection.
*
* @param FieldInterface $innerField
*/
Expand All @@ -43,6 +50,15 @@ public function __construct(FieldInterface $innerField, array $options = array()
parent::__construct($innerField->getKey(), $options);
}

/**
* Available options:
*
* * modifiable: If true, elements in the collection can be added
* and removed by the presence of absence of the
* corresponding field groups. Field groups could be
* added or removed via Javascript and reflected in
* the underlying collection. Default: false.
*/
protected function configure()
{
$this->addOption('modifiable', false);
Expand Down
23 changes: 18 additions & 5 deletions src/Symfony/Component/Form/CountryField.php
View file
Expand Up @@ -14,18 +14,31 @@
use Symfony\Component\Locale\Locale;

/**
* A field for selecting from a list of countries
* A field for selecting from a list of countries.
*
* In addition to the ChoiceField options, this field has the following
* options:
*
* * empty_value: If set to a non-false value, an "empty" option will
* be added to the top of the countries choices. A
* common value might be "Choose a country". Default: false.
*
* @see Symfony\Component\Form\ChoiceField
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
class CountryField extends ChoiceField
{
/**
* @inheritDoc
*/
protected function configure()
{
$this->addOption('choices', Locale::getDisplayCountries($this->locale));
$this->addOption('empty_value', false);

$choices = Locale::getDisplayCountries($this->locale);

if (false !== $this->getOption('empty_value')) {
$choices = array('' => $this->getOption('empty_value')) + $choices;
}

$this->addOption('choices', $choices);

parent::configure();
}
Expand Down
52 changes: 29 additions & 23 deletions src/Symfony/Component/Form/DateField.php
View file
Expand Up @@ -18,6 +18,30 @@
use Symfony\Component\Form\ValueTransformer\DateTimeToLocalizedStringTransformer;
use Symfony\Component\Form\ValueTransformer\DateTimeToArrayTransformer;

/**
* Represents a date field.
*
* Available options:
*
* * widget: How to render the field ("input" or "choice"). Default: "choice".
* * type: The type of the date stored on the object. Default: "datetime":
* * datetime: A DateTime object;
* * string: A raw string (e.g. 2011-05-01, Y-m-d);
* * timestamp: A unix timestamp (e.g. 1304208000);
* * raw: A year, month, day array.
* * pattern: The pattern for the select boxes when "widget" is "choice".
* You can use the placeholders "{{ year }}", "{{ month }}" and "{{ day }}".
* Default: locale dependent.
*
* * years: An array of years for the year select tag.
* * months: An array of months for the month select tag.
* * days: An array of days for the day select tag.
*
* * format: The date format type to use for displaying the data. Default: medium.
* * data_timezone: The timezone of the data. Default: UTC.
* * user_timezone: The timezone of the user entering a new value. Default: UTC.
*
*/
class DateField extends HybridField
{
const FULL = 'full';
Expand Down Expand Up @@ -65,37 +89,19 @@ class DateField extends HybridField
*/
protected $formatter;

/**
* Configures the text field.
*
* Available options:
*
* * widget: How to render the field ("input" or "select"). Default: "input"
* * years: An array of years for the year select tag (optional)
* * months: An array of months for the month select tag (optional)
* * days: An array of days for the day select tag (optional)
* * format: See DateValueTransformer. Default: medium
* * type: The type of the date ("date", "datetime" or "timestamp"). Default: "date"
* * data_timezone: The timezone of the data
* * user_timezone: The timezone of the user entering a new value
* * pattern: The pattern for the select boxes when "widget" is "select".
* You can use the placeholders "{{ year }}", "{{ month }}" and "{{ day }}".
* Default: locale dependent
*
* @param array $options Options for this field
* @throws \InvalidArgumentException Thrown if you want to show a timestamp with the select widget.
*/
protected function configure()
{
$this->addOption('widget', self::CHOICE, self::$widgets);
$this->addOption('type', self::DATETIME, self::$types);
$this->addOption('pattern');

$this->addOption('years', range(date('Y') - 5, date('Y') + 5));
$this->addOption('months', range(1, 12));
$this->addOption('days', range(1, 31));

$this->addOption('format', self::MEDIUM, self::$formats);
$this->addOption('type', self::DATETIME, self::$types);
$this->addOption('data_timezone', 'UTC');
$this->addOption('user_timezone', 'UTC');
$this->addOption('widget', self::CHOICE, self::$widgets);
$this->addOption('pattern');

$this->formatter = new \IntlDateFormatter(
$this->locale,
Expand Down
43 changes: 34 additions & 9 deletions src/Symfony/Component/Form/DateTimeField.php
View file
Expand Up @@ -18,7 +18,31 @@
use Symfony\Component\Form\ValueTransformer\ValueTransformerChain;

/**
* A field for editing a date and a time simultaneously
* A field for editing a date and a time simultaneously.
*
* Available options:
*
* * date_widget: How to render the date field ("input" or "choice"). Default: "choice".
* * time_widget: How to render the time field ("input" or "choice"). Default: "choice".
* * type: The type of the date stored on the object. Default: "datetime":
* * datetime: A DateTime object;
* * string: A raw string (e.g. 2011-05-01 12:30:00, Y-m-d H:i:s);
* * timestamp: A unix timestamp (e.g. 1304208000).
* * date_pattern: The pattern for the select boxes when date "widget" is "choice".
* You can use the placeholders "{{ year }}", "{{ month }}" and "{{ day }}".
* Default: locale dependent.
* * with_seconds Whether or not to create a field for seconds. Default: false.
*
* * years: An array of years for the year select tag.
* * months: An array of months for the month select tag.
* * days: An array of days for the day select tag.
* * hours: An array of hours for the hour select tag.
* * minutes: An array of minutes for the minute select tag.
* * seconds: An array of seconds for the second select tag.
*
* * date_format: The date format type to use for displaying the date. Default: medium.
* * data_timezone: The timezone of the data. Default: UTC.
* * user_timezone: The timezone of the user entering a new value. Default: UTC.
*
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
Expand Down Expand Up @@ -51,24 +75,24 @@ class DateTimeField extends FieldGroup
TimeField::INPUT,
);

/**
* {@inheritDoc}
*/
public function configure()
protected function configure()
{
$this->addOption('date_widget', DateField::CHOICE, self::$dateWidgets);
$this->addOption('time_widget', TimeField::CHOICE, self::$timeWidgets);
$this->addOption('type', self::DATETIME, self::$types);
$this->addOption('date_pattern');
$this->addOption('with_seconds', false);

$this->addOption('years', range(date('Y') - 5, date('Y') + 5));
$this->addOption('months', range(1, 12));
$this->addOption('days', range(1, 31));
$this->addOption('hours', range(0, 23));
$this->addOption('minutes', range(0, 59));
$this->addOption('seconds', range(0, 59));

$this->addOption('data_timezone', 'UTC');
$this->addOption('user_timezone', 'UTC');
$this->addOption('date_format', DateField::MEDIUM, self::$dateFormats);
$this->addOption('date_widget', DateField::CHOICE, self::$dateWidgets);
$this->addOption('time_widget', TimeField::CHOICE, self::$timeWidgets);
$this->addOption('type', self::DATETIME, self::$types);
$this->addOption('with_seconds', false);

$this->add(new DateField('date', array(
'type' => DateField::RAW,
Expand All @@ -79,6 +103,7 @@ public function configure()
'years' => $this->getOption('years'),
'months' => $this->getOption('months'),
'days' => $this->getOption('days'),
'pattern' => $this->getOption('date_pattern'),
)));
$this->add(new TimeField('time', array(
'type' => TimeField::RAW,
Expand Down
7 changes: 7 additions & 0 deletions src/Symfony/Component/Form/IntegerField.php
View file
Expand Up @@ -24,6 +24,13 @@
/**
* A localized field for entering integers.
*
* The rounding-mode option defaults to rounding down. The available values are:
* * NumberToLocalizedStringTransformer::ROUND_DOWN
* * NumberToLocalizedStringTransformer::ROUND_UP
* * NumberToLocalizedStringTransformer::ROUND_FLOOR
* * NumberToLocalizedStringTransformer::ROUND_CEILING
*
* @see Symfony\Component\Form\NumberField
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
class IntegerField extends NumberField
Expand Down
20 changes: 18 additions & 2 deletions src/Symfony/Component/Form/LanguageField.php
View file
Expand Up @@ -14,8 +14,16 @@
use Symfony\Component\Locale\Locale;

/**
* A field for selecting from a list of languages
* A field for selecting from a list of languages.
*
* In addition to the ChoiceField options, this field has the following
* options:
*
* * empty_value: If set to a non-false value, an "empty" option will
* be added to the top of the languages choices. A
* common value might be "Choose a language". Default: false.
*
* @see Symfony\Component\Form\ChoiceField
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
class LanguageField extends ChoiceField
Expand All @@ -25,7 +33,15 @@ class LanguageField extends ChoiceField
*/
protected function configure()
{
$this->addOption('choices', Locale::getDisplayLanguages($this->locale));
$this->addOption('empty_value', false);

$choices = Locale::getDisplayLanguages($this->locale);

if (false !== $this->getOption('empty_value')) {
$choices = array('' => $this->getOption('empty_value')) + $choices;
}

$this->addOption('choices', $choices);

parent::configure();
}
Expand Down
20 changes: 18 additions & 2 deletions src/Symfony/Component/Form/LocaleField.php
View file
Expand Up @@ -14,8 +14,16 @@
use Symfony\Component\Locale\Locale;

/**
* A field for selecting from a list of locales
* A field for selecting from a list of locales.
*
* In addition to the ChoiceField options, this field has the following
* options:
*
* * empty_value: If set to a non-false value, an "empty" option will
* be added to the top of the locale choices. A
* common value might be "Choose a locale". Default: false.
*
* @see Symfony\Component\Form\ChoiceField
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
class LocaleField extends ChoiceField
Expand All @@ -25,7 +33,15 @@ class LocaleField extends ChoiceField
*/
protected function configure()
{
$this->addOption('choices', Locale::getDisplayLocales($this->locale));
$this->addOption('empty_value', false);

$choices = Locale::getDisplayLocales($this->locale);

if (false !== $this->getOption('empty_value')) {
$choices = array('' => $this->getOption('empty_value')) + $choices;
}

$this->addOption('choices', $choices);

parent::configure();
}
Expand Down
15 changes: 13 additions & 2 deletions src/Symfony/Component/Form/MoneyField.php
View file
Expand Up @@ -13,8 +13,19 @@
use Symfony\Component\Form\ValueTransformer\MoneyToLocalizedStringTransformer;

/**
* A localized field for entering money values
* A localized field for entering money values.
*
* This field will output the money with the correct comma, period or spacing
* (e.g. 10,000) as well as the correct currency symbol in the correct location
* (i.e. before or after the field).
*
* Available options:
*
* * currency: The currency to display the money with. This is the 3-letter
* ISO 4217 currency code.
* * divisor: A number to divide the money by before displaying. Default 1.
*
* @see Symfony\Component\Form\NumberField
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
class MoneyField extends NumberField
Expand All @@ -34,9 +45,9 @@ class MoneyField extends NumberField
*/
protected function configure()
{
$this->addRequiredOption('currency');
$this->addOption('precision', 2);
$this->addOption('divisor', 1);
$this->addOption('currency');

parent::configure();

Expand Down
15 changes: 15 additions & 0 deletions src/Symfony/Component/Form/NumberField.php
View file
Expand Up @@ -16,6 +16,21 @@
/**
* A localized field for entering numbers.
*
* Available options:
*
* * precision: The number of digits to allow when rounding. Default
* is locale-specific.
* * grouping:
* * rounding-mode: The method to use to round to get to the needed level
* of precision. Options include:
* * NumberToLocalizedStringTransformer::ROUND_FLOOR
* * NumberToLocalizedStringTransformer::ROUND_DOWN
* * NumberToLocalizedStringTransformer::ROUND_HALFDOWN
* * NumberToLocalizedStringTransformer::ROUND_HALFUP (default)
* * NumberToLocalizedStringTransformer::ROUND_UP
* * NumberToLocalizedStringTransformer::ROUND_CEILING
*
* @see \NumberFormatter
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
*/
class NumberField extends Field
Expand Down

0 comments on commit d341e8b

Please sign in to comment.