Chapter 10 - Forms
==================
>**Caution**
>This chapter describes the way forms were implemented in symfony 1.0. For
compatibility reasons and because the admin generator feature still uses
this system, this information is also valuable for symfony 1.1. However, if
you start a new project with symfony 1.1, you should also read the "symfony
Forms in Action" book for more information on the new forms framework.
When writing templates, much of a developer's time is devoted to forms. Despite this, forms are generally poorly designed. Since much attention is required to deal with default values, formatting, validation, repopulation, and form handling in general, some developers tend to skim over some important details in the process. Accordingly, symfony devotes special attention to this topic. This chapter describes the tools that automate many of these requirements while speeding up forms development:
* The form helpers provide a faster way to write form inputs in templates, especially for complex elements such as dates, drop-down lists, and rich text.
* When a form is devoted to editing the properties of an object, the templating can be further accelerated by using object form helpers.
* The YAML validation files facilitate form validation and repopulation.
* Validators package the code required to validate input. Symfony bundles validators for the most common needs, and it is very easy to add custom validators.
Form Helpers
------------
In templates, HTML tags of form elements are very often mixed with PHP code. Form helpers in symfony aim to simplify this task and to avoid opening `` tags.
### Main Form Tag
As explained in the previous chapter, you must use the `form_tag()` helper to create a form, since it transforms the action given as a parameter into a routed URL. The second argument can support additional options--for instance, to change the default `method`, change the default `enctype`, or specify other attributes. Listing 10-1 shows examples.
Listing 10-1 - The `form_tag()` Helper
[php]
=> ` tag, even if it doesn't look good in your source code.
### Standard Form Elements
With form helpers, each element in a form is given an id attribute deduced from its name attribute by default. This is not the only useful convention. See Listing 10-2 for a full list of standard form helpers and their options.
Listing 10-2 - Standard Form Helpers Syntax
[php]
// Text field (input)
=>
// All form helpers accept an additional options parameter
// It allows you to add custom attributes to the generated tag
=>
// Long text field (text area)
=>
// Check box
=>
// Radio button
=>
// Dropdown list (select)
Visa
')
?>
=>
// List of options for a select tag
=>
// Dropdown helper combined with a list of options
=>
// To specify option names, use an associative array
'Steve',
'Bob' => 'Bob',
'Albert' => 'Albert',
'Ian' => 'Ian',
'Buck' => 'Buck'
), 'Ian')) ?>
=>
// Dropdown list with multiple selection (selected values can be an array)
'Visa', 'Eurocard' => 'Eurocard', 'Mastercard' => 'Mastercard'),
array('Visa', 'Mastercard'),
), array('multiple' => true))) ?>
=>
// Drop-down list with multiple selection (selected values can be an array)
'Visa', 'Eurocard' => 'Eurocard', 'Mastercard' => 'Mastercard'),
array('Visa', 'Mastercard')
), 'multiple=multiple') ?>
=>
// Upload file field
=>
// Password field
=>
// Hidden field
=>
// Submit button (as text)
=>
// Submit button (as image)
=>
The `submit_image_tag()` helper uses the same syntax and has the same advantages as the `image_tag()`.
>**NOTE**
>For radio buttons, the `id` attribute is not set by default to the value of the `name` attribute, but to a combination of the name and the value. That's because you need to have several radio button tags with the same name to obtain the automated "deselecting the previous one when selecting another" feature, and the `id=name` convention would imply having several HTML tags with the same `id` attribute in your page, which is strictly forbidden.
-
>**SIDEBAR**
>Handling form submission
>
>How do you retrieve the data submitted by users through forms? It is available in the request parameters, so the action only needs to call `$request->getParameter($elementName)` to get the value.
>
>A good practice is to use the same action to display and handle the form. According to the request method (GET or POST), either the form template is called or the form is handled and the request is redirected to another action.
>
> [php]
> // In mymodule/actions/actions.class.php
> public function executeEditAuthor($request)
> {
> if (!$this->getRequest()->isMethod('post'))
> {
> // Display the form
> return sfView::SUCCESS;
> }
> else
> {
> // Handle the form submission
> $name = $request->getParameter('name');
> ...
> $this->redirect('mymodule/anotheraction');
> }
> }
>
>For this to work, the form target must be the same action as the one displaying it.
>
> [php]
> // In mymodule/templates/editAuthorSuccess.php
>
>
> ...
Symfony offers specialized form helpers to do asynchronous requests in the background. The next chapter, which focuses on Ajax, provides more details.
### Date Input Widgets
Forms are often used to retrieve dates. Dates in the wrong format are the main reason for form-submission failures. The `input_date_tag()` helper can assist the user in entering a date with an interactive JavaScript calendar, if you set the `rich` option to `true`, as shown in Figure 10-1.
Figure 10-1 - Rich date input tag
If the `rich` option is omitted, the helper echoes three `