Appendix A - Widgets

Introduction

The symfony form framework comes bundled with a lot of useful widgets. These widgets cover the common needs of most projects. This chapter describes the default form widgets bundled with symfony. We have also included some of the form widgets from the sfFormExtraPlugin, sfPropelPlugin, and sfDoctrinePlugin plugins, as these plugins are supported by the core team and contain some very useful widgets.

Before diving into each widget details, let's see what widgets have in common.

The sfWidget Base Class

All symfony widgets inherit from the sfWidget base class, which provides some default features available to all widgets.

By default, all widgets are rendered as XHTML. You can switch to HTML by calling the setXhtml() method:

sfWidget::setXhtml(false);

The widget system also automatically takes care of escaping HTML attributes and sensible content. To be effective, it needs to know the charset used by your project. By default the charset is UTF-8, but it can be configured by calling the setCharset() method:

sfWidget::setCharset('ISO-8859-1');

If a widget depends on some JavaScript files and/or stylesheets, you can override the getJavaScripts() and getStylesheets() methods respectively:

class Widget extends sfWidget
{
  public function getStylesheets()
  {
    // the array keys are files and values are the media names
    // separated by a colon (,)
    return array(
      '/path/to/file.css' => 'all',
      '/another/file.css' => 'screen,print',
    );
  }
 
  public function getJavaScripts()
  {
    return array('/path/to/file.js', '/another/file.js');
  }
}

The sfWidgetForm Base Class

In this section, we will only talk about form widgets. All of them inherit from the sfWidgetForm base class, which extends the sfWidget class to provide some extra default features.

When creating a widget, you can optionally pass options and HTML attributes as arguments:

$w = new sfWidgetFormInput(
  array('default' => 'Fabien'),
  array('class' => 'foo')
);

Options and HTML attributes can also be set by using the setOptions() and setAttributes() methods:

$w = new sfWidgetFormInput();
$w->setOptions(array('default' => 'Fabien'));
$w->setAttributes(array('class' => 'foo'));

The setOption() and setAttribute() methods allows to set an individual option or HTML attribute:

$w = new sfWidgetFormInput();
$w->setOption('default', 'Fabien');
$w->setAttribute('class', 'foo');

A widget can be rendered by calling the render() method:

$w->render('name', 'value', array('class' => 'foo'));

The render() method takes the following arguments:

• The name of the widget
• The value of the widget
• Some optional HTML attributes (these are merged with the default ones defined at construction time)

The above widget renders as follows:

<input class="foo" type="text" name="bar" id="bar" value="value"/>

The default options defined by sfWidgetForm are the following:

The sfWidgetForm class also provides accessor methods for all the options:

• is_hidden: isHidden(), setHidden()
• needs_multipart: needsMultipartForm()
• default: getValue(), setValue()
• label: getLabel(), setLabel()
• id_format: getIdFormat(), setIdFormat()

Widget Schema

A form widget schema is a wrapper widget for one or several other widgets.

In the next sections, the widgets have been regrouped into categories.

Widgets

• sfWidgetFormChoice
• sfWidgetFormDate
• sfWidgetFormDateRange
• sfWidgetFormDateTime
• sfWidgetFormDoctrineChoice
• sfWidgetFormFilterInput
• sfWidgetFormFilterDate
• sfWidgetFormI18nDate
• sfWidgetFormI18nDateTime
• sfWidgetFormI18nSelectCountry
• sfWidgetFormI18nSelectLanguage
• sfWidgetFormI18nSelectCurrency
• sfWidgetFormI18nTime
• sfWidgetFormInput
• sfWidgetFormInputCheckbox
• sfWidgetFormInputFile
• sfWidgetFormInputFileEditable
• sfWidgetFormInputHidden
• sfWidgetFormInputPassword
• sfWidgetFormJQueryAutocompleter
• sfWidgetFormJQueryDate
• sfWidgetFormPropelChoice
• sfWidgetFormReCaptcha
• sfWidgetFormSchema
• sfWidgetFormSchemaDecorator
• sfWidgetFormSelect
• sfWidgetFormSelectDoubleList
• sfWidgetFormSelectMany
• sfWidgetFormSelectCheckbox
• sfWidgetFormSelectRadio
• sfWidgetFormTextarea
• sfWidgetFormTextareaTinyMCE
• sfWidgetFormTime

Input Widgets

sfWidgetFormInput

The input tag is probably the simplest form tag you will ever use and is represented by the sfWidgetFormInput class.

$w = new sfWidgetFormInput();
echo $w->render('foo');
 
# <input type="text" name="foo" id="foo" />

sfWidgetFormInputCheckbox

The sfWidgetFormInputCheckbox is an input widget with a type of checkbox.

$w = new sfWidgetFormInputCheckbox();
echo $w->render('foo');
 
# <input type="checkbox" name="foo" id="foo" />

sfWidgetFormInputHidden

The sfWidgetFormInputHidden is an input widget with a type of hidden. The is_hidden option is also set to true.

$w = new sfWidgetFormInputHidden();
echo $w->render('foo');
 
# <input type="hidden" name="foo" id="foo" />

sfWidgetFormInputPassword

The sfWidgetFormInputPassword is an input widget with a type of password.

$w = new sfWidgetFormInputPassword();
echo $w->render('foo');
 
# <input type="password" name="foo" id="foo" />

sfWidgetFormInputFile

The sfWidgetFormInputFile is an input widget with a type of file. The needs_multipart option is automatically set to true.

$w = new sfWidgetFormInputFile();
echo $w->render('foo');
 
# <input type="file" name="foo" id="foo" />

sfWidgetFormInputFileEditable

The sfWidgetFormInputFileEditable is an input file widget, extending the sfWidgetFormInputFile widget to add the possibility to display or remove a previously uploaded file.

sfWidgetFormTextarea

The sfWidgetFormTextarea widget automatically set default values for the rows and cols HTML attributes as they are mandatory.

$w = new sfWidgetFormTextarea();
echo $w->render('foo');
 
# <textarea rows="4" cols="30" name="foo" id="foo"></textarea>

sfWidgetFormTextareaTinyMCE

If you want to render a WYSIWYG editor widget, you can use sfWidgetFormTextareaTinyMCE:

$w = new sfWidgetFormTextareaTinyMCE(
  array(),
  array('class' => 'foo')
);

As the Tiny MCE JavaScript files are not bundled with the plugin, you must install it and include it by yourself.

Choice Widgets

Choice Representations

When you want the user to make a choice amongst a list of possibilities, HTML offers several way of representing the choice:

• A select tag:

  

• A select tag with a multiple attribute:

  

• A list of input tags with a type of radio:

  

• A list of input tags with a type of checkbox:

  

But ultimately, they all allow the user to make a single or a multiple choice within a finite number of possibilities.

The sfWidgetFormChoice widget standardizes all these possibilities within one widget. The widget is able to render a choice as any of the four HTML representations we have seen above. It also lets you define your own representation as you will see later on.

sfWidgetFormChoice is a special widget in the sense that it delegates the rendering to another widget. The rendering is controlled by two options: expanded and multiple:

And here is the HTML representation for each possibility:

$w = new sfWidgetFormChoice(array(
  'choices' => array('Fabien Potencier', 'Fabian Lange'),
));

$w = new sfWidgetFormChoice(array(
  'multiple' => true,
  'choices'  => array('PHP', 'symfony', 'Doctrine', 'Propel', 'model'),
));

$w = new sfWidgetFormChoice(array(
  'expanded' => true,
  'choices'  => array('published', 'draft', 'deleted'),
));

$w = new sfWidgetFormChoice(array(
  'expanded' => true,
  'multiple' => true,
  'choices'  => array('A week of symfony', 'Call the expert', 'Community'),
));

Choices Grouping

The sfWidgetFormChoice widget has built-in support for groups of choices by passing an array of arrays for the choices options:

$choices = array(
  'Europe'  => array('France' => 'France', 'Spain' => 'Spain', 'Italy' => 'Italy'),
  'America' => array('USA' => 'USA', 'Canada' => 'Canada', 'Brazil' => 'Brazil'),
);
 
$w = new sfWidgetFormChoice(array('choices' => $choices));

The expanded and multiple options also work as expected:

$w = new sfWidgetFormChoice(array(
  'choices'  => $choices,
  'expanded' => true,
));

The layout used by the renderer widget can also be customized:

$w = new sfWidgetFormChoice(array(
  'choices'  => $choices,
  'expanded' => true,
  'renderer_options' => array('template' => '<strong>%group%</strong> %options%'),
));

Here is some more example of option combinations:

$w = new sfWidgetFormChoice(array(
  'choices'  => $choices,
  'multiple' => true,
));

$w = new sfWidgetFormChoice(array(
  'choices'  => $choices,
  'multiple' => true,
  'expanded' => true,
  'renderer_options' => array('template' => '<strong>%group%</strong> %options%'),
));

Supported Options

Here is a list of all supported options for the widget:

The sfWidgetFormSelectCheckbox and sfWidgetFormSelectRadio widgets support the following options:

Double List Representation

When the user can select multiple options, it is sometimes better to show the list of selected options in another box.

The sfWidgetFormSelectDoubleList widget can be used to render a choice widget as a double list:

$w = new sfWidgetFormChoice(array(
  'choices'        => array('PHP', 'symfony', 'Doctrine', 'Propel', 'model'),
  'renderer_class' => 'sfWidgetFormSelectDoubleList',
));

$files = $w->getJavascripts();

Autocomplete

When you want the user to make a selection amongst a lot of elements, listing them all in a select box becomes impractical. The sfWidgetFormJQueryAutocompleter solves this problem by converting a simple input tag to an autocomplete select box.

$w = new sfWidgetFormChoice(array(
  'choices'          => array(),
  'renderer_class'   => 'sfWidgetFormJQueryAutocompleter',
  'renderer_options' => array('url' => '/autocomplete_script'),
));

The url option is the URL the widget will call to populate the choices based on the user input. The URL receives two parameters:

• q: The string entered by the user
• limit: The maximum number of items to return

The script must return a valid JSON representation of the choice array (use the PHP built-in json_encode() function to convert an array to JSON).

If the choices are related to a Propel model, the sfWidgetFormPropelJQueryAutocompleter widget is optimized for foreign key lookup:

$w = new sfWidgetFormChoice(array(
  'renderer_class'   => 'sfWidgetFormPropelJQueryAutocompleter',
  'renderer_options' => array(
    'model' => 'Article',
    'url'   => '/autocomplete_script',
  ),
));

Choice bound to a Propel Model

If the choices are bound to a Propel model (usually when you want to allow the user to change a foreign key), you can use the sfWidgetFormPropelChoice widget:

$w = new sfWidgetFormPropelChoice(array(
  'model'     => 'Article',
  'add_empty' => false,
));

The choices are automatically retrieved by the widget according to the model class you pass. The widget is highly configurable via a set of dedicated options:

Choice bound to a Doctrine Model

If the choices are bound to a Doctrine model (usually when you want to allow the user to change a foreign key), you can use the sfWidgetFormDoctrineChoice widget:

$w = new sfWidgetFormDoctrineChoice(array(
  'model'     => 'Article',
  'add_empty' => false,
));

The choices are automatically retrieved by the widget according to the model class you pass. The widget is highly configurable via a set of dedicated options:

Date Widgets

Date widgets can be used to ease date entering by proposing several select boxes for a date, a time, or a date time. All symfony date widgets are represented by several HTML tags. They can also be customized according to the user culture.

sfWidgetFormDate

The sfWidgetFormDate represents a date widget:

The values submitted by the user are stored in an array of the name of the widget:

$w = new sfWidgetFormDate();
$w->render('date');
 
# submitted values will be in a `date` array:
# array(
#   'date' => array(
#     'day'   => 15,
#     'month' => 10,
#     'year'  => 2005,
#   ),
# );

The behavior of the widget can be customized with a lot of options:

Using the format option allows the customization of the default tags arrangement (the %year%, %month%, and %day% placeholder are replaced by the corresponding select tag when the render() method is called):

$w = new sfWidgetFormDate(
  array('format' => '%year% - %month% - %day%')
);

By default, the year select tag is populated with the 10 years around the current year. This can be changed by using the years option:

$years = range(2009, 2020);
$w = new sfWidgetFormDate(
  array('years' => array_combine($years, $years))
);

The years, months, and days options take an array where the keys are the values of the option tags and the values are the strings displayed to the user.

sfWidgetFormTime

The sfWidgetFormTime represents a time widget:

The values submitted by the user are stored in an array of the name of the widget:

$w = new sfWidgetFormTime();
$w->render('time');
 
# submitted values will be in a `time` array:
# array(
#   'time' => array(
#     'hour'    => 12,
#     'minute'  => 13,
#     'second'  => 14,
#   ),
# );

The behavior of the widget can be customized with a lot of options:

By default, the widget does not allow for the selection of seconds. This can be changed by setting the with_seconds option to true:

$w = new sfWidgetFormTime(array('with_seconds' => true));

Using the format and format_without_seconds options allows the customization of the default tags arrangement (the %hour%, %minute%, and %second% placeholder are replaced by the corresponding select tag when the render() method is called):

$w = new sfWidgetFormTime(array(
  'with_seconds' => true,
  'format'       => '%hour% : %minute% : %second%',
));

If you don't want to propose every minute or second, you can provide your own values for each of the three tags:

$seconds = array(0, 15, 30, 45);
$w = new sfWidgetFormTime(array(
  'with_seconds' => true,
  'seconds'      => array_combine($seconds, $seconds),
));

The hours, minutes, and seconds options take an array where the keys are the values of the option tags and the values are the strings displayed to the user.

sfWidgetFormDateTime

The sfWidgetFormDateTime widget is a widget that renders two sub-widgets: a sfWidgetFormDate widget and a sfWidgetFormTime one:

$w = new sfWidgetFormDateTime();

sfWidgetFormI18nDate

The sfWidgetFormI18nDate extends the standard sfWidgetFormDate widget. But whereas the standard widget displays months as numbers, the i18n one displays them as strings, localized according to a culture:

$w = new sfWidgetFormI18nDate(array('culture' => 'fr'));

The month string formatting can be tweaked with the month_format option. It accepts three values: name (the default), short_name, or number.

$w = new sfWidgetFormI18nDate(array(
  'culture'      => 'fr',
  'month_format' => 'short_name',
));

According to the culture, the widget also knows the order of the three different select boxes and the separator to use between them.

sfWidgetFormI18nTime

The sfWidgetFormI18nTime extends the standard sfWidgetFormTime widget.

According to the culture passed as an option, the widget knows the order of the three different select boxes and the separator to use between them:

$w = new sfWidgetFormI18nTime(array('culture' => 'ar'));

sfWidgetFormI18nDateTime

The sfWidgetFormI18nDateTime widget is a widget that renders two sub-widgets: a sfWidgetFormI18nDate widget and a sfWidgetFormI18nTime one.

sfWidgetFormDateRange

The sfWidgetFormDateRange widget represents a choice of a range of dates:

$w = new sfWidgetFormDateRange(array(
  'from_date' => new sfWidgetFormDate(),
  'to_date'   => new sfWidgetFormDate(),
));

The template used to render the widget can be customized with the template option:

$w = new sfWidgetFormDateRange(array(
  'from_date' => new sfWidgetFormDate(),
  'to_date'   => new sfWidgetFormDate(),
  'template'  => 'Begin at: %from_date%<br />End at: %to_date%',
));

sfWidgetFormJQueryDate

The sfWidgetFormJQueryDate widget represents a date widget rendered by JQuery UI:

$w = new sfWidgetFormJQueryDate(array(
  'culture' => 'en',
));

I18n Widgets

sfWidgetFormI18nSelectCountry

The sfWidgetFormI18nSelectCountry represents a choice of countries:

$w = new sfWidgetFormI18nSelectCountry(array('culture' => 'fr'));

sfWidgetFormI18nSelectLanguage

The sfWidgetFormI18nSelectLanguage represents a choice of languages:

$w = new sfWidgetFormI18nSelectLanguage(array('culture' => 'fr'));

sfWidgetFormI18nSelectCurrency

The sfWidgetFormI18nSelectCurrency represents a choice of currencies:

$w = new sfWidgetFormI18nSelectCurrency(array('culture' => 'fr'));

Captcha Widget

The sfFormExtraPlugin plugin comes with a captcha widget, sfWidgetFormReCaptcha, based on the ReCaptcha project:

$w = new sfWidgetFormReCaptcha(array(
  'public_key' => 'RECAPTCHA_PUBLIC_KEY'
));

The public_key is the ReCaptcha public key. You can obtain one for free by signing for an API key.

As it is not possible to change the name of the ReCaptcha fields, you will have to add them manually when binding a form from an HTTP request.

For instance, if your form has a contact[%s] name format, here is the needed code to ensure that the captcha information will be merged with the rest of the form submitted values:

$captcha = array(
  'recaptcha_challenge_field' => $request->getParameter('recaptcha_challenge_field'),
  'recaptcha_response_field'  => $request->getParameter('recaptcha_response_field'),
);
$submittedValues = array_merge(
  $request->getParameter('contact'),
  array('captcha' => $captcha)
);

This widget is to be used with the sfValidatorReCatpcha validator.

Filter Widgets

Filter widgets are special widgets that can be used to render a form that acts as a filter.

sfWidgetFormFilterInput

sfWidgetFormFilterInput represents a filter for text. By default, it includes a checkbox to allow users to search for empty text.

sfWidgetFormFilterDate

sfWidgetFormFilterDate represents a widget to filter a range of date. By default, it includes a checkbox to allow users to search for empty dates.

sfWidgetFormSchema

The sfWidgetFormSchema widget represents a widget which is composed of several fields. A field is simply a named widget:

$w = new sfWidgetFormSchema(array(
  'name'    => new sfWidgetFormInput(),
  'country' => new sfWidgetFormI18nSelectCountry(),
));

The sfWidgetFormSchema constructor takes five optional arguments:

• An array of fields
• An array of options
• An array of HTML attributes
• An array of labels for the embedded widgets
• An array of help messages for the embedded widgets

The available options are:

If you want to change the default formatter for all forms, you can set the setDefaultFormFormatterName() method:

sfWidgetFormSchema::setDefaultFormFormatterName('list');

As the sfWidgetFormSchema extends the sfWidgetForm class, it inherits all its methods and behaviors.

<Table>
  <?php echo $ws->render('') ?>
</table>

The sfWidgetFormSchema can be used as an array to access the embedded widgets:

$ws = new sfWidgetFormSchema(array('name' => new sfWidgetFormInput()));
 
$nameWidget = $ws['name'];
 
unset($ws['name']);

As a widget schema is a widget like any other, widget schemas can be nested:

$ws = new sfWidgetFormSchema(array(
  'title'  => new sfWidgetFormInput(),
  'author' => new sfWidgetFormSchema(array(
    'first_name' => new sfWidgetFormInput(),
    'last_name'  => new sfWidgetFormInput(),
  )),
));

You can access embedded widget schema widgets by using the array notation:

$ws['author']['first_name']->setLabel('First Name');

Below, the main methods of widget schema classes are described. For a full list of methods, refer to the online API documentation.

setLabel(), getLabel(), setLabels(), getLabels()

The setLabel(), getLabel(), setLabels(), and getLabels() methods manages the labels for the embedded widgets. They are proxy methods for the getLabel() and setLabel() widget methods.

$ws = new sfWidgetFormSchema(array('name' => new sfWidgetFormInput()));
 
$ws->setLabel('name', 'Fabien');
 
// which is equivalent to
 
$ws['name']->setLabel('Fabien');
 
// or
 
$ws->setLabels(array('name' => 'Fabien'));

The setLabels() method merges the values with the existing ones.

setDefault(), getDefault(), setDefaults(), getDefaults()

The setDefault(), getDefault(), setDefaults(), and getDefaults() methods manages the default values for the embedded widgets. They are proxy methods for the getDefault() and setDefault() widget methods.

$ws = new sfWidgetFormSchema(array('name' => new sfWidgetFormInput()));
 
$ws->setDefault('name', 'Fabien');
 
// which is equivalent to
 
$ws['name']->setDefault('Fabien');
 
// or
 
$ws->setDefaults(array('name' => 'Fabien'));

The setDefaults() method merges the values with the existing ones.

setHelp(), setHelps(), getHelps(), getHelp()

The setHelp(), setHelps(), getHelps(), and getHelp() methods manages the help message associated with embedded widgets:

$ws = new sfWidgetFormSchema(array('name' => new sfWidgetFormInput()));
 
$ws->setHelp('name', 'Fabien');
 
// which is equivalent to
 
$ws->setHelps(array('name' => 'Fabien'));

The setHelps() method merges the values with the existing ones.

getPositions(), setPositions(), moveField()

The fields contained in a widget schema are ordered. The order can be changed with the moveField() method:

$ws = new sfWidgetFormSchema(array(
  'first_name' => new sfWidgetFormInput(),
  'last_name' => new sfWidgetFormInput()
));
 
$ws->moveField('first_name', sfWidgetFormSchema::AFTER, 'last_name');

The constants are the following:

• sfWidgetFormSchema::FIRST
• sfWidgetFormSchema::LAST
• sfWidgetFormSchema::BEFORE
• sfWidgetFormSchema::AFTER

It is also possible to change all positions with the setPositions() method:

$ws->setPositions(array('last_name', 'first_name'));

sfWidgetFormSchemaDecorator

The sfWidgetFormSchemaDecorator widget is a proxy widget schema which wraps a form schema widget inside a given HTML snippet:

$ws = new sfWidgetFormSchema(array('name' => new sfWidgetFormInput()));
 
$wd = new sfWidgetFormSchemaDecorator($ws, '<table>%content%</table>');