From 6252c71254424a91074f021526c38875e77674d4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 24 May 2017 16:59:06 +0200 Subject: [PATCH] Change some examples to remove references to gender types --- components/config/definition.rst | 7 +- form/create_custom_field_type.rst | 114 ++++++++++++++-------------- form/create_form_type_extension.rst | 2 +- reference/constraints/Choice.rst | 66 ++++++++-------- reference/forms/types/choice.rst | 16 ++-- reference/forms/types/entity.rst | 4 +- validation.rst | 53 +++++++------ 7 files changed, 133 insertions(+), 129 deletions(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index d82df6ac634..559ed61c0dd 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -141,13 +141,14 @@ values:: $rootNode ->children() - ->enumNode('gender') - ->values(array('male', 'female')) + ->enumNode('delivery') + ->values(array('standard', 'expedited', 'priority')) ->end() ->end() ; -This will restrict the ``gender`` option to be either ``male`` or ``female``. +This will restrict the ``delivery`` options to be either ``standard``, +``expedited`` or ``priority``. Array Nodes ~~~~~~~~~~~ diff --git a/form/create_custom_field_type.rst b/form/create_custom_field_type.rst index fc8c0d905f2..b1c50bf7b4e 100644 --- a/form/create_custom_field_type.rst +++ b/form/create_custom_field_type.rst @@ -7,7 +7,7 @@ How to Create a Custom Form Field Type Symfony comes with a bunch of core field types available for building forms. However there are situations where you may want to create a custom form field type for a specific purpose. This recipe assumes you need a field definition -that holds a person's gender, based on the existing choice field. This section +that holds a shipping option, based on the existing choice field. This section explains how the field is defined, how you can customize its layout and finally, how you can register it for use in your application. @@ -16,24 +16,25 @@ Defining the Field Type In order to create the custom field type, first you have to create the class representing the field. In this situation the class holding the field type -will be called ``GenderType`` and the file will be stored in the default location +will be called ``ShippingType`` and the file will be stored in the default location for form fields, which is ``\Form\Type``. Make sure the field extends :class:`Symfony\\Component\\Form\\AbstractType`:: - // src/AppBundle/Form/Type/GenderType.php + // src/AppBundle/Form/Type/ShippingType.php namespace AppBundle\Form\Type; use Symfony\Component\Form\AbstractType; use Symfony\Component\OptionsResolver\OptionsResolver; - class GenderType extends AbstractType + class ShippingType extends AbstractType { public function configureOptions(OptionsResolver $resolver) { $resolver->setDefaults(array( 'choices' => array( - 'm' => 'Male', - 'f' => 'Female', + 'standard' => 'Standard Shipping', + 'expedited' => 'Expedited Shipping', + 'priority' => 'Priority Shipping', ) )); } @@ -45,7 +46,7 @@ for form fields, which is ``\Form\Type``. Make sure the field extend public function getName() { - return 'app_gender'; + return 'app_shipping'; } } @@ -69,8 +70,8 @@ important: This method is used to set any extra variables you'll need when rendering your field in a template. For example, in `ChoiceType`_, a ``multiple`` variable is set and used in the template to set (or not - set) the ``multiple`` attribute on the ``select`` field. See `Creating a Template for the Field`_ - for more details. + set) the ``multiple`` attribute on the ``select`` field. See + `Creating a Template for the Field`_ for more details. .. versionadded:: 2.7 The ``configureOptions()`` method was introduced in Symfony 2.7. Previously, @@ -93,9 +94,9 @@ The ``getName()`` method returns an identifier which should be unique in your application. This is used in various places, such as when customizing how your form type will be rendered. -The goal of this field was to extend the choice type to enable selection of -a gender. This is achieved by fixing the ``choices`` to a list of possible -genders. +The goal of this field was to extend the choice type to enable selection of the +shipping type. This is achieved by fixing the ``choices`` to a list of available +shipping options. Creating a Template for the Field --------------------------------- @@ -109,14 +110,14 @@ any work as the custom field type will automatically be rendered like a ``choice type. But for the sake of this example, suppose that when your field is "expanded" (i.e. radio buttons or checkboxes, instead of a select field), you want to always render it in a ``ul`` element. In your form theme template (see above -link for details), create a ``gender_widget`` block to handle this: +link for details), create a ``shipping_widget`` block to handle this: .. configuration-block:: .. code-block:: html+twig {# app/Resources/views/form/fields.html.twig #} - {% block gender_widget %} + {% block shipping_widget %} {% spaceless %} {% if expanded %}
    @@ -136,7 +137,7 @@ link for details), create a ``gender_widget`` block to handle this: .. code-block:: html+php - +
      block($form, 'widget_container_attributes') ?>> @@ -154,7 +155,7 @@ link for details), create a ``gender_widget`` block to handle this: .. note:: Make sure the correct widget prefix is used. In this example the name should - be ``gender_widget``, according to the value returned by ``getName()``. + be ``shipping_widget``, according to the value returned by ``getName()``. Further, the main config file should point to the custom form template so that it's used when rendering all forms. @@ -252,18 +253,18 @@ new instance of the type in one of your forms:: use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; - class AuthorType extends AbstractType + class OrderType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { - $builder->add('gender_code', new GenderType(), array( - 'placeholder' => 'Choose a gender', + $builder->add('shipping_code', new ShippingType(), array( + 'placeholder' => 'Choose a delivery option', )); } } -But this only works because the ``GenderType()`` is very simple. What if -the gender codes were stored in configuration or in a database? The next +But this only works because the ``ShippingType()`` is very simple. What if +the shipping codes were stored in configuration or in a database? The next section explains how more complex field types solve this problem. .. versionadded:: 2.6 @@ -278,7 +279,7 @@ Creating your Field Type as a Service So far, this entry has assumed that you have a very simple custom field type. But if you need access to configuration, a database connection, or some other service, then you'll want to register your custom type as a service. For -example, suppose that you're storing the gender parameters in configuration: +example, suppose that you're storing the shipping parameters in configuration: .. configuration-block:: @@ -286,9 +287,10 @@ example, suppose that you're storing the gender parameters in configuration: # app/config/config.yml parameters: - genders: - m: Male - f: Female + shipping_options: + standard: Standard Shipping + expedited: Expedited Shipping + priority: Priority Shipping .. code-block:: xml @@ -300,9 +302,10 @@ example, suppose that you're storing the gender parameters in configuration: http://symfony.com/schema/dic/services/services-1.0.xsd"> - - Male - Female + + Standard Shipping + Expedited Shipping + Priority Shipping @@ -310,11 +313,12 @@ example, suppose that you're storing the gender parameters in configuration: .. code-block:: php // app/config/config.php - $container->setParameter('genders.m', 'Male'); - $container->setParameter('genders.f', 'Female'); + $container->setParameter('shipping_options.standard', 'Standard Shipping'); + $container->setParameter('shipping_options.expedited', 'Expedited Shipping'); + $container->setParameter('shipping_options.priority', 'Priority Shipping'); -To use the parameter, define your custom field type as a service, injecting -the ``genders`` parameter value as the first argument to its to-be-created +To use the parameter, define your custom field type as a service, injecting the +``shipping_options`` parameter value as the first argument to its to-be-created ``__construct()`` function: .. configuration-block:: @@ -323,12 +327,12 @@ the ``genders`` parameter value as the first argument to its to-be-created # src/AppBundle/Resources/config/services.yml services: - app.form.type.gender: - class: AppBundle\Form\Type\GenderType + app.form.type.shipping: + class: AppBundle\Form\Type\ShippingType arguments: - - '%genders%' + - '%shipping_options%' tags: - - { name: form.type, alias: app_gender } + - { name: form.type, alias: app_shipping } .. code-block:: xml @@ -340,9 +344,9 @@ the ``genders`` parameter value as the first argument to its to-be-created http://symfony.com/schema/dic/services/services-1.0.xsd"> - - %genders% - + + %shipping_options% + @@ -350,12 +354,12 @@ the ``genders`` parameter value as the first argument to its to-be-created .. code-block:: php // src/AppBundle/Resources/config/services.php - use AppBundle\Form\Type\GenderType; + use AppBundle\Form\Type\ShippingType; - $container->register('app.form.type.gender', GenderType::class) - ->addArgument('%genders%') + $container->register('app.form.type.shipping', ShippingType::class) + ->addArgument('%shipping_options%') ->addTag('form.type', array( - 'alias' => 'app_gender', + 'alias' => 'app_shipping', )); .. tip:: @@ -366,9 +370,9 @@ the ``genders`` parameter value as the first argument to its to-be-created Be sure that the ``alias`` attribute of the tag corresponds with the value returned by the ``getName()`` method defined earlier. You'll see the importance of this in a moment when you use the custom field type. But first, add a ``__construct`` -method to ``GenderType``, which receives the gender configuration:: +method to ``ShippingType``, which receives the shipping configuration:: - // src/AppBundle/Form/Type/GenderType.php + // src/AppBundle/Form/Type/ShippingType.php namespace AppBundle\Form\Type; use Symfony\Component\OptionsResolver\OptionsResolver; @@ -376,26 +380,26 @@ method to ``GenderType``, which receives the gender configuration:: // ... // ... - class GenderType extends AbstractType + class ShippingType extends AbstractType { - private $genderChoices; + private $shippingOptions; - public function __construct(array $genderChoices) + public function __construct(array $shippingOptions) { - $this->genderChoices = $genderChoices; + $this->shippingOptions = $shippingOptions; } public function configureOptions(OptionsResolver $resolver) { $resolver->setDefaults(array( - 'choices' => $this->genderChoices, + 'choices' => $this->shippingOptions, )); } // ... } -Great! The ``GenderType`` is now fueled by the configuration parameters and +Great! The ``ShippingType`` is now fueled by the configuration parameters and registered as a service. Additionally, because you used the ``form.type`` tag in its configuration, using the field is now much easier:: @@ -406,18 +410,18 @@ configuration, using the field is now much easier:: // ... - class AuthorType extends AbstractType + class OrderType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { - $builder->add('gender_code', 'app_gender', array( - 'placeholder' => 'Choose a gender', + $builder->add('shipping_code', 'app_shipping', array( + 'placeholder' => 'Choose a delivery option', )); } } Notice that instead of instantiating a new instance, you can just refer to -it by the alias used in your service configuration, ``app_gender``. Have fun! +it by the alias used in your service configuration, ``app_shipping``. Have fun! .. _`ChoiceType`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php .. _`FieldType`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Extension/Core/Type/FieldType.php diff --git a/form/create_form_type_extension.rst b/form/create_form_type_extension.rst index c3af5806d1f..9a4977efb43 100644 --- a/form/create_form_type_extension.rst +++ b/form/create_form_type_extension.rst @@ -5,7 +5,7 @@ How to Create a Form Type Extension =================================== :doc:`Custom form field types ` are great when -you need field types with a specific purpose, such as a gender selector, +you need field types with a specific purpose, such as a shipping type selector, or a VAT number input. But sometimes, you don't really need to add new field types - you want diff --git a/reference/constraints/Choice.rst b/reference/constraints/Choice.rst index be0aa3eb650..1c412bdd783 100644 --- a/reference/constraints/Choice.rst +++ b/reference/constraints/Choice.rst @@ -52,9 +52,9 @@ If your valid choice list is simple, you can pass them in directly via the protected $city; /** - * @Assert\Choice(choices = {"male", "female"}, message = "Choose a valid gender.") + * @Assert\Choice(choices = {"fiction", "non-fiction"}, message = "Choose a valid genre.") */ - protected $gender; + protected $genre; } .. code-block:: yaml @@ -64,10 +64,10 @@ If your valid choice list is simple, you can pass them in directly via the properties: city: - Choice: [New York, Berlin, Tokyo] - gender: + genre: - Choice: - choices: [male, female] - message: Choose a valid gender. + choices: [fiction, non-fiction] + message: Choose a valid genre. .. code-block:: xml @@ -85,13 +85,13 @@ If your valid choice list is simple, you can pass them in directly via the Tokyo - + - + @@ -107,7 +107,7 @@ If your valid choice list is simple, you can pass them in directly via the class Author { - protected $gender; + protected $genre; public static function loadValidatorMetadata(ClassMetadata $metadata) { @@ -116,9 +116,9 @@ If your valid choice list is simple, you can pass them in directly via the new Assert\Choice(array('New York', 'Berlin', 'Tokyo')) ); - $metadata->addPropertyConstraint('gender', new Assert\Choice(array( - 'choices' => array('male', 'female'), - 'message' => 'Choose a valid gender.', + $metadata->addPropertyConstraint('genre', new Assert\Choice(array( + 'choices' => array('fiction', 'non-fiction'), + 'message' => 'Choose a valid genre.', ))); } } @@ -138,9 +138,9 @@ form element. class Author { - public static function getGenders() + public static function getGenres() { - return array('male', 'female'); + return array('fiction', 'non-fiction'); } } @@ -159,9 +159,9 @@ constraint. class Author { /** - * @Assert\Choice(callback = "getGenders") + * @Assert\Choice(callback = "getGenres") */ - protected $gender; + protected $genre; } .. code-block:: yaml @@ -169,8 +169,8 @@ constraint. # src/AppBundle/Resources/config/validation.yml AppBundle\Entity\Author: properties: - gender: - - Choice: { callback: getGenders } + genre: + - Choice: { callback: getGenres } .. code-block:: xml @@ -181,9 +181,9 @@ constraint. xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - + - + @@ -199,12 +199,12 @@ constraint. class Author { - protected $gender; + protected $genre; public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('gender', new Assert\Choice(array( - 'callback' => 'getGenders', + $metadata->addPropertyConstraint('genre', new Assert\Choice(array( + 'callback' => 'getGenres', ))); } } @@ -224,9 +224,9 @@ you can pass the class name and the method as an array. class Author { /** - * @Assert\Choice(callback = {"Util", "getGenders"}) + * @Assert\Choice(callback = {"Util", "getGenres"}) */ - protected $gender; + protected $genre; } .. code-block:: yaml @@ -234,8 +234,8 @@ you can pass the class name and the method as an array. # src/AppBundle/Resources/config/validation.yml AppBundle\Entity\Author: properties: - gender: - - Choice: { callback: [Util, getGenders] } + genre: + - Choice: { callback: [Util, getGenres] } .. code-block:: xml @@ -246,11 +246,11 @@ you can pass the class name and the method as an array. xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - + @@ -267,12 +267,12 @@ you can pass the class name and the method as an array. class Author { - protected $gender; + protected $genre; public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('gender', new Assert\Choice(array( - 'callback' => array('Util', 'getGenders'), + $metadata->addPropertyConstraint('genre', new Assert\Choice(array( + 'callback' => array('Util', 'getGenres'), ))); } } diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst index b4721cc541b..98b2fa08894 100644 --- a/reference/forms/types/choice.rst +++ b/reference/forms/types/choice.rst @@ -255,9 +255,9 @@ to the user. * Before 2.7 (and deprecated now):: - $builder->add('gender', 'choice', array( - // Shows "Male" to the user, returns "m" when selected - 'choices' => array('m' => 'Male', 'f' => 'Female'), + $builder->add('genre', 'choice', array( + // Shows "Fiction" to the user, returns "f" when selected + 'choices' => array('f' => 'Fiction', 'n' => 'Non-fiction'), // before 2.7, this option didn't actually exist, but the // behavior was equivalent to setting this to false in 2.7. 'choices_as_values' => false, @@ -265,9 +265,9 @@ to the user. * Since 2.7:: - $builder->add('gender', 'choice', array( - // Shows "Male" to the user, returns "m" when selected - 'choices' => array('Male' => 'm', 'Female' => 'f'), + $builder->add('genre', 'choice', array( + // Shows "Fiction" to the user, returns "f" when selected + 'choices' => array('Fiction' => 'f', 'Non-fiction' => 'n'), 'choices_as_values' => true, )); @@ -276,8 +276,8 @@ type behaves as if it were set to true: * Default for 3.0:: - $builder->add('gender', 'choice', array( - 'choices' => array('Male' => 'm', 'Female' => 'f'), + $builder->add('genre', 'choice', array( + 'choices' => array('Fiction' => 'f', 'Non-fiction' => 'n'), )); .. include:: /reference/forms/types/options/expanded.rst.inc diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index 277438d9120..6964471a9e7 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -156,8 +156,8 @@ more details, see the main :ref:`choice_label ` doc For example, if the translations property is actually an associative array of objects, each with a name property, then you could do this:: - $builder->add('gender', 'entity', array( - 'class' => 'MyBundle:Gender', + $builder->add('genre', 'entity', array( + 'class' => 'MyBundle:Genre', 'choice_label' => 'translations[en].name', )); diff --git a/validation.rst b/validation.rst index 017f2aff3f0..0b8024a41ed 100644 --- a/validation.rst +++ b/validation.rst @@ -323,8 +323,9 @@ Constraint Configuration Some constraints, like :doc:`NotBlank `, are simple whereas others, like the :doc:`Choice ` constraint, have several configuration options available. Suppose that the -``Author`` class has another property called ``gender`` that can be set to either -"male", "female" or "other": +``Author`` class has another property called ``genre`` that defines the +literature genre mostly associated with the author, which can be set to either +"fiction" or "non-fiction": .. configuration-block:: @@ -339,11 +340,11 @@ constraint, have several configuration options available. Suppose that the { /** * @Assert\Choice( - * choices = { "male", "female", "other" }, - * message = "Choose a valid gender." + * choices = { "fiction", "non-fiction" }, + * message = "Choose a valid genre." * ) */ - public $gender; + public $genre; // ... } @@ -353,8 +354,8 @@ constraint, have several configuration options available. Suppose that the # src/AppBundle/Resources/config/validation.yml AppBundle\Entity\Author: properties: - gender: - - Choice: { choices: [male, female, other], message: Choose a valid gender. } + genre: + - Choice: { choices: [fiction, non-fiction], message: Choose a valid genre. } # ... .. code-block:: xml @@ -367,14 +368,13 @@ constraint, have several configuration options available. Suppose that the http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - + - + @@ -392,7 +392,7 @@ constraint, have several configuration options available. Suppose that the class Author { - public $gender; + public $genre; // ... @@ -400,9 +400,9 @@ constraint, have several configuration options available. Suppose that the { // ... - $metadata->addPropertyConstraint('gender', new Assert\Choice(array( - 'choices' => array('male', 'female', 'other'), - 'message' => 'Choose a valid gender.', + $metadata->addPropertyConstraint('genre', new Assert\Choice(array( + 'choices' => array('fiction', 'non-fiction'), + 'message' => 'Choose a valid genre.', ))); } } @@ -426,9 +426,9 @@ options can be specified in this way. class Author { /** - * @Assert\Choice({"male", "female", "other"}) + * @Assert\Choice({"fiction", "non-fiction"}) */ - protected $gender; + protected $genre; // ... } @@ -438,8 +438,8 @@ options can be specified in this way. # src/AppBundle/Resources/config/validation.yml AppBundle\Entity\Author: properties: - gender: - - Choice: [male, female, other] + genre: + - Choice: [fiction, non-fiction] # ... .. code-block:: xml @@ -452,11 +452,10 @@ options can be specified in this way. http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - + - male - female - other + fiction + non-fiction @@ -474,15 +473,15 @@ options can be specified in this way. class Author { - protected $gender; + protected $genre; public static function loadValidatorMetadata(ClassMetadata $metadata) { // ... $metadata->addPropertyConstraint( - 'gender', - new Assert\Choice(array('male', 'female', 'other')) + 'genre', + new Assert\Choice(array('fiction', 'non-fiction')) ); } }