Form Building: More Auto-Magic Than You Can Handle?

posted by: Nate :: Dec 21st 2006, 23:12

One thing that's been getting some attention in Cake 1.2 is the building of forms. Recently, I was rewriting some old code from an application which I've been developing on and off for quite a while now, and the difference was remarkable. Consider the following:

(Old)
<form id="TaskEditForm" method="post" action="/tasks/edit/<?=$data['Task']['id']; ?>" onSubmit="return false;">

Here we see a hand-coded form tag with embedded PHP, echoing the ID of the current Task object. Now consider the following code, updated for 1.2, which produces effectively the same output:

(New)
<?=$form->create(array('default' => false)); ?>

Okay, let's start with what we don't see. You'll notice first that we don't see any reference to a URL; neither a controller nor an action; not even a model name. We also don't see a DOM ID, or any reference to the JavaScript event in the preceeding code. Let's start with the bit about the model. In Cake 1.2, we're transitioning to an approach to form building that is more directly model-oriented, and according to the API, the first parameter to FormHelper::create() is actually supposed to be the name of a model, i.e.:

<?=$form->create('Task', array('default' => false)); ?>

However, if you don't provide one, it is assumed to be the default model for the controller (in this case TasksController).

So how does it even know whether this is an add or edit form? Simple: it checks $this->data for a value for the primary key for the given model. If it is set and not empty, it is assumed to be an edit form, otherwise it is an add form. According to convention, 'add' and 'edit' are the default names for form-related actions. Most of the rest of the attributes are pretty straightforward: as with form elements, DOM IDs are now auto-generated for forms themselves, based on the model and type (add/edit).

The last remaining bit is 'default' => false. This is new for both forms and links, and provides you a simple way to disable the default action without actually having to write any JavaScript.

We've also replaced most of the form-related methods in HtmlHelper with roughly equivalent ones in FormHelper. We've also added some wrapper methods to FormHelper, which you can provide with a few hints about how you want your form elements to render, and they take care of everything for you. Here's an example:

(Old)

// Controller:
$this->set('contacts', $this->Task->Contact->generateList());

// View:
<div class="input">
	<label for="TaskContactId">Assigned to</label>
	<?=$html->selectTag('Task/contact_id', $contacts, $this->data['Task']['contact_id'], null, null, false); ?>
</div>

(New)

// Controller:
$this->set('contacts', $this->Task->Contact->generateList());

// View:
<?=$form->input('contact_id', array('label' => 'Assigned to', 'empty' => false)); ?>

Again, both code listings produce effectively the same output.

FormHelper::input() takes various hints about what type of form element you want it to generate based not only on the information you provide it, but also on the field's model data, and on the view environment itself. Let's first compare the $form->input() part with the $html->selectTag() (you can ignore the controller code, it's the same in both). The first thing is the lack of the 'Task/' part in the field definition that is passed to the method. We're still using that syntax, but if you don't provide a model name, that's okay, because Cake already knows that we're creating a form for the Task model, so it is used automatically.

The next thing you'll notice is that $contacts, our list of options to actually use in the <select /> element, is not present in the view code at all. Since Cake knows that contact_id is a foreign key to another model, it checks the view for a variable called $contacts (the plural of the key name, with the '_id' part removed), and if it is found (and it is an array), Cake uses it as the option list.

The other factors that determine the type of form field that input() will generate are as follows:

• As in the above example, if the field is a foreign key, and the corresponding options variable is specified, a select menu will be rendered.
• If you specify an 'options' key in the second parameter, a select menu will be rendered.
• If the field name is 'password' or 'passwd', a password field will be rendered.
• Text and varchar fields are rendered as textareas and text inputs, respectively.
• Booleans render as checkboxes (and the label is rendered to the right of the element).
• Date, time, and datetime fields all render with the corresponding group of select menus.
• If the field is the primary key of the model, it renders as a hidden field.

Of course, you can always manually specify the type of element rendered using the 'type' key of the $options array, which can be set to any one of the following values: 'hidden', 'checkbox', 'text', 'password', 'file', 'select', 'time', 'date', 'datetime', or 'textarea'. If the 'type' key is unspecified, and the field type is not one of the above, it will render as a textarea.

In addition to rendering the input element itself, input() will also render a label, a wrapper <div /> and any associated validation messages, if present. This is all by default, but you can customize the behavior, as in the following:

<?=$form->input('terms', array('label' => array('text' => 'Terms of service', 'class' => 'title'))); ?>

Here, the 'label' key has been defined as an array in order to specify custom rendering options for the <label /> tag. You can also define 'label' as a string (the text of the label itself), or false, to disable the rendering of the label.

The 'div' key works similarly for controlling the rendering of the wrapper div, except that assigning it a string sets the class name.

Now, at the risk of being too meta, there's also a wrapper method for the wrapper method: FormHelper::inputs(). This method takes a single array parameter, which can be indexed, associative, or mixed. The array is simply a list of fields to be rendered with FormHelper::input(). By default, all fields are rendered with the default options, but you can use the associative array syntax to specify options for individual fields, as in the following:

<?=$form->inputs(array('first_name', 'middle_initial' => array('label' => 'MI'))); ?>

Here, the first_name field would be rendered with defaults, but the middle_initial field would be rendered with custom label text. Using this syntax it is possible (though not always recommended ;-)) to render an entire form in one line of code.

• older
• newer