From 6c883642848c9aaf2a425774b8ddf13737159248 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 11 Apr 2013 17:32:18 +0200 Subject: [PATCH 1/2] Added documentation for buttons in forms --- book/forms.rst | 128 ++++++++++++++++-- reference/forms/types.rst | 3 + reference/forms/types/button.rst | 34 +++++ reference/forms/types/map.rst.inc | 9 +- reference/forms/types/options/attr.rst.inc | 2 +- .../forms/types/options/button_attr.rst.inc | 15 ++ .../types/options/button_disabled.rst.inc | 9 ++ .../forms/types/options/button_label.rst.inc | 11 ++ .../options/button_translation_domain.rst.inc | 7 + reference/forms/types/reset.rst | 34 +++++ reference/forms/types/submit.rst | 43 ++++++ 11 files changed, 284 insertions(+), 11 deletions(-) create mode 100644 reference/forms/types/button.rst create mode 100644 reference/forms/types/options/button_attr.rst.inc create mode 100644 reference/forms/types/options/button_disabled.rst.inc create mode 100644 reference/forms/types/options/button_label.rst.inc create mode 100644 reference/forms/types/options/button_translation_domain.rst.inc create mode 100644 reference/forms/types/reset.rst create mode 100644 reference/forms/types/submit.rst diff --git a/book/forms.rst b/book/forms.rst index 272eae5e86e..e37423d9d56 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -101,6 +101,7 @@ from inside a controller:: $form = $this->createFormBuilder($task) ->add('task', 'text') ->add('dueDate', 'date') + ->add('save', 'submit') ->getForm(); return $this->render('AcmeTaskBundle:Default:new.html.twig', array( @@ -125,6 +126,11 @@ In this example, you've added two fields to your form - ``task`` and ``dueDate`` corresponding to the ``task`` and ``dueDate`` properties of the ``Task`` class. You've also assigned each a "type" (e.g. ``text``, ``date``), which, among other things, determines which HTML form tag(s) is rendered for that field. +At last, you added a submit button for submitting the form to the server. + +.. versionadded:: 2.3 + Support for submit buttons was added in Symfony 2.3. Before that, you had + to add buttons to the form's HTML manually. Symfony2 comes with many built-in types that will be discussed shortly (see :ref:`book-forms-type-reference`). @@ -147,8 +153,6 @@ helper functions: {# src/Acme/TaskBundle/Resources/views/Default/new.html.twig #}
{{ form_widget(form) }} - -
.. code-block:: html+php @@ -156,8 +160,6 @@ helper functions:
enctype($form) ?> > widget($form) ?> - -
.. image:: /images/book/form-simple.png @@ -194,7 +196,7 @@ it into a format that's suitable for being rendered in an HTML form. Support for "hasser" methods was added in Symfony 2.1. .. index:: - single: Forms; Handling form submission + single: Forms; Handling form submissions Handling Form Submissions ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -215,6 +217,7 @@ controller:: $form = $this->createFormBuilder($task) ->add('task', 'text') ->add('dueDate', 'date') + ->add('save', 'submit') ->getForm(); if ($request->isMethod('POST')) { @@ -265,6 +268,42 @@ possible paths: Redirecting a user after a successful form submission prevents the user from being able to hit "refresh" and re-post the data. +.. index:: + single: Forms; Multiple Submit Buttons + +.. _book-form-submitting-multiple-buttons: + +Submitting Forms with Multiple Buttons +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.3 + Support for buttons in forms was added in Symfony 2.3. + +When your form contains more than one submit button, you will want to check +which of the buttons was clicked to adapt the program flow in your controller. +Let's add a second button with the caption "Save and add" to our form:: + + $form = $this->createFormBuilder($task) + ->add('task', 'text') + ->add('dueDate', 'date') + ->add('save', 'submit') + ->add('saveAndAdd', 'submit') + ->getForm(); + +In your controller, use the button's +:method:`Symfony\\Component\\Form\\ClickableInterface\\isClicked` method for +querying if the "Save and add" button was clicked:: + + if ($form->isValid()) { + // perform some action, such as saving the task to the database + + $nextAction = $form->get('saveAndAdd')->isClicked() + ? 'task_new' + : 'task_success'; + + return $this->redirect($this->generateUrl($nextAction)); + } + .. index:: single: Forms; Validation @@ -408,8 +447,41 @@ method:: In both of these cases, *only* the ``registration`` validation group will be used to validate the underlying object. -Groups based on Submitted Data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + single: Forms; Disabling validation + +Disabling Validation +~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.3 + The ability to set ``validation_groups`` to false is new to version 2.3. + Setting it to an empty array was already supported before. + +Sometimes it is useful to suppress the validation of a form altogether. For +these cases, you can skip the call to :method:`Symfony\\Component\\Form\\FormInterface::isValid` +in your controller. If this is not possible, you can alternatively set the +``validation_groups`` option to ``false`` or an empty array:: + + use Symfony\Component\OptionsResolver\OptionsResolverInterface; + + public function setDefaultOptions(OptionsResolverInterface $resolver) + { + $resolver->setDefaults(array( + 'validation_groups' => false, + )); + } + +Note that when you do that, the form will still run basic integrity checks, +for example whether an uploaded file was too large or whether non-existing +fields were submitted. If you want to suppress validation completely, remove +the :method:`Symfony\\Component\\Form\\FormInterface::isValid` call from your +controller. + +.. index:: + single: Forms; Validation groups based on submitted data + +Groups based on the Submitted Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.1 The ability to specify a callback or Closure in ``validation_groups`` @@ -417,7 +489,7 @@ Groups based on Submitted Data If you need some advanced logic to determine the validation groups (e.g. based on submitted data), you can set the ``validation_groups`` option -to an array callback, or a ``Closure``:: +to an array callback:: use Symfony\Component\OptionsResolver\OptionsResolverInterface; @@ -431,7 +503,7 @@ to an array callback, or a ``Closure``:: This will call the static method ``determineValidationGroups()`` on the ``Client`` class after the form is bound, but before validation is executed. The Form object is passed as an argument to that method (see next example). -You can also define whole logic inline by using a Closure:: +You can also define whole logic inline by using a ``Closure``:: use Symfony\Component\Form\FormInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; @@ -450,6 +522,44 @@ You can also define whole logic inline by using a Closure:: )); } +.. index:: + single: Forms; Validation groups based on clicked button + +Groups based on the Clicked Button +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.3 + Support for buttons in forms was added in Symfony 2.3. + +When your form contains multiple submit buttons, you can change the validation +group depending on which button is used to submit the form. For example, +consider a form in a wizard that lets you advance to the next step or go back +to the previous step. Let's assume also that when returning to the previous +step, the data of the form should be saved, but not validated. + +First, we need to add the two buttons to the form:: + + $form = $this->createFormBuilder($task) + // ... + ->add('nextStep', 'submit') + ->add('previousStep', 'submit') + ->getForm(); + +Then, we configure the button for returning to the previous step to run +specific validation groups. In this example, we want it to suppress validation, +so we set its ``validation_groups`` options to false:: + + $form = $this->createFormBuilder($task) + // ... + ->add('previousStep', 'submit', array( + 'validation_groups' => false, + )) + ->getForm(); + +Now the form will skip your validation constraints. It will still validate +basic integrity constraints, such as checking whether an uploaded file was too +large or whether you tried to submit text in a number field. + .. index:: single: Forms; Built-in field types diff --git a/reference/forms/types.rst b/reference/forms/types.rst index 685c9007a7b..00d20926ada 100644 --- a/reference/forms/types.rst +++ b/reference/forms/types.rst @@ -9,6 +9,7 @@ Form Types Reference :hidden: types/birthday + types/button types/checkbox types/choice types/collection @@ -31,7 +32,9 @@ Form Types Reference types/percent types/radio types/repeated + types/reset types/search + types/submit types/text types/textarea types/time diff --git a/reference/forms/types/button.rst b/reference/forms/types/button.rst new file mode 100644 index 00000000000..ef755e1d4b5 --- /dev/null +++ b/reference/forms/types/button.rst @@ -0,0 +1,34 @@ +.. index:: + single: Forms; Fields; button + +button Field Type +================= + +.. versionadded:: 2.3 + The ``button`` type is new in version 2.3 + +A simple, non-responsive button. + ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Rendered as | ``button`` tag | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Options | - `attr`_ | +| | - `disabled`_ | +| | - `label`_ | +| | - `translation_domain`_ | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Parent type | none | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ButtonType` | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ + +Options +------- + +.. include:: /reference/forms/types/options/button_attr.rst.inc + +.. include:: /reference/forms/types/options/button_disabled.rst.inc + +.. include:: /reference/forms/types/options/button_label.rst.inc + +.. include:: /reference/forms/types/options/button_translation_domain.rst.inc diff --git a/reference/forms/types/map.rst.inc b/reference/forms/types/map.rst.inc index fdf51a6a554..38690a7df04 100644 --- a/reference/forms/types/map.rst.inc +++ b/reference/forms/types/map.rst.inc @@ -49,8 +49,15 @@ Hidden Fields * :doc:`hidden` * :doc:`csrf` +Buttons +~~~~~~~ + +* :doc:`button` +* :doc:`reset` +* :doc:`submit` + Base Fields ~~~~~~~~~~~ * :doc:`field` -* :doc:`form` \ No newline at end of file +* :doc:`form` diff --git a/reference/forms/types/options/attr.rst.inc b/reference/forms/types/options/attr.rst.inc index 21b040843d5..7fcf2603e7c 100644 --- a/reference/forms/types/options/attr.rst.inc +++ b/reference/forms/types/options/attr.rst.inc @@ -3,7 +3,7 @@ attr **type**: array **default**: Empty array -If you want to add extra attributes to HTML field representation +If you want to add extra attributes to the HTML field representation, you can use ``attr`` option. It's an associative array with HTML attribute as a key. This can be useful when you need to set a custom class for some widget:: diff --git a/reference/forms/types/options/button_attr.rst.inc b/reference/forms/types/options/button_attr.rst.inc new file mode 100644 index 00000000000..39a2f6c35f4 --- /dev/null +++ b/reference/forms/types/options/button_attr.rst.inc @@ -0,0 +1,15 @@ +attr +~~~~ + +**type**: array **default**: Empty array + +If you want to add extra attributes to the HTML representation of the button, +you can use ``attr`` option. It's an associative array with HTML attribute +as a key. This can be useful when you need to set a custom class for the button:: + + $builder->add('save', 'button', array( + 'attr' => array('class' => 'save'), + )); + + + diff --git a/reference/forms/types/options/button_disabled.rst.inc b/reference/forms/types/options/button_disabled.rst.inc new file mode 100644 index 00000000000..3fee652ff68 --- /dev/null +++ b/reference/forms/types/options/button_disabled.rst.inc @@ -0,0 +1,9 @@ +disabled +~~~~~~~~ + +**type**: ``boolean`` **default**: ``false`` + +If you don't want a user to be able to click a button, you can set the disabled +option to true. It will not be possible to submit the form with this button, +not even when bypassing the browser and sending an request manually, for +example with cURL. diff --git a/reference/forms/types/options/button_label.rst.inc b/reference/forms/types/options/button_label.rst.inc new file mode 100644 index 00000000000..9926016a0f3 --- /dev/null +++ b/reference/forms/types/options/button_label.rst.inc @@ -0,0 +1,11 @@ +label +~~~~~ + +**type**: ``string`` **default**: The label is "guessed" from the field name + +Sets the label that will be displayed on the button. The label can also be +directly set inside the template: + +.. code-block:: jinja + + {{ form_widget(form.save, { 'label': 'Click me' }) }} diff --git a/reference/forms/types/options/button_translation_domain.rst.inc b/reference/forms/types/options/button_translation_domain.rst.inc new file mode 100644 index 00000000000..56c3453f5c1 --- /dev/null +++ b/reference/forms/types/options/button_translation_domain.rst.inc @@ -0,0 +1,7 @@ +translation_domain +~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``messages`` + +This is the translation domain that will be used for any labels or options +that are rendered for this button. diff --git a/reference/forms/types/reset.rst b/reference/forms/types/reset.rst new file mode 100644 index 00000000000..418122fad24 --- /dev/null +++ b/reference/forms/types/reset.rst @@ -0,0 +1,34 @@ +.. index:: + single: Forms; Fields; reset + +reset Field Type +================ + +.. versionadded:: 2.3 + The ``submit`` type is new in version 2.3 + +A button that resets all fields to their original values. + ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Rendered as | ``input`` ``reset`` tag | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Inherited | - `attr`_ | +| options | - `disabled`_ | +| | - `label`_ | +| | - `translation_domain`_ | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Parent type | :doc:`button` | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ResetType` | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ + +Inherited options +----------------- + +.. include:: /reference/forms/types/options/button_attr.rst.inc + +.. include:: /reference/forms/types/options/button_disabled.rst.inc + +.. include:: /reference/forms/types/options/button_label.rst.inc + +.. include:: /reference/forms/types/options/button_translation_domain.rst.inc diff --git a/reference/forms/types/submit.rst b/reference/forms/types/submit.rst new file mode 100644 index 00000000000..5b2dc8e370a --- /dev/null +++ b/reference/forms/types/submit.rst @@ -0,0 +1,43 @@ +.. index:: + single: Forms; Fields; submit + +submit Field Type +================= + +.. versionadded:: 2.3 + The ``submit`` type is new in version 2.3 + +A submit button. + ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Rendered as | ``input`` ``submit`` tag | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Inherited | - `attr`_ | +| options | - `disabled`_ | +| | - `label`_ | +| | - `translation_domain`_ | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Parent type | :doc:`button` | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\SubmitType` | ++----------------------+------------------------------------------------------------------------------------------------------------------------+ + +Submit buttons feature an additional method +:method:`Symfony\\Component\\Form\\ClickableInterface\\isClicked` that lets you +check whether this button was used to submit the forms. This is especially +useful when :ref:`a form has multiple submit buttons `:: + + if ($form->get('save')->isClicked()) { + // ... + } + +Inherited options +----------------- + +.. include:: /reference/forms/types/options/button_attr.rst.inc + +.. include:: /reference/forms/types/options/button_disabled.rst.inc + +.. include:: /reference/forms/types/options/button_label.rst.inc + +.. include:: /reference/forms/types/options/button_translation_domain.rst.inc From 88b88e5bb47b0f39a634c6efc409902db3359a57 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Sat, 13 Apr 2013 15:33:43 +0200 Subject: [PATCH 2/2] Fixed spelling and grammar errors --- book/forms.rst | 9 +++--- reference/forms/types/button.rst | 26 ++++++++--------- .../types/options/button_disabled.rst.inc | 2 +- .../forms/types/options/button_label.rst.inc | 12 ++++++-- reference/forms/types/reset.rst | 26 ++++++++--------- reference/forms/types/submit.rst | 28 +++++++++---------- 6 files changed, 55 insertions(+), 48 deletions(-) diff --git a/book/forms.rst b/book/forms.rst index e37423d9d56..568c4d52ad5 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -291,11 +291,11 @@ Let's add a second button with the caption "Save and add" to our form:: ->getForm(); In your controller, use the button's -:method:`Symfony\\Component\\Form\\ClickableInterface\\isClicked` method for +:method:`Symfony\\Component\\Form\\ClickableInterface::isClicked` method for querying if the "Save and add" button was clicked:: if ($form->isValid()) { - // perform some action, such as saving the task to the database + // ... perform some action, such as saving the task to the database $nextAction = $form->get('saveAndAdd')->isClicked() ? 'task_new' @@ -454,8 +454,9 @@ Disabling Validation ~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.3 - The ability to set ``validation_groups`` to false is new to version 2.3. - Setting it to an empty array was already supported before. + The ability to set ``validation_groups`` to false was added in Symfony 2.3, + although setting it to an empty array achieved the same result in previous + versions. Sometimes it is useful to suppress the validation of a form altogether. For these cases, you can skip the call to :method:`Symfony\\Component\\Form\\FormInterface::isValid` diff --git a/reference/forms/types/button.rst b/reference/forms/types/button.rst index ef755e1d4b5..6e8cce6ed57 100644 --- a/reference/forms/types/button.rst +++ b/reference/forms/types/button.rst @@ -5,22 +5,22 @@ button Field Type ================= .. versionadded:: 2.3 - The ``button`` type is new in version 2.3 + The ``button`` type was added in Symfony 2.3 A simple, non-responsive button. -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Rendered as | ``button`` tag | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Options | - `attr`_ | -| | - `disabled`_ | -| | - `label`_ | -| | - `translation_domain`_ | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Parent type | none | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ButtonType` | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ ++----------------------+----------------------------------------------------------------------+ +| Rendered as | ``button`` tag | ++----------------------+----------------------------------------------------------------------+ +| Options | - `attr`_ | +| | - `disabled`_ | +| | - `label`_ | +| | - `translation_domain`_ | ++----------------------+----------------------------------------------------------------------+ +| Parent type | none | ++----------------------+----------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ButtonType` | ++----------------------+----------------------------------------------------------------------+ Options ------- diff --git a/reference/forms/types/options/button_disabled.rst.inc b/reference/forms/types/options/button_disabled.rst.inc index 3fee652ff68..b08ebf3f35f 100644 --- a/reference/forms/types/options/button_disabled.rst.inc +++ b/reference/forms/types/options/button_disabled.rst.inc @@ -5,5 +5,5 @@ disabled If you don't want a user to be able to click a button, you can set the disabled option to true. It will not be possible to submit the form with this button, -not even when bypassing the browser and sending an request manually, for +not even when bypassing the browser and sending a request manually, for example with cURL. diff --git a/reference/forms/types/options/button_label.rst.inc b/reference/forms/types/options/button_label.rst.inc index 9926016a0f3..9cafe2fc8e4 100644 --- a/reference/forms/types/options/button_label.rst.inc +++ b/reference/forms/types/options/button_label.rst.inc @@ -5,7 +5,13 @@ label Sets the label that will be displayed on the button. The label can also be directly set inside the template: - -.. code-block:: jinja - {{ form_widget(form.save, { 'label': 'Click me' }) }} +.. configuration-block:: + + .. code-block:: html+jinja + + {{ form_widget(form.save, { 'label': 'Click me' }) }} + + .. code-block:: html+php + + widget($form['save'], array('label' => 'Click me')) ?> diff --git a/reference/forms/types/reset.rst b/reference/forms/types/reset.rst index 418122fad24..004657aaf55 100644 --- a/reference/forms/types/reset.rst +++ b/reference/forms/types/reset.rst @@ -5,22 +5,22 @@ reset Field Type ================ .. versionadded:: 2.3 - The ``submit`` type is new in version 2.3 + The ``reset`` type was added in Symfony 2.3 A button that resets all fields to their original values. -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Rendered as | ``input`` ``reset`` tag | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Inherited | - `attr`_ | -| options | - `disabled`_ | -| | - `label`_ | -| | - `translation_domain`_ | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Parent type | :doc:`button` | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ResetType` | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ ++----------------------+---------------------------------------------------------------------+ +| Rendered as | ``input`` ``reset`` tag | ++----------------------+---------------------------------------------------------------------+ +| Inherited | - `attr`_ | +| options | - `disabled`_ | +| | - `label`_ | +| | - `translation_domain`_ | ++----------------------+---------------------------------------------------------------------+ +| Parent type | :doc:`button` | ++----------------------+---------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ResetType` | ++----------------------+---------------------------------------------------------------------+ Inherited options ----------------- diff --git a/reference/forms/types/submit.rst b/reference/forms/types/submit.rst index 5b2dc8e370a..ce75fa3b116 100644 --- a/reference/forms/types/submit.rst +++ b/reference/forms/types/submit.rst @@ -5,25 +5,25 @@ submit Field Type ================= .. versionadded:: 2.3 - The ``submit`` type is new in version 2.3 + The ``submit`` type was added in Symfony 2.3 A submit button. -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Rendered as | ``input`` ``submit`` tag | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Inherited | - `attr`_ | -| options | - `disabled`_ | -| | - `label`_ | -| | - `translation_domain`_ | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Parent type | :doc:`button` | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\SubmitType` | -+----------------------+------------------------------------------------------------------------------------------------------------------------+ ++----------------------+----------------------------------------------------------------------+ +| Rendered as | ``input`` ``submit`` tag | ++----------------------+----------------------------------------------------------------------+ +| Inherited | - `attr`_ | +| options | - `disabled`_ | +| | - `label`_ | +| | - `translation_domain`_ | ++----------------------+----------------------------------------------------------------------+ +| Parent type | :doc:`button` | ++----------------------+----------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\SubmitType` | ++----------------------+----------------------------------------------------------------------+ Submit buttons feature an additional method -:method:`Symfony\\Component\\Form\\ClickableInterface\\isClicked` that lets you +:method:`Symfony\\Component\\Form\\ClickableInterface::isClicked` that lets you check whether this button was used to submit the forms. This is especially useful when :ref:`a form has multiple submit buttons `::