diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst index 07f80d3cf3c..447518d4e3a 100644 --- a/reference/forms/types/choice.rst +++ b/reference/forms/types/choice.rst @@ -15,10 +15,17 @@ option. +-------------+------------------------------------------------------------------------------+ | Options | - `choices`_ | | | - `choice_list`_ | +| | - `choice_loader`_ | +| | - `choice_label`_ | +| | - `choice_name`_ | +| | - `choice_value`_ | +| | - `choice_attr`_ | +| | - `choices_as_values`_ | | | - `placeholder`_ | | | - `expanded`_ | | | - `multiple`_ | | | - `preferred_choices`_ | +| | - `group_by`_ | +-------------+------------------------------------------------------------------------------+ | Overridden | - `compound`_ | | options | - `empty_data`_ | @@ -51,7 +58,8 @@ user sees on the form (e.g. ``Male``). .. code-block:: php $builder->add('gender', 'choice', array( - 'choices' => array('m' => 'Male', 'f' => 'Female'), + 'choices' => array('Male' => 'm', 'Female' => 'f'), + 'choices_as_values' => true, 'required' => false, )); @@ -61,15 +69,33 @@ of checkboxes depending on the ``expanded`` option:: $builder->add('availability', 'choice', array( 'choices' => array( - 'morning' => 'Morning', - 'afternoon' => 'Afternoon', - 'evening' => 'Evening', + 'Morning' => 'morning', + 'Afternoon' => 'afternoon', + 'Evening' => 'evening', + ), + 'choices_as_values' => true, + 'multiple' => true, + )); + +If you rely on your option value attribute (e.g. for JavaScript) you need +to set ``choice_value``, otherwise the option values will be mapped to integer +values:: + + $builder->add('availability', 'choice', array( + 'choices' => array( + 'Morning' => 'morning', + 'Afternoon' => 'afternoon', + 'Evening' => 'evening', ), + 'choices_as_values' => true, + 'choice_value' => function ($choice) { + return $choice; + }, 'multiple' => true, )); -You can also use the ``choice_list`` option, which takes an object that -can specify the choices for your widget. +You can also use the ``choice_loader`` option, which can be used to load +the list only partially in cases where a fully-loaded list is not necessary. .. _forms-reference-choice-tags: @@ -85,19 +111,59 @@ choices This is the most basic way to specify the choices that should be used by this field. The ``choices`` option is an array, where the array key -is the item value and the array value is the item's label:: +is the item's label and the array value is the item's value:: $builder->add('gender', 'choice', array( - 'choices' => array('m' => 'Male', 'f' => 'Female'), + 'choices' => array('Male' => 'm', 'Female' => 'f'), + 'choices_as_values' => true, )); -.. tip:: +.. versionadded:: 2.7 + Symfony 2.7 introduced the option to flip the ``choices`` array to be + able to use values that are not integers or strings (but e.g. floats + or booleans). + +choices_as_values +~~~~~~~~~~~~~~~~~ - When the values to choose from are not integers or strings (but e.g. - floats or booleans), you should use the `choice_list`_ option instead. - With this option you are able to keep the original data format which - is important to ensure that the user input is validated properly and - useless database updates caused by a data type mismatch are avoided. +**type**: ``boolean`` **default**: false + +.. versionadded:: 2.7 + + The ``choices_as_values`` option of ChoiceType was introduced in Symfony + 2.7. + +The ``choices_as_values`` option was introduced to ensure backward compatibility +with the modified handling of the ``choices`` optio. Being set to ``false`` +the choices array will be read as values mapping the keys. Setting the option +to ``true`` will enable the new handling of the choices mapping keys to +values. + +* Before 2.7:: + + $builder->add('gender', 'choice', array( + 'choices' => array('m' => 'Male', 'f' => 'Female'), + 'choices_as_values' => false, + )); + +* Optional since 2.7:: + + $builder->add('gender', 'choice', array( + 'choices' => array('Male' => 'm', 'Female' => 'f'), + 'choices_as_values' => true, + )); + +* Default for 3.0:: + + $builder->add('gender', 'choice', array( + 'choices' => array('Male' => 'm', 'Female' => 'f'), + )); + +.. caution:: + + The ``choices_as_values`` option will be removed in Symfony 3.0, + where the choices will be passed in the values of the ``choices`` + option by default. choice_list ~~~~~~~~~~~ @@ -141,6 +207,19 @@ But don't be confused! If ``Full`` is selected (value ``0`` in HTML), ``1`` will be returned in your form. If ``Almost empty`` is selected (value ``2`` in HTML), ``0.1`` will be returned. +choice_loader +~~~~~~~~~~~~~ + +.. versionadded:: 2.7 + + The ``choice_loader`` option of ChoiceType was introduced in Symfony + 2.7. + +The choice loader can be used to load the list only partially in cases where +a fully-loaded list is not necessary. + +**type**: :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\ChoiceLoaderInterface` + .. include:: /reference/forms/types/options/placeholder.rst.inc .. include:: /reference/forms/types/options/expanded.rst.inc @@ -149,6 +228,16 @@ in HTML), ``0.1`` will be returned. .. include:: /reference/forms/types/options/preferred_choices.rst.inc +.. include:: /reference/forms/types/options/choice_label.rst.inc + +.. include:: /reference/forms/types/options/choice_name.rst.inc + +.. include:: /reference/forms/types/options/choice_value.rst.inc + +.. include:: /reference/forms/types/options/choice_attr.rst.inc + +.. include:: /reference/forms/types/options/group_by.rst.inc + Overridden Options ------------------ diff --git a/reference/forms/types/options/choice_attr.rst.inc b/reference/forms/types/options/choice_attr.rst.inc new file mode 100644 index 00000000000..a5f929ee72b --- /dev/null +++ b/reference/forms/types/options/choice_attr.rst.inc @@ -0,0 +1,24 @@ +choice_attr +~~~~~~~~~~~ + +.. versionadded:: 2.7 + The ``choice_attr`` option was introduced in Symfony 2.7. + +**type**: ``array``, ``callable`` or ``string`` **default**: ``array()`` + +Returns the additional HTML attributes for choices. Can be an array, a callable +(like for ``choice_label``) or a property path. + +If an array, the keys of the ``choices`` array must be used as keys:: + + $builder->add('attending', 'choice', array( + 'choices' => array( + 'Yes' => true, + 'No' => false, + 'Maybe' => null, + ), + 'choices_as_values' => true, + 'choice_attr' => array( + 'Maybe' => array('class' => 'greyed-out'), + ), + )); diff --git a/reference/forms/types/options/choice_label.rst.inc b/reference/forms/types/options/choice_label.rst.inc new file mode 100644 index 00000000000..73970631fdd --- /dev/null +++ b/reference/forms/types/options/choice_label.rst.inc @@ -0,0 +1,39 @@ +choice_label +~~~~~~~~~~~~ + +.. versionadded:: 2.7 + The ``choice_label`` option was introduced in Symfony 2.7. + +**type**: ``callable`` or ``string`` **default**: ``null`` + +Returns the label for each choice. Can be a callable (which receives the +choice as first and the key of the ``choices`` array as second argument) +or a property path. + +If ``null``, the keys of the ``choices`` array are used as labels. + +* Using a callable to set the label:: + + $builder->add('attending', 'choice', array( + 'choices' => array( + 'yes' => true, + 'no' => false, + 'maybe' => null, + ), + 'choices_as_values' => true, + 'choice_label' => function ($choice, $key) { + return 'form.choice.'.$key; + }, + )); + +* Using a property path to set the label:: + + $builder->add('attending', 'choice', array( + 'choices' => array( + Status::getInstance(Status::YES), + Status::getInstance(Status::NO), + Status::getInstance(Status::MAYBE), + ), + 'choices_as_values' => true, + 'choice_label' => 'displayName', + )); diff --git a/reference/forms/types/options/choice_name.rst.inc b/reference/forms/types/options/choice_name.rst.inc new file mode 100644 index 00000000000..6b0c108f61c --- /dev/null +++ b/reference/forms/types/options/choice_name.rst.inc @@ -0,0 +1,18 @@ +choice_name +~~~~~~~~~~~ + +.. versionadded:: 2.7 + The ``choice_name`` option was introduced in Symfony 2.7. + +**type**: ``callable`` or ``string`` **default**: ``null`` + +Returns the form name for each choice. That name is used as name of the +checkbox/radio form for this choice. It is also used as index of the choice +views in the template. Can be a callable (like for ``choice_label``) or +a property path. + +The generated names must be valid form names, i.e. contain alpha-numeric +symbols, underscores, hyphens and colons only. They must start with an +alpha-numeric symbol or an underscore. + +If ``null``, an incrementing integer is used as name. diff --git a/reference/forms/types/options/choice_value.rst.inc b/reference/forms/types/options/choice_value.rst.inc new file mode 100644 index 00000000000..2f4feb94d84 --- /dev/null +++ b/reference/forms/types/options/choice_value.rst.inc @@ -0,0 +1,13 @@ +choice_value +~~~~~~~~~~~~ + +.. versionadded:: 2.7 + The ``choice_value`` option was introduced in Symfony 2.7. + +**type**: ``callable`` or ``string`` **default**: ``null`` + +Returns the string value for each choice. This value is displayed in the +``value`` attributes and submitted in the POST/PUT requests. Can be a +callable (like for ``choice_label``) or a property path. + +If ``null``, an incrementing integer is used as value. diff --git a/reference/forms/types/options/group_by.rst.inc b/reference/forms/types/options/group_by.rst.inc new file mode 100644 index 00000000000..a0c59b5effd --- /dev/null +++ b/reference/forms/types/options/group_by.rst.inc @@ -0,0 +1,29 @@ +group_by +~~~~~~~~ + +.. versionadded:: 2.7 + The ``group_by`` option was introduced in Symfony 2.7. + +**type**: ``array``, ``callable`` or ``string`` **default**: ``null`` + +Returns the grouping used for the choices. Can be an array/Traversable, +a callable (like for ``choice_label``) or a property path. + +The return values of the callable/property path are used as group labels. +If ``null`` is returned, a choice is not grouped. + +If ``null``, the structure of the ``choices`` array is used to construct +the groups:: + + $builder->add('attending', 'choice', array( + 'choices' => array( + 'Decided' => array( + 'Yes' => true, + 'No' => false, + ), + 'Undecided' => array( + 'Maybe' => null, + ), + ), + 'choices_as_values' => true, + )); diff --git a/reference/forms/types/options/preferred_choices.rst.inc b/reference/forms/types/options/preferred_choices.rst.inc index 57cfea43830..05f3c9be757 100644 --- a/reference/forms/types/options/preferred_choices.rst.inc +++ b/reference/forms/types/options/preferred_choices.rst.inc @@ -1,16 +1,52 @@ preferred_choices ~~~~~~~~~~~~~~~~~ -**type**: ``array`` **default**: ``array()`` +**type**: ``array``, ``callable`` or ``string`` **default**: ``array()`` -If this option is specified, then a sub-set of all of the options will be -moved to the top of the select menu. The following would move the "Baz" -option to the top, with a visual separator between it and the rest of the -options:: +If this option is specified as an array, then a sub-set of all of the options +will be moved to the top of the select menu. The following would move the +"Yes" option to the top, with a visual separator between it and the rest +of the options:: - $builder->add('foo_choices', 'choice', array( - 'choices' => array('foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz'), - 'preferred_choices' => array('baz'), + $builder->add('attending', 'choice', array( + 'choices' => array( + 'Yes' => true, + 'No' => false, + 'Maybe' => null, + ), + 'choices_as_values' => true, + 'preferred_choices' => array(true), + )); + +.. versionadded:: 2.7 + Setting a callable or propery path was introduced in Symfony 2.7. + +If this option is specified as a callable, then the the preferred options +are computed by the callback:: + + $builder->add('attending', 'choice', array( + 'choices' => array( + 'Yes' => true, + 'No' => false, + 'Maybe' => null, + ), + 'choices_as_values' => true, + 'preferred_choices' => function ($choice, $key) { + return true === $choice; + }, + )); + +If this option is specified as a property path, then the preferred options +are taken from the objects:: + + $builder->add('attending', 'choice', array( + 'choices' => array( + 'Yes' => Status::getInstance(Status::YES), + 'No' => Status::getInstance(Status::NO), + 'Maybe' => Status::getInstance(Status::MAYBE), + ), + 'choices_as_values' => true, + 'preferred_choices' => 'preferred', )); Note that preferred choices are only meaningful when rendering as a ``select``