← Home

Propel and patForms integrated: powerful form generation

5 steps to heaven

Let's have a look at what these both tools can do for you when they join forces.

  1. You simply throw a Propel class(name) into a patForms_Definition_Propel. This will look up information that's necessary to build a form and write it to a form definition xml file on the fly.
  2. Once created you can tweak the form definition xml file according to your needs. For example you might want to rename labels, descriptions or display different values from related tables (linked by foreign keys).
  3. But you don't need to tweak anything. Yet, handing this definition over to a patForms_Creator_Definition will create a complete and working patForms instance - full fledged with validation rules (both client- and server-side) and Html select boxes populated from related tables (via foreign keys).
  4. This patForms instance is able to connect to a patForms_Storage_Propel, that will (at present) look at the $_POST and $_GET vars and automagically retrieve, validate and save objects for you, populating the form from the object or - vice versa - populating the object from the form values.
  5. You can now render the patForms instance by using one of the provided patForms_Renderers and display the form elements and data using a template engine of your choice.

You're done.

New data has been validated before it has been saved to the database. If a validation error has occured, the error will be displayed by your form template and nothing has gone to the database. Existing objects have been fetched from the database, have been validated and updated.

Yes, life can be that easy :)

To say the least: we are really impressed about how seamlessly everything in Propel and patForms (both being great projects for themselves) fits together with only some minor changes to both of them. The good design pays out on both sides, keeping the libraries flexible and extensible.

7 lines of code

Wanna see some code? Ok, let's do it together ...

By now, it takes less than 10 lines of code to create a working "Add a new book" form for the bookstore example application shipped with Propel:

$definition = patForms_Definition_Propel::create(array(
   'name' => 'book', 'filename' => $filename));
$storage = patForms::createStorage('Propel');
$storage->setStorageLocation('BookPeer');
$form = &patForms::createCreator('Definition')->create($definition);
$form->setRenderer(patForms::createRenderer('Array'));
$form->setStorage($storage);

The result will look like this:

screenshot 1

As you can see, there are two related tables (foreign keys) defined for the Propel Book entity: Author and Publisher, both referenced by ID. For each of them a Select box is created and already populated with the IDs available from those tables.

screenshot 2

Some very little changes

Of cause, we'll want to show something different than these IDs here. So, we'll tweak the form definition xml file, that's already been created on-the-fly.

For the AuthorId, we'll change the lines

<members>
  <tag>Id</tag>
</members>
<mask>%s</mask>
to something like this: 
<members>
  <tag>FirstName</tag>
  <tag>LastName</tag>
</members>
<mask>%s (%s)</mask>

And (after having additionally changed some labels and titles) we'll get:

screenshot 3

Save new and edit existing

When we fill in some valid form data and click the "Save Form" button, the data gets already saved to the database table. (This will be painlessly done by a patForms_Storage_Propel driver by simply registering it to the form.)

By the way ... want an "Edit an existing book" form instead?

Just add one single line before rendering the form to the template:

$form->setValues(array('Id' => 1)); // the primary key

This will display the Book with the ID 1 and we will already be able to edit existing data and save it back to the database:

screenshot 4

Even shorter?

It's no big deal to further imagine a patForms_Factory::create() method, that could be called by something like this:

$form = patForms_Factory::create(array(
	'type' => 'Propel',
	'class' => 'Book',
	'renderer' => 'Array',
	'primary' => array('Id', 1)
));

One call for a complete and full-fledged, auto-validated form that's defined by the database scheme and some very simple additional changes in an xml file.

Hey, don't say that's not really cool :)

Go and play with it ...

You will need working installations of:

... as well as a build version of the Propel Bookstore project (tested with mysql). Have a look at the Propel docs to get started with the Bookstore build.

But don't use it!

Ok. :)

This is a proof of concept. There are several flaws and missing stuff, things to be discussed and solved. And yes: patForms itself is considered to be in alpha ...

But with some extra work here and there these both tools will make up a really great team that can help you to get started very fast with a working prototype for your data(base)-driven web application.

Feedback?

Do you like this? Then please digg it!