From b654800370e3f7182be51c772a29760d19993ae2 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 25 Apr 2013 18:49:22 +0200 Subject: [PATCH] Removed notion "bind" from the documentation --- book/forms.rst | 6 +-- book/validation.rst | 4 +- cookbook/form/data_transformers.rst | 4 +- .../{direct_bind.rst => direct_submit.rst} | 48 ++++++++++++------- cookbook/form/dynamic_form_modification.rst | 26 +++++----- cookbook/form/index.rst | 2 +- cookbook/form/unit_testing.rst | 12 ++--- cookbook/form/use_empty_data.rst | 2 +- cookbook/security/acl.rst | 2 +- reference/forms/types/url.rst | 2 +- 10 files changed, 62 insertions(+), 46 deletions(-) rename cookbook/form/{direct_bind.rst => direct_submit.rst} (58%) diff --git a/book/forms.rst b/book/forms.rst index 9f024af892c..6b76eeb5f47 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -226,8 +226,8 @@ controller:: .. versionadded:: 2.3 The :method:`Symfony\Component\Form\FormInterface::handleRequest` method was added in Symfony 2.3. Previously, the ``$request`` was passed to the - ``bind`` method - a strategy which is deprecated and will be removed - in Symfony 3.0. For details on that method, see :doc:`/cookbook/form/direct_bind`. + ``submit`` method - a strategy which is deprecated and will be removed + in Symfony 3.0. For details on that method, see :doc:`/cookbook/form/direct_submit`. This controller follows a common pattern for handling forms, and has three possible paths: @@ -247,7 +247,7 @@ possible paths: .. note:: - You can use the method :method:`Symfony\Component\Form\FormInterface::isBound` + You can use the method :method:`Symfony\Component\Form\FormInterface::isSubmitted` to check whether a form was submitted, regardless of whether or not the submitted data is actually valid. diff --git a/book/validation.rst b/book/validation.rst index 717a3daa969..6f7956ddcce 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -205,8 +205,8 @@ Validation and Forms The ``validator`` service can be used at any time to validate any object. In reality, however, you'll usually work with the ``validator`` indirectly when working with forms. Symfony's form library uses the ``validator`` service -internally to validate the underlying object after values have been submitted -and bound. The constraint violations on the object are converted into ``FieldError`` +internally to validate the underlying object after values have been submitted. +The constraint violations on the object are converted into ``FieldError`` objects that can easily be displayed with your form. The typical form submission workflow looks like the following from inside a controller:: diff --git a/cookbook/form/data_transformers.rst b/cookbook/form/data_transformers.rst index 5c7ed6c3438..c3a8d43dcc4 100644 --- a/cookbook/form/data_transformers.rst +++ b/cookbook/form/data_transformers.rst @@ -157,7 +157,7 @@ when creating your form. Later, you'll learn how you could create a custom Cool, you're done! Your user will be able to enter an issue number into the text field and it will be transformed back into an Issue object. This means -that, after a successful bind, the Form framework will pass a real Issue +that, after a successful submission, the Form framework will pass a real Issue object to ``Task::setIssue()`` instead of the issue number. If the issue isn't found, a form error will be created for that field and @@ -201,7 +201,7 @@ used directly. 3) **View Data** - This is the format that's used to fill in the form fields themselves. It's also the format in which the user will submit the data. When -you call ``Form::bind($data)``, the ``$data`` is in the "view" data format. +you call ``Form::submit($data)``, the ``$data`` is in the "view" data format. The 2 different types of transformers help convert to and from each of these types of data: diff --git a/cookbook/form/direct_bind.rst b/cookbook/form/direct_submit.rst similarity index 58% rename from cookbook/form/direct_bind.rst rename to cookbook/form/direct_submit.rst index ae58fdf47ff..eb0cf0394a5 100644 --- a/cookbook/form/direct_bind.rst +++ b/cookbook/form/direct_submit.rst @@ -1,8 +1,8 @@ .. index:: - single: Form; Form::bind + single: Form; Form::submit() -How to use the bind Function to handle Form Submissions -======================================================= +How to use the submit() Function to handle Form Submissions +=========================================================== In Symfony 2.3, a new :method:`Symfony\Component\Form\FormInterface::handleRequest` method was added, which makes handling form submissions easier than ever:: @@ -33,11 +33,14 @@ method was added, which makes handling form submissions easier than ever:: To see more about this method, read :ref:`book-form-handling-form-submissions`. -Using Form::bind() to handle a request (deprecated) ---------------------------------------------------- +Calling Form::submit() manually +------------------------------- -Prior to this, the :method:`Symfony\Component\Form\FormInterface::bind` method -was used instead:: +In some cases, you want better control over when exactly your form is submitted +and what data is passed to it. Instead of using the +:method:`Symfony\Component\Form\FormInterface::handleRequest` +method, pass the submitted data directly to +:method:`Symfony\Component\Form\FormInterface::submit`:: use Symfony\Component\HttpFoundation\Request; // ... @@ -49,7 +52,7 @@ was used instead:: ->getForm(); if ($request->isMethod('POST')) { - $form->bind($request); + $form->submit($request->request->get($form->getName())); if ($form->isValid()) { // perform some action... @@ -63,17 +66,21 @@ was used instead:: )); } -Passing the :class:`Symfony\\Component\HttpFoundation\\Request` directly to -``bind`` still works, but is deprecated and will be removed in Symfony 3.0. -However, you *can* safely pass array values directly to bind. +.. tip:: + + Forms consisting of nested fields expect an array in + :method:`Symfony\Component\Form\FormInterface::submit`. You can also submit + individual fields by calling :method:`Symfony\Component\Form\FormInterface::submit` + directly on the field:: -Passing an Array directly to Form::bind ---------------------------------------- + $form->get('firstName')->submit('Fabien'); -In some cases, you may want to collect and pass an array of values directly -to a Form, instead of using the ``handleRequest`` method. This is absolutely -valid and not deprecated (passing a :class:`Symfony\\Component\HttpFoundation\\Request` -object to ``Form::bind`` is deprecated, but passing an array of ok):: +Passing a Request to Form::submit() (deprecated) +------------------------------------------------ + +Before Symfony 2.3, the :method:`Symfony\Component\Form\FormInterface::submit` +method accepted a :class:`Symfony\\Component\\HttpFoundation\\Reuqest` object as +a convenient shortcut to the previous example:: use Symfony\Component\HttpFoundation\Request; // ... @@ -85,7 +92,7 @@ object to ``Form::bind`` is deprecated, but passing an array of ok):: ->getForm(); if ($request->isMethod('POST')) { - $form->bind($request->request->get($form->getName())); + $form->submit($request); if ($form->isValid()) { // perform some action... @@ -98,3 +105,8 @@ object to ``Form::bind`` is deprecated, but passing an array of ok):: 'form' => $form->createView(), )); } + +Passing the :class:`Symfony\\Component\HttpFoundation\\Request` directly to +:method:`Symfony\\Component\\Form\\FormInterface::submit`` still works, but is +deprecated and will be removed in Symfony 3.0. You should use the method +:method:`Symfony\Component\Form\FormInterface::handleRequest` instead. diff --git a/cookbook/form/dynamic_form_modification.rst b/cookbook/form/dynamic_form_modification.rst index 2608748c17e..53b6cbe14fa 100644 --- a/cookbook/form/dynamic_form_modification.rst +++ b/cookbook/form/dynamic_form_modification.rst @@ -444,14 +444,18 @@ On a form, we can usually listen to the following events: * ``PRE_SET_DATA`` * ``POST_SET_DATA`` -* ``PRE_BIND`` -* ``BIND`` -* ``POST_BIND`` +* ``PRE_SUBMIT`` +* ``SUBMIT`` +* ``POST_SUBMIT`` -When listening to ``BIND`` and ``POST_BIND``, it's already "too late" to make -changes to the form. Fortunately, ``PRE_BIND`` is perfect for this. There +.. versionadded:: 2.3 + The events ``PRE_SUBMIT``, ``SUBMIT`` and ``POST_SUBMIT`` were added in + Symfony 2.3. Before, they were named ``PRE_BIND``, ``BIND`` and ``POST_BIND``. + +When listening to ``SUBMIT`` and ``POST_SUBMIT``, it's already "too late" to make +changes to the form. Fortunately, ``PRE_SUBMIT`` is perfect for this. There is, however, a big difference in what ``$event->getData()`` returns for each -of these events. Specifically, in ``PRE_BIND``, ``$event->getData()`` returns +of these events. Specifically, in ``PRE_SUBMIT``, ``$event->getData()`` returns the raw data submitted by the user. This can be used to get the ``SportMeetup`` id and retrieve it from the database, @@ -494,7 +498,7 @@ The subscriber would now look like:: public static function getSubscribedEvents() { return array( - FormEvents::PRE_BIND => 'preBind', + FormEvents::PRE_SUBMIT => 'preSubmit', FormEvents::PRE_SET_DATA => 'preSetData', ); } @@ -506,7 +510,7 @@ The subscriber would now look like:: { $meetup = $event->getData()->getMeetup(); - // Before binding the form, the "meetup" will be null + // Before SUBMITing the form, the "meetup" will be null if (null === $meetup) { return; } @@ -517,7 +521,7 @@ The subscriber would now look like:: $this->customizeForm($form, $positions); } - public function preBind(FormEvent $event) + public function preSubmit(FormEvent $event) { $data = $event->getData(); $id = $data['event']; @@ -617,6 +621,6 @@ set for every possible kind of sport that our users are registering for. One piece that may still be missing is the client-side updating of your form after the sport is selected. This should be handled by making an AJAX call -back to your application. In that controller, you can bind your form, but -instead of processing it, simply use the bound form to render the updated +back to your application. In that controller, you can submit your form, but +instead of processing it, simply use the submitted form to render the updated fields. The response from the AJAX call can then be used to update the view. diff --git a/cookbook/form/index.rst b/cookbook/form/index.rst index 83e27589824..f5c05d7c229 100644 --- a/cookbook/form/index.rst +++ b/cookbook/form/index.rst @@ -13,4 +13,4 @@ Form use_virtuals_forms unit_testing use_empty_data - direct_bind + direct_submit diff --git a/cookbook/form/unit_testing.rst b/cookbook/form/unit_testing.rst index 5fb2040133b..499eccd81d1 100644 --- a/cookbook/form/unit_testing.rst +++ b/cookbook/form/unit_testing.rst @@ -40,7 +40,7 @@ The simplest ``TypeTestCase`` implementation looks like the following:: class TestedTypeTest extends TypeTestCase { - public function testBindValidData() + public function testSubmitValidData() { $formData = array( 'test' => 'test', @@ -53,8 +53,8 @@ The simplest ``TypeTestCase`` implementation looks like the following:: $object = new TestObject(); $object->fromArray($formData); - // bind the data to the form directly - $form->bind($formData); + // submit the data to the form directly + $form->submit($formData); $this->assertTrue($form->isSynchronized()); $this->assertEquals($object, $form->getData()); @@ -81,7 +81,7 @@ This test checks that none of your data transformers used by the form failed. The :method:`Symfony\\Component\\Form\\FormInterface::isSynchronized`` method is only set to ``false`` if a data transformer throws an exception:: - $form->bind($formData); + $form->submit($formData); $this->assertTrue($form->isSynchronized()); .. note:: @@ -90,7 +90,7 @@ method is only set to ``false`` if a data transformer throws an exception:: active in the test case and it relies on validation configuration. Instead, unit test your custom constraints directly. -Next, verify the binding and mapping of the form. The test below +Next, verify the submission and mapping of the form. The test below checks if all the fields are correctly specified:: $this->assertEquals($object, $form->getData()); @@ -129,7 +129,7 @@ before creating the parent form:: class TestedTypeTest extends TypeTestCase { - public function testBindValidData() + public function testSubmitValidData() { $this->factory->addType(new TestChildType()); diff --git a/cookbook/form/use_empty_data.rst b/cookbook/form/use_empty_data.rst index 0929f8f21c8..11f79cf846c 100644 --- a/cookbook/form/use_empty_data.rst +++ b/cookbook/form/use_empty_data.rst @@ -5,7 +5,7 @@ How to configure Empty Data for a Form Class ============================================ The ``empty_data`` option allows you to specify an empty data set for your -form class. This empty data set would be used if you bind your form, but +form class. This empty data set would be used if you submit your form, but haven't called ``setData()`` on your form or passed in data when you created you form. For example:: diff --git a/cookbook/security/acl.rst b/cookbook/security/acl.rst index 88d21bfb0f4..ba389ed7e2f 100644 --- a/cookbook/security/acl.rst +++ b/cookbook/security/acl.rst @@ -102,7 +102,7 @@ Creating an ACL, and adding an ACE { $comment = new Comment(); - // ... setup $form, and bind data + // ... setup $form, and submit data if ($form->isValid()) { $entityManager = $this->getDoctrine()->getManager(); diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst index 76501ebdc9e..1d47719fc1f 100644 --- a/reference/forms/types/url.rst +++ b/reference/forms/types/url.rst @@ -36,7 +36,7 @@ default_protocol If a value is submitted that doesn't begin with some protocol (e.g. ``http://``, ``ftp://``, etc), this protocol will be prepended to the string when -the data is bound to the form. +the data is submitted to the form. Inherited Options -----------------