merged branch bschussek/issue5383 (PR #6528)

This PR was merged into the master branch.

Discussion
----------

[2.3] [Form] Support buttons in forms

Bug fix: no
Feature addition: yes
Backwards compatibility break: yes
Symfony2 tests pass: yes
Fixes the following tickets: #5383
Todo: -
License of the code: MIT
Documentation PR: symfony/symfony-docs#2489

The general idea of this PR is to be able to add buttons to forms like so:

```php
$builder->add('clickme', 'submit');
```

You can then check in the controller whether the button was clicked:

```php
if ($form->get('clickme')->isClicked()) {
   // do stuff
}
```

Button-specific validation groups are also supported:

```php
$builder->add('clickme', 'submit', array(
    'validation_groups' => 'OnlyClickMe',
));
```

The validation group will then override the one defined in the form if that button is clicked.

This PR also introduces the disabling of form validation by passing the value `false` in the option `validation_groups`:

```php
$builder->add('clickme', 'submit', array(
    'validation_groups' => false,
));
```

The same can be achieved (already before this PR) by passing an empty array:
```php
$builder->add('clickme', 'submit', array(
    'validation_groups' => array(),
));
```

See the linked documentation for more information.

Commits
-------

faf8d7a [Form] Added upgrade information about setting "validation_groups" => false
d504732 [Form] Added leading backslashes to @exceptionMessage doc blocks
c8afa88 [Form] Removed deprecated code scheduled for removal in 2.3
36ca056 [Form] Simplified Twig code
ce29c70 [Form] Fixed incorrect doc comment
0bc7129 [Form] Fixed invalid use of FormException
600007b [Form] The option "validation_groups" can now be set to false to disable validation. This is identical to setting it to an empty array.
277d6df [Form] Fixed concatenation operator CS (see 7c47e34928c39e4797edc841423237a16588395e)
7b07925 [Form] Changed isset() to array_key_exists() to be consistent with ParameterBag
7b438a8 [Form] Made submit buttons able to convey validation groups
cc2118d [Form] Implemented support for buttons

Author: fabpot

Button.php

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Form;
+
+/**
+ * A type that should be converted into a {@link Button} instance.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+interface ButtonTypeInterface extends FormTypeInterface
+{
+}

ButtonBuilder.php

@@ -28,6 +28,8 @@ CHANGELOG
  * added an optional PropertyAccessorInterface parameter to FormType,
    ObjectChoiceList and PropertyPathMapper
  * [BC BREAK] PropertyPathMapper and FormType now have a constructor
+ * [BC BREAK] setting the option "validation_groups" to ``false`` now disables validation
+   instead of assuming group "Default"
 
 2.1.0
 -----

ButtonTypeInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Form;
+
+/**
+ * A clickable form element.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+interface ClickableInterface
+{
+    /**
+     * Returns whether this element was clicked.
+     *
+     * @return Boolean Whether this element was clicked.
+     */
+    public function isClicked();
+}

CHANGELOG.md

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Form\Exception;
+
+/**
+ * Base InvalidArgumentException for the Form component.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+class InvalidArgumentException extends \InvalidArgumentException implements ExceptionInterface
+{
+}

ClickableInterface.php

@@ -50,6 +50,9 @@ protected function loadTypes()
             new Type\TimezoneType(),
             new Type\UrlType(),
             new Type\FileType(),
+            new Type\ButtonType(),
+            new Type\SubmitType(),
+            new Type\ResetType(),
         );
     }
 }

Exception/InvalidArgumentException.php

@@ -0,0 +1,121 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Form\Extension\Core\Type;
+
+use Symfony\Component\Form\AbstractType;
+use Symfony\Component\Form\FormBuilderInterface;
+use Symfony\Component\Form\FormInterface;
+use Symfony\Component\Form\FormView;
+use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+
+/**
+ * Encapsulates common logic of {@link FormType} and {@link ButtonType}.
+ *
+ * This type does not appear in the form's type inheritance chain and as such
+ * cannot be extended (via {@link FormTypeExtension}s) nor themed.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+abstract class BaseType extends AbstractType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder->setDisabled($options['disabled']);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function buildView(FormView $view, FormInterface $form, array $options)
+    {
+        $name = $form->getName();
+        $blockName = $options['block_name'] ?: $form->getName();
+        $translationDomain = $options['translation_domain'];
+
+        if ($view->parent) {
+            if ('' !== ($parentFullName = $view->parent->vars['full_name'])) {
+                $id = sprintf('%s_%s', $view->parent->vars['id'], $name);
+                $fullName = sprintf('%s[%s]', $parentFullName, $name);
+                $uniqueBlockPrefix = sprintf('%s_%s', $view->parent->vars['unique_block_prefix'], $blockName);
+            } else {
+                $id = $name;
+                $fullName = $name;
+                $uniqueBlockPrefix = '_'.$blockName;
+            }
+
+            if (!$translationDomain) {
+                $translationDomain = $view->parent->vars['translation_domain'];
+            }
+        } else {
+            $id = $name;
+            $fullName = $name;
+            $uniqueBlockPrefix = '_'.$blockName;
+
+            // Strip leading underscores and digits. These are allowed in
+            // form names, but not in HTML4 ID attributes.
+            // http://www.w3.org/TR/html401/struct/global.html#adef-id
+            $id = ltrim($id, '_0123456789');
+        }
+
+        $blockPrefixes = array();
+        for ($type = $form->getConfig()->getType(); null !== $type; $type = $type->getParent()) {
+            array_unshift($blockPrefixes, $type->getName());
+        }
+        $blockPrefixes[] = $uniqueBlockPrefix;
+
+        if (!$translationDomain) {
+            $translationDomain = 'messages';
+        }
+
+        $view->vars = array_replace($view->vars, array(
+            'form'                => $view,
+            'id'                  => $id,
+            'name'                => $name,
+            'full_name'           => $fullName,
+            'disabled'            => $form->isDisabled(),
+            'label'               => $options['label'],
+            'multipart'           => false,
+            'attr'                => $options['attr'],
+            'block_prefixes'      => $blockPrefixes,
+            'unique_block_prefix' => $uniqueBlockPrefix,
+            'translation_domain'  => $translationDomain,
+            // Using the block name here speeds up performance in collection
+            // forms, where each entry has the same full block name.
+            // Including the type is important too, because if rows of a
+            // collection form have different types (dynamically), they should
+            // be rendered differently.
+            // https://github.com/symfony/symfony/issues/5038
+            'cache_key'           => $uniqueBlockPrefix.'_'.$form->getConfig()->getType()->getName(),
+        ));
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    {
+        $resolver->setDefaults(array(
+            'block_name'         => null,
+            'disabled'           => false,
+            'label'              => null,
+            'attr'               => array(),
+            'translation_domain' => null,
+        ));
+
+        $resolver->setAllowedTypes(array(
+            'attr'       => 'array',
+        ));
+    }
+}

Extension/Core/CoreExtension.php

@@ -0,0 +1,38 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Form\Extension\Core\Type;
+
+use Symfony\Component\Form\ButtonTypeInterface;
+
+/**
+ * A form button.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+class ButtonType extends BaseType implements ButtonTypeInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getParent()
+    {
+        return null;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getName()
+    {
+        return 'button';
+    }
+}