Changed to simple more real-life example and processed feedback concerning theming and configuration

endroid · weaverryan · commit 1eee777415b4 · 2012-01-07T10:57:47.000-06:00
diff --git a/cookbook/form/create_custom_field_type.rst b/cookbook/form/create_custom_field_type.rst
@@ -7,69 +7,87 @@ 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 we want to create a custom form field
 type for a specific purpose. In this recipe we assume we need a field definition
-that holds a person's full name, consisting of two inputs: the first name
-and the last name. Of course we can achieve this by using two separate fields,
-but let's assume we want to have a single field definition holding this
-information. This section explains how the field is defined, how we can customize
-its layout and finally, how we can register it to use it in our application.
+that holds a person's gender, based on the existing choice field. This section
+explains how the field is defined, how we can customize its layout and finally,
+how we can register it to use it in our application.
 
 Defining the Field Type
 --------------------------
 
 In order to create the custom field type, first we have to create the class
 representing the field. In our situation the class holding the field type
-will be called FullnameType and the file will be stored in the default location
+will be called GenderType and the file will be stored in the default location
 for form fields, which is <BundleName>\Form\Type. Make sure the field extends
 AbstractType.
 
 .. code-block:: php
 
-    # src/Acme/DemoBundle/Form/Type/FullnameType.php
+    # src/Acme/DemoBundle/Form/Type/GenderType.php
 
     namespace Acme\DemoBundle\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilder;
 
-    class FullnameType extends AbstractType
+    class GenderType extends AbstractType
     {
         /**
          * {@inheritdoc}
          */
-        public function buildForm(FormBuilder $builder, array $options)
+        public function getDefaultOptions(array $options)
         {
-            $builder
-                ->add('firstName', 'text', array(
-                    'attr' => array(
-                        'class' => 'firstName'
-                    )
-                ))
-                ->add('lastName', 'text', array(
-                    'attr' => array(
-                        'class' => 'lastName'
-                    )
-                ))
-            ;
+            return array(
+                'choice_list' => new GenderChoiceList(),
+            );
+        }
+
+        /**
+         * {@inheritdoc}
+         */
+        public function getParent(array $options)
+        {
+            return 'choice';
         }
 
         /**
          * {@inheritdoc}
          */
         public function getName()
         {
-            return 'fullname';
+            return 'gender';
         }
 
     }
 
-Here we can see from the contents of the buildForm function that the field
-itself is composed of two fields holding the first name and the last name.
-This will lead to two separate inputs within your field.
-
-The getName method returns an identifier for the type which is used
+Here the return value of the getParent function indicates that the choice
+field is extended. The getName method returns an identifier which is used
 to prevent conflicts with other types. For shared bundles, a good practice
 is to start the type name with the bundle alias.
 
+The goal of our field was to extend the choice type to enable selection of
+a gender. This is achieved by fixing the choice_list to a list of possible
+genders. As the choice field uses a ChoiceList for building its list, we
+create one that provides this information.
+
+.. code-block:: php
+
+    # src/Acme/DemoBundle/Form/ChoiceList/GenderChoiceList.php
+
+    namespace Acme\DemoBundle\Form\ChoiceList;
+
+    use Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface;
+
+    class GenderChoiceList implements ChoiceListInterface
+    {
+      public function getChoices()
+      {
+        return array(
+              'm' => 'male',
+              'f' => 'female',
+        );
+      }
+    }
+
 Creating a Template for the Field
 ---------------------------------
 
@@ -83,42 +101,26 @@ form_div_layout.html.twig (if it does not exist yet) and add our new field.
 
     # src/Acme/DemoBundle/Resources/Form/fields.html.twig
 
-    {% extends 'form_div_layout.html.twig' %}
-
-    {% block fullname_widget %}
+    {% block gender_widget %}
         <div {{ block('widget_container_attributes') }}>
-            {{ form_errors(form.firstName) }}
-            {{ form_errors(form.lastName) }}
-            {{ form_widget(form.firstName) }} {{ form_widget(form.lastName) }}
+            {{ form_errors(form) }}
+            {{ form_widget(form) }}
         </div>
     {% endblock %}
 
 Make sure the correct widget prefix is used. In this example the name should
-be fullname_widget, according to the value returned by getName. Further,
-the configuration should point to the custom fields template. Otherwise
+be gender_widget, according to the value returned by getName. Further,
+the main config file should point to the custom fields template. Otherwise
 the default form template will be used.
 
-.. configuration-block::
-
-    .. code-block:: yaml
+.. code-block:: yaml
 
-        # src/Acme/DemoBundle/Resources/config/resources.yml
-
-        twig:
-            form:
-                resources:
-                    - 'AcmeDemoBundle:Form:fields.html.twig'
-
-    .. code-block:: xml
-
-        # src/Acme/DemoBundle/Resources/config/resources.xml
+    # app/config/config.yml
 
-        <twig:config ...>
-                <twig:form>
-                    <resource>AcmeDemoBundle:Form:fields.html.twig</resource>
-                </twig:form>
-                <!-- ... -->
-        </twig:config>
+    twig:
+        form:
+            resources:
+                - 'AcmeDemoBundle:Form:fields.html.twig'
 
 Registering the Field Type
 --------------------------
@@ -132,17 +134,17 @@ able to use it in our forms. This is achieved by adding it as a new service.
 
         # src/Acme/DemoBundle/Resources/config/resources.yml
 
-        form.type.fullname:
+        form.type.gender:
             class: Acme\DemoBundle\Form\Type\FullnameType
             tags:
-              - { name: form.type, alias: fullname }
+              - { name: form.type, alias: gender }
 
     .. code-block:: xml
 
         # src/Acme/DemoBundle/Resources/config/resources.xml
 
-        <service id="form.type.fullname" class="Acme\DemoBundle\Form\Type\FullnameType">
-            <tag name="form.type" alias="fullname" />
+        <service id="form.type.gender" class="Acme\DemoBundle\Form\Type\GenderType">
+            <tag name="form.type" alias="gender" />
         </service>
 
 Make sure that the alias tag corresponds with the value returned by the getName
