8000 Merge pull request #64 from sensiolabs/move-components/form · symfony/symfony-docs@47dfbe0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 47dfbe0

Browse files
weaverryanweaverryan
authored
Merge pull request #64 from sensiolabs/move-components/form
Move Form component sub-articles to the Form topic
2 parents d210474 + 18d2dbb commit 47dfbe0

File tree

6 files changed

+96
-55
lines changed

6 files changed

+96
-55
lines changed

‎components/form.rst‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -702,15 +702,6 @@ method to access the list of errors. It returns a
702702
This is useful, for example, if you want to use PHP's ``array_`` function
703703
on the form errors.
704704

705-
Learn More
706-
----------
707-
708-
.. toctree::
709-
:maxdepth: 1
710-
:glob:
711-
712-
form/*
713-
714705
.. _Packagist: https://packagist.org/packages/symfony/form
715706
.. _Twig: http://twig.sensiolabs.org
716707
.. _`Twig Configuration`: http://twig.sensiolabs.org/doc/intro.html

‎form/dynamic_form_modification.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,7 @@ how to customize your form based on three common use-cases:
2525
field.
2626

2727
If you wish to learn more about the basics behind form events, you can
28-
take a look at the :doc:`Form Events </components/form/form_events>`
29-
documentation.
28+
take a look at the :doc:`Form Events </form/events>` documentation.
3029

3130
.. _cookbook-form-events-underlying-data:
3231

‎components/form/form_events.rst‎ renamed to ‎form/events.rst‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ depending on the request values::
2727
};
2828

2929
$form = $formFactory->createBuilder()
30-
// add form fields
30+
// ... add form fields
3131
->addEventListener(FormEvents::PRE_SUBMIT, $listener);
3232

3333
// ...
@@ -310,18 +310,22 @@ Creating and binding an event listener to the form is very easy::
310310
When you have created a form type class, you can use one of its methods as a
311311
callback for better readability::
312312

313-
// ...
313+
// src/AppBundle/Form/SubscriptionType.php
314+
namespace AppBundle\Form;
314315

316+
// ...
315317
class SubscriptionType extends AbstractType
316318
{
317319
public function buildForm(FormBuilderInterface $builder, array $options)
318320
{
319-
$builder->add('username', 'text');
320-
$builder->add('show_email', 'checkbox');
321-
$builder->addEventListener(
322-
FormEvents::PRE_SET_DATA,
323-
array($this, 'onPreSetData')
324-
);
321+
$builder
322+
->add('username', 'text')
323+
->add('show_email', 'checkbox')
324+
->addEventListener(
325+
FormEvents::PRE_SET_DATA,
326+
array($this, 'onPreSetData')
327+
)
328+
;
325329
}
326330

327331
public function onPreSetData(FormEvent $event)
@@ -341,6 +345,9 @@ Event subscribers have different uses:
341345

342346
.. code-block:: php
343347
348+
// src/AppBundle/Form/EventListener/AddEmailFieldListener.php
349+
namespace AppBundle\Form\EventListener;
350+
344351
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
345352
use Symfony\Component\Form\FormEvent;
346353
use Symfony\Component\Form\FormEvents;
@@ -388,8 +395,9 @@ Event subscribers have different uses:
388395
}
389396
}
390397
391-
To register the event subscriber, use the addEventSubscriber() method::
398+
To register the event subscriber, use the ``addEventSubscriber()`` method::
392399

400+
use AppBundle\Form\EventListener\AddEmailFieldListener;
393401
// ...
394402

395403
$form = $formFactory->createBuilder()

‎components/form/type_guesser.rst‎ renamed to ‎form/type_guesser.rst‎

Lines changed: 75 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -24,25 +24,26 @@ Create a PHPDoc Type Guesser
2424
In this section, you are going to build a guesser that reads information about
2525
fields from the PHPDoc of the properties. At first, you need to create a class
2626
which implements :class:`Symfony\\Component\\Form\\FormTypeGuesserInterface`.
27-
This interface requires 4 methods:
28-
29-
* :method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessType` -
30-
tries to guess the type of a field;
31-
* :method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessRequired` -
32-
tries to guess the value of the :ref:`required <reference-form-option-required>`
33-
option;
34-
* :method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessMaxLength` -
35-
tries to guess the value of the :ref:`max_length <reference-form-option-max_length>`
36-
option;
37-
* :method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessPattern` -
38-
tries to guess the value of the :ref:`pattern <reference-form-option-pattern>`
39-
option.
27+
This interface requires four methods:
28+
29+
:method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessType`
30+
Tries to guess the type of a field;
31+
:method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessRequired`
32+
Tries to guess the value of the :ref:`required <reference-form-option-required>`
33+
option;
34+
:method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessMaxLength`
35+
Tries to guess the value of the :ref:`max_length <reference-form-option-max_length>`
36+
option;
37+
:method:`Symfony\\Component\\Form\\FormTypeGuesserInterface::guessPattern`
38+
Tries to guess the value of the :ref:`pattern <reference-form-option-pattern>`
39+
option.
4040

4141
Start by creating the class and these methods. Next, you'll learn how to fill each on.
4242

4343
.. code-block:: php
4444
45-
namespace Acme\Form;
45+
// src/AppBundle/Form/TypeGuesser/PHPDocTypeGuesser.php
46+
namespace AppBundle\Form\TypeGuesser;
4647
4748
use Symfony\Component\Form\FormTypeGuesserInterface;
4849
@@ -72,7 +73,7 @@ When guessing a type, the method returns either an instance of
7273
:class:`Symfony\\Component\\Form\\Guess\\TypeGuess` or nothing, to determine
7374
that the type guesser cannot guess the type.
7475

75-
The ``TypeGuess`` constructor requires 3 options:
76+
The ``TypeGuess`` constructor requires three options:
7677

7778
* The type name (one of the :doc:`form types </reference/forms/types>`);
7879
* Additional options (for instance, when the type is ``entity``, you also
@@ -84,10 +85,10 @@ The ``TypeGuess`` constructor requires 3 options:
8485
``VERY_HIGH_CONFIDENCE``. After all type guessers have been executed, the
8586
type with the highest confidence is used.
8687

87-
With this knowledge, you can easily implement the ``guessType`` method of the
88+
With this knowledge, you can easily implement the ``guessType()`` method of the
8889
``PHPDocTypeGuesser``::
8990

90-
namespace Acme\Form;
91+
namespace AppBundle\Form\TypeGuesser;
9192

9293
use Symfony\Component\Form\Guess\Guess;
9394
use Symfony\Component\Form\Guess\TypeGuess;
@@ -140,6 +141,8 @@ With this knowledge, you can easily implement the ``guessType`` method of the
140141

141142
return $phpdocTags;
142143
}
144+
145+
// ...
143146
}
144147

145148
This type guesser can now guess the field type for a property if it has
@@ -148,8 +151,8 @@ PHPdoc!
148151
Guessing Field Options
149152
~~~~~~~~~~~~~~~~~~~~~~
150153

151-
The other 3 methods (``guessMaxLength``, ``guessRequired`` and
152-
``guessPattern``) return a :class:`Symfony\\Component\\Form\\Guess\\ValueGuess`
154+
The other three methods (``guessMaxLength()``, ``guessRequired()`` and
155+
``guessPattern()``) return a :class:`Symfony\\Component\\Form\\Guess\\ValueGuess`
153156
instance with the value of the option. This constructor has 2 arguments:
154157

155158
* The value of the option;
@@ -161,7 +164,7 @@ set.
161164

162165
.. caution::
163166

164-
You should be very careful using the ``guessPattern`` method. When the
167+
You should be very careful using the ``guessPattern()`` method. When the
165168
type is a float, you cannot use it to determine a min or max value of the
166169
float (e.g. you want a float to be greater than ``5``, ``4.512313`` is not valid
167170
but ``length(4.512314) > length(5)`` is, so the pattern will succeed). In
@@ -170,22 +173,60 @@ set.
170173
Registering a Type Guesser
171174
--------------------------
172175

173-
The last thing you need to do is registering your custom type guesser by using
174-
:method:`Symfony\\Component\\Form\\FormFactoryBuilder::addTypeGuesser` or
175-
:method:`Symfony\\Component\\Form\\FormFactoryBuilder::addTypeGuessers`::
176176

177-
use Symfony\Component\Form\Forms;
178-
use Acme\Form\PHPDocTypeGuesser;
177+
The last thing you need to do is registering your custom type guesser by
178+
creating a service and tagging it as ``form.type_guesser``:
179179

180-
$formFactory = Forms::createFormFactoryBuilder()
181-
// ...
182-
->addTypeGuesser(new PHPDocTypeGuesser())
183-
->getFormFactory();
180+
.. configuration-block::
181+
182+
.. code-block:: yaml
183+
184+
# app/config/services.yml
185+
services:
186+
187+
app.phpdoc_type_guesser:
188+
class: AppBundle\Form\TypeGuesser\PHPDocTypeGuesser
189+
tags:
190+
- { name: form.type_guesser }
191+
192+
.. code-block:: xml
193+
194+
<!-- app/config/services.xml -->
195+
<?xml version="1.0" encoding="UTF-8" ?>
196+
<container xmlns="http://symfony.com/schema/dic/services"
197+
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
198+
xsd:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd"
199+
>
200+
<services>
184201
185-
// ...
202+
<service class="AppBundle\Form\TypeGuesser\PHPDocTypeGuesser">
203+
<tag name="form.type_guesser"/>
204+
</service>
186205
187-
.. note::
206+
</services>
207+
</container>
188208
189-
When you use the Symfony Framework, you need to register your type guesser
190-
and tag it with ``form.type_guesser``. For more information see
191-
:ref:`the tag reference <reference-dic-type_guesser>`.
209+
.. code-block:: php
210+
211+
// app/config/services.php
212+
$container->register('AppBundle\Form\TypeGuesser\PHPDocTypeGuesser')
213+
->addTag('form.type_guesser')
214+
;
215+
216+
217+
.. sidebar:: Registering a Type Guesser in the Component
218+
219+
If you're using the Form component standalone in your PHP project, use
220+
:method:`Symfony\\Component\\Form\\FormFactoryBuilder::addTypeGuesser` or
221+
:method:`Symfony\\Component\\Form\\FormFactoryBuilder::addTypeGuessers` of
222+
the ``FormFactoryBuilder`` to register new type guessers::
223+
224+
use Symfony\Component\Form\Forms;
225+
use Acme\Form\PHPDocTypeGuesser;
226+
227+
$formFactory = Forms::createFormFactoryBuilder()
228+
// ...
229+
->addTypeGuesser(new PHPDocTypeGuesser())
230+
->getFormFactory();
231+
232+
// ...

‎redirection_map‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,8 +254,10 @@
254254
/components/expression_language/index /components/expression_language
255255
/components/filesystem/introduction /components/filesystem
256256
/components/filesystem/index /components/filesystem
257+
/components/form/form_events /form/events
257258
/components/form/introduction /components/form
258259
/components/form/index /components/form
260+
/components/form/type_guesser /form/type_guesser
259261
/components/http_foundation/introduction /components/http_foundation
260262
/components/http_kernel/introduction /components/http_kernel
261263
/components/http_kernel/index /components/http_kernel

‎reference/dic_tags.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -410,7 +410,7 @@ metadata and Doctrine metadata (if you're using Doctrine) or Propel metadata
410410
.. seealso::
411411

412412
For information on how to create your own type guesser, see
413-
:doc:`/components/form/type_guesser`.
413+
:doc:`/form/type_guesser`.
414414

415415
kernel.cache_clearer
416416
--------------------

0 commit comments

Comments
 (0)
0