David's virtual world

Improving the forms even more

After reading Bernhard’s great article about how the symfony forms framework could be enhanced I sat back and thought: how would I like the forms to be? What could be improved to increase my efficiency? Well, after 2 days of brain storming I have found those areas:

• Field grouping
• Field formatters
• Required marks
• Separators
• Submit buttons
• Help texts
• I18n for everything

In my current symfony project at work I’m using at least 9 different forms, tendency rising. There are lots of things that would help making most of them easier to use.

Field grouping

The W3C HTML specification provides a clean solution to grouping form fields: fieldset and legend elements. Symfony doesn’t support them by now, but I think they are crucial, since lots of people use them and they are quite easy to define.
Looking at Bernhard’s code sample let’s suppose we want to group the username and email fields and then the password fields:

  public function configure()
  {
    $this->addGroup('user_stuff', 'Personal information');
 
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    $this->addField('email')
         ->setValidator(new sfValidatorEmail());
 
    $this->addGroup('password_stuff', 'Password information');
 
    $this->addField('password', new PasswordField());
 
    $this->addField('password_again')
         ->setWidget(new sfWidgetPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');
  }

In my imagination this should render like this:

<fieldset id="user_stuff">
  <legend>Personal information</legend>
  <!-- The name and email form fields go here -->
</fieldset>
 
<fieldset id="password_stuff">
  <legend>Password information</legend>
  <!-- The password form fields go here -->
</fieldset>

The magic would be that “addGroup($name, $legendText)” would automatically close a previous group and add all further fields to the current group fieldset. To close a group manually and add the following fields to the global scope a closeGroup() method would be enough.
The grouping HTML code would be defined in the form’s formatter, which can be enhanced easily:

class sfWidgetFormSchemaFormatterList extends sfWidgetFormSchemaFormatter
{
  protected
    // other stuff
    $groupFormat = "<fieldset>\n  <legend>%legend%</legend>\n  %content%</fieldset>";
}

And what if we add a form field later on that belongs to a previous group? Nothing easier than that!

    $this->addFieldToGroup('surname', 'user_stuff');

At the end of the article you’ll see why I think it would be useful to have this in the form definition.

Field formatters

Besides the grouping my forms share one more thing: not all the fields are rendered the same way. Some of them require parameters to the label tag or just completely different row stylings. The solution to this at the moment: I have to generate the row myself. The drawback: I’m usually too lazy to include stuff like error rendering and if I change the formatter one day I have to manually alter all the custom form field rows. There’s only one summary for this: it sucks!
Why not enable custom formatters per row? There’s not even a need to define something new, we can re-use the existing formatter code!

  public function configure()
  {
//  This is how formatters are defined now:
//  $this->widgetSchema->setFormFormatterName('List');
 
//  Make it more intuitive in the first place:
    $this->setFormatterName('List');
 
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    $this->addField('email')
         ->setValidator(new sfValidatorEmail());
 
    $this->addField('password', new PasswordField())
         // here it comes!
         ->setFormatterName('customPasswordFormat');
 
    $this->addField('password_again')
         ->setWidget(new sfWidgetPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)')
         // and here!
         ->setFormatterName('customPasswordFormat');
  }

The only thing that changes here is that the 2 password fields would be formatted using another formatter. Everything else would stay the same. So simple and yet so powerful…

Required marks

There have been lots of discussions on the mailing lists how required fields should be displayed. My favourite solution would be to put this where all the other formatting stuff goes: to the formatter.

class sfWidgetFormSchemaFormatterList extends sfWidgetFormSchemaFormatter
{
  protected
    $rowFormat       = "<li>\n  %error%%label%%required%\n  %field%%help%\n%hidden_fields%</li>\n",
    // other stuff
    $requiredFormat = "<span>*</span>";
}

Combined with the ability to define custom styles per field this would be a powerful solution.
Ah, there’s something else I would like to notice: defining the required property in the validator is fine from a techie-architect-point-of-view (as are so many other form related issues). But let’s once more see it from the user’s perspective:

  public function configure()
  {
    // old way
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15, 'required' => true));
 
    // what about this?
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15))
         ->setRequired(true);

See the difference? I’d personally like to have both options, but the second one would be much more intuitive from the user’s point of view.

Separators

Update 2009-04-16: I’m not sure anymore that separators like I described them here are a good idea. I’ll keep the content unchanged for anyone to understand the discussion that followed. Keep in mind that all this is a kind of brain storming which naturally results in more storm than brain .

Separators are quite useful in templates when 2 form rows shouldn’t be too close to each other or separated visually using a horizontal line or whatever. In the template this is usually done like this:

  <?php echo $form['name']->renderRow() ?>
  <div class="separator"></div>
  <?php echo $form['email']->renderRow() ?>

Let’s extend the formatter first (you know what I’m getting at, don’t you?):

class sfWidgetFormSchemaFormatterList extends sfWidgetFormSchemaFormatter
{
  protected
    // other stuff
    $separatorFormat = '<div class="separator"></div>';
}

Now we can use it in the form code. And we can use different separators in the same form!

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    $this->addSeparator();
 
    $this->addField('email')
         ->setValidator(new sfValidatorEmail());
 
    $this->addSeparator()
         ->setFormatterName('anotherSeparatorFormat');
 
    $this->addField('password', new PasswordField());

Submit buttons

Submit buttons belong to the form. They are even input widgets from a technical point of view. So why not add them to the form definition?

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    // all the other fields 
 
    // solution 1
    $this->addField('submit')
         ->setWidget(new sfWidgetSubmit('Submit the form'))
         ->setValidator(new sfValidatorPass());
 
    // solution 2
    $this->addSubmitButton('submit', 'Submit the form');

Together with the ability to use a specific formatter for the submit widget this would make every kind of submit button possible.

Help texts

So far the only possible way to add help texts to your form is passing them to the renderRow() method like this:

  echo $form['name']->renderRow(array(), 'Label text', 'Help text');

Why is this separated from the form definition? Especially if the label is defined inside the form? Are there scenarios where the label stays the same but the help text changes? I don’t think so!
Let’s try an alternative approach:

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15))
         ->setLabel('Label text')
         ->setHelp('Help text');

You see that this is mixing content with structure. But since most of the forms stuff is mixing content with structure (otherwise the labels should never have been in the form definition in the first place) why not allow to do it properly? And this leads to my last point:

I18n for everything

Symfony is great. Symfony has many powerful features. Symfony supports internationalization (short i18n) for everything. Everything? Not so! The form classes strictly defy being i18ned (sic!), making you wrap labels and help texts in __() functions in the template and hoping that the users don’t mind english error messages. Is there a reason for this? Of course: removing the form’s dependency to use an i18n instance. Is this necessary? I don’t think so:

  public function configure()
  {
    $this->enableI18n(sfContext::getInstance()->getI18n());

Inject the i18n instance into the form. After that, everything could be translated: labels, help texts, messages, errors, even formatters! If you don’t want to use it, don’t. If you need it, make sure you get the damn i18n instance into the form somehow (there are solutions…). I know this is not easy because it changes how most of the widgets are rendered. But I think it would be worth the price.

Why do I want all this stuff?

That’s lots of feature requests. That’s lots of extensions and changes to the forms framework. But why? I can tell you! Because if all of the above features were available, 80% of my form templates could look like this:

  <?php echo $form->render() ?>

Wouldn’t that be worth it? Wouldn’t that help the core powers of symfony: KISS and DRY? I know that some projects have different people for generating form code and markup, but I think most work is done by the same developers. At least this would provide an option to do it differently.

Comments are welcome!