From 1c9b524c9b05ed181888f70cef7af20eacc75679 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Mon, 1 Aug 2022 21:33:10 +0200 Subject: [PATCH] Better explaining what `getParent` actually does Main reason for changing this is to stop presenting `getParent()` of being the "default" (or normal) way of doing it. * I removed the "PHP extension" note-box, cause the (new) text for `getParent()` makes it clear what this does. * I moved `finishView()` one paragraph up (didn't change anything) * Moved all `getParent`-related stuff into its paragraph, and moved it to the top (since it's the most important question in the beginning) --- form/create_custom_field_type.rst | 48 ++++++++++--------------------- 1 file changed, 15 insertions(+), 33 deletions(-) diff --git a/form/create_custom_field_type.rst b/form/create_custom_field_type.rst index 20861ca13bc..af9e79f7723 100644 --- a/form/create_custom_field_type.rst +++ b/form/create_custom_field_type.rst @@ -55,19 +55,11 @@ By convention they are stored in the ``src/Form/Type/`` directory:: } } -The methods of the ``FormTypeInterface`` are explained in detail later in -this article. Here, ``getParent()`` method defines the base type -(``ChoiceType``) and ``configureOptions()`` overrides some of its options. +``getParent()`` tells Symfony to take ``ChoiceType`` as a starting point, +then ``configureOptions()`` overrides some of its options. (All methods of the +``FormTypeInterface`` are explained in detail later in this article.) The resulting form type is a choice field with predefined choices. -.. note:: - - The PHP class extension mechanism and the Symfony form field extension - mechanism are not the same. The parent type returned in ``getParent()`` is - what Symfony uses to build and manage the field type. Making the PHP class - extend from ``AbstractType`` is only a convenient way of implementing the - required ``FormTypeInterface``. - Now you can add this form type when :doc:`creating Symfony forms `:: // src/Form/Type/OrderType.php @@ -123,15 +115,17 @@ convenient to extend instead from :class:`Symfony\\Component\\Form\\AbstractType // ... } -When a form type doesn't extend from another specific type, there's no need to -implement the ``getParent()`` method (Symfony will make the type extend from the -generic :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType`, -which is the parent of all the other types). - These are the most important methods that a form type class can define: .. _form-type-methods-explanation: +``getParent()`` + When returning a (fully-qualified) class name here, Symfony will call each + method of that type (i.e. ``buildForm()``, ``buildView()``, etc.) and all its + type extensions, before calling the corresponding method of your custom type. + This is probably a good idea if you're just changing some details of an + existing type. To start from scratch, just omit ``getParent()``. + ``buildForm()`` It adds and configures other types into this type. It's the same method used when :ref:`creating Symfony form classes `. @@ -139,28 +133,16 @@ These are the most important methods that a form type class can define: ``buildView()`` It sets any extra variables you'll need when rendering the field in a template. -``configureOptions()`` - It defines the options configurable when using the form type, which are also - the options that can be used in ``buildForm()`` and ``buildView()`` - methods. Options are inherited from parent types and parent type - extensions, but you can create any custom option you need. - ``finishView()`` When creating a form type that consists of many fields, this method allows to modify the "view" of any of those fields. For any other use case, it's recommended to use ``buildView()`` instead. -``getParent()`` - If your custom type is based on another type (i.e. they share some - functionality) add this method to return the fully-qualified class name - of that original type. Do not use PHP inheritance for this. - Symfony will call all the form type methods (``buildForm()``, - ``buildView()``, etc.) of the parent type and it will call all its type - extensions before calling the ones defined in your custom type. - - By default, the ``AbstractType`` class returns the generic - :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType` - type, which is the root parent for all form types in the Form component. +``configureOptions()`` + It defines the options configurable when using the form type, which are also + the options that can be used in ``buildForm()`` and ``buildView()`` + methods. Options are inherited from parent types and parent type + extensions, but you can create any custom option you need. Defining the Form Type ~~~~~~~~~~~~~~~~~~~~~~