Ezzatron

I recently started learning how to use the forms system in symfony 1.2 and for the most part I was impressed with its simplicity and flexibility. Unfortunately I was thrown in the deep end somewhat when a project I was working on had a requirement for an “expanding” form – that is, one where a certain section of a form should be able to be repeated as many times as necessary to accommodate the user’s needs.

In the case of the project in question, the specific situation was an application form where the user could fill out any number of team members involved in their project. Each team member consisted of a name and a role, both free-form text fields. Team members were to be stored in the database, linked to the application in a one to many relationship.

Circumstances conspired that this must be achieved in a single form, so full of confidence in symfony’s design decisions regarding the forms system, a bit of light Googling revealed the answer – symfony’s embedded forms system. Great, so you just plonk in a few embedded forms and away you go, right? Wrong.

The good news is, I managed to find a solution that satisfied the requirements, eventually. The bad news is that it is not easy, elegant, or particularly reusable.

What follows is a loose guide to implementing such a system. Being a relative newcomer to symfony I cannot guarantee that this is the best way to do things, so tread with caution, and if you think of a better way to achieve the same outcome, please please let me know! Read on if you dare…

Introduction

I’m going to assume the following in this guide:

• You have a solid working knowledge of symfony, PHP and Doctrine.
• You have a blank symfony 1.2 project, set up to use Doctrine rather than Propel (although I’m sure the same could be achieved with Propel with a bit of tweaking).
• You have the symfony executable in your system path or in the root of your project.
• You are using a relational database such as MySQL to store your data.
• You have entered your database connection details into your config/databases.yml file and set up all the appropriate database permissions.
• You have completed any web server setup as required to access the project.
• You are aware that you need to clear the symfony cache (by running symfony cc) when new classes are created and when configuration changes are made.

I’m also going to move fairly quickly as there is a lot to cover, so please feel free to ask for any clarification in the comments and I will update as necessary.

For help with installing and setting up symfony 1.2, check out Getting started with symfony. I chose to use Doctrine 1.1 for this tutorial, however the version that comes with symfony should also be fine. For instructions on upgrading to Doctrine 1.1 see Using Doctrine 1.1 with Symfony 1.2.

You can also see a live demo and get an idea of what we are trying to achieve by visiting http://expandingform.sf.ezzatron.com/.

Step 1: Setting up

Here is the Doctrine schema we will be using. I went for something a bit more cheery than the above situation, namely bands and band members:

Place this in your config/doctrine/schema.yml file, and then create a data fixture so we have some test data to work with:

Place the above in data/fixtures/fixtures.yml and run:

This will generate all the model classes and forms we will need, create the database, and populate it with some test data for us. Next we need to create an application, and we’ll use the standard symfony app name “frontend”:

Replacing “randomstring” with whatever you like. Now let’s generate a module from our model classes as a base to start from:

Now if you visit http://<project url>/frontend_dev.php/band/edit/id/1 you should be presented with the following:

We now have a basic form for entering band details. Thus concludes step 1. Moving on to…

Step 2: Building the form

OK let’s dive right in. We are going to embed forms for editing band members inside of the band form itself. To add a single member form you would simply add:

to our lib/form/doctrine/BandForm.class.php‘s configure() method. But what we want is to structure the form in such a way that the form data, when posted to the update action, will contain an array of band members. The way to do so in the symfony forms system is to wrap the embedded forms in another form, then embed this wrapper form itself into the main form. Confused? Don’t worry, everything will become clearer once we actually create the forms.

Firstly, we need to make a small modification to the band member form to allow it to slot into our band form better. The generated form includes a field for the related band ID, which we will not need as all band members will relate to the band represented in the parent band form.

We could modify the BandMemberForm class itself, but it’s possible we may want to use the form outside of a band context, so let’s harness the power of the forms system and extend the form instead. Create a file at lib/form/doctrine/EmbeddedBandMemberForm.class.php with the following class definition (PHP opening tag excluded for brevity):

Next, let’s create the “container” form. Create a file at lib/form/doctrine/BandMembersForm.class.php containing the following class:

This creates three blank forms for inputting band members. Now to actually embed the container form into our main band form, it’s actually very simple. Simply edit lib/form/doctrine/BandForm.class.php so that it looks like the following:

Now when we reload our band form (did you remember to clear your cache?), we will see the following:

Looks promising, and that wasn’t too painful so far, right?

There next obvious step would be displaying the existing band members. We want to be able to see and edit the existing band members and still have the option of inputting new members also. To do this we need to pass the Band object to our container form so that it can access the existing members. Let’s update the container form so that it looks like:

Now we have to change the main form so that we pass the Band object when we instantiate the container form:

Reloading the form should now show the existing members:

So now we have a form that can display the band with all of its members and still provide room for new ones. Time for the next step.

Step 3: Getting the form to save

Try saving the form without making any changes to the data. You should get validation errors because the band member name is a required field:

This won’t do at all because we want to be able to leave a band member blank and have the system ignore it. We also want to be able to delete an existing member by clearing their name and role. So let’s remove the requirement for now, and we’ll add it back in later. Edit your EmbeddedBandMemberForm class so that it looks like this:

Now when we try to save the form again, we get an exception thrown:

As you can see, Doctrine is not happy with us, but why? The answer is that symfony is trying to create new band members from the blank band member forms, but it has no idea which band the new members should belong to. We’ll deal with this issue shortly, but in the meantime let’s start by making symfony ignore any band member forms which are left blank.

Firstly, how do we decide if a band member form is “blank”? Let’s write a couple of custom methods in our form classes. Some of this functionality is reusable, so we’ll place the main body of the code in lib/form/doctrine/BaseFormDoctrine.class.php which is the base class for all of our generated forms:

These two methods essentially traverse an array recursively looking for any non-blank values, and returns false as soon as one is found. The method needs to be recursive because some fields like dates are passed as an array. Now we can write a simple method in our EmbeddedBandMemberForm class to check whether the fields that constitute a band member have been filled out:

We are simply grabbing the field names directly from our model class, and excluding the ones we don’t care about. This is more robust that explicitly specifying name and role as the important fields, as it allows for further fields to be added to the band member form as requirements change.

Now we need to actually change the way the form is processed by overriding some methods in our main band form:

These methods doubtless require some explanation. Firstly let’s look at updateObjectEmbeddedForms(). This method uses the custom method we wrote to check whether the band members passed to the form for processing are blank. If a blank band member is encountered, the related form is removed from the forms array to prevent symfony from attempting to update the related band member object.

The next method, saveEmbeddedForms() works in tandem with the above. It runs through each of the forms and checks whether the related object has been modified. If an unmodified object is encountered, the related form is once again removed from the forms array to prevent symfony from attempting to save an unmodified object.

OK so now we should be able to save our form without any validation warnings or exceptions cropping up. If you can’t, it’s probably time to double check everything, and perhaps clear your cache. On to the next step…

Step 4: Adding and deleting members

Our form now saves without errors, but what does it actually do? Not much at the moment. Let’s try adding another band member. Ladies and gentlemen, may I present Steven on second guitar!:

What happens when we save the form? Ah, it seems we have the same issue we encountered before:

As we found out in the previous step, this is caused by symfony not knowing to link our new band member to the band we are editing. We can fix this by making a simple change to our BandForm class, in the saveEmbeddedForms() method:

Now when we try again, the new member is saved correctly and appears in the list of band members as expected:

Awesome! We now have 2 guitarists and all the glory that comes with duelling guitar solos. But wait; oh no! Steven has decided to get married and move to Norway! Well, it’s time to remove him from the band I guess, so let’s try setting his name and role to blank and see what happens when we save…

Oh dear, it seems Steven is not keen on leaving without a fight. He still appears in the list of band members. So what’s happening here? In short, we simply haven’t told Doctrine to dispose of the unwanted band member yet! Let’s go ahead and do that now by modifying the BandForm class’ updateObjectEmbeddedForms() method:

Now we can try again to delete Steven, and it seems to have worked:

So now we have a fully functional form, which is great! But there are some important things we still need to consider, which leads us to the next step…

Step 5: Validation

That’s right, you forgot, didn’t you? Back in step 3 we disabled important validation for the band member form, which means, for example, if you try to enter a band member with a role but no name, you get this nasty validation exception:

NOTE: You may find that you do not encounter this exception, there seems to be a bug somewhere where the “notblank” validator we specified in the schema is being ignored. Nevertheless, we still need to prevent blank names from being entered.

We can’t leave things as they stand, so let’s create a custom wrapper for the validator schema that we can use to validate band members that have not been left blank. Create a file at lib/validator/EmbeddedBandMemberValidatorSchema.class.php and enter this class definition:

All this class does is check whether the passed values are considered “blank” before applying the existing validation rules. This increases robustness by allowing us to keep all of the validation rules defined in the BandMemberForm class, and freeing us from having to duplicate their logic in the EmbeddedBandMemberForm class.

Now it’s simply a matter of making a small change to the EmbeddedBandMemberForm class’ configure() method to allow us to take advantage of our new wrapper class:

With those changes made, we can try again to save a band member with only a role and this time we are presented with the appropriate form errors:

OK, that’s validation taken care of, let’s make some usability improvements.

Step 6: Usability

We’re going to add extra functionality to our form for users with JavaScript support, namely the ability to add additional spaces for band members without the need to save the form. What’s more we’re going to do it without preventing non-JavaScript enabled users from using the form. This is known as progressive enhancement and is generally considered a best-practice in web development.

The first thing we need to do is set up an action to render the additional band member forms so that we can fetch them via an AJAX call. Open up your apps/frontend/modules/band/actions/actions.class.php file and add the following method:

The template for this action is very simple. Create a file at apps/frontend/modules/band/templates/memberFormSuccess.php with the following contents:

You may have noticed the call to BandForm::setNumMembers() in the above action. We still need to add this method, so let’s do that now. Edit your BandForm class and add the following method definition:

This in turn means a change to the BandMembersForm class, which should be edited to look like this:

What the above changes do are allow us to insert extra blank band members as we please. We then use this to recreate the “extra” band member form exactly as it would appear if it were rendered as part of the whole form.

All that is left to do is create the AJAX handler and some unobtrusive JavaScript to fetch and insert the new member form. Open apps/frontend/modules/band/templates/_form.php and update the contents to the following:

It’s important to note that this code is somewhat ugly because I wanted to avoid manually changing the form’s layout. In a production situation you could implement a much more elegant solution by customising the form layout or writing a custom form renderer.

This point aside, your form should now look like the image below when JavaScript is enabled (when JavaScript is disabled a message will be displayed informing the user of how to add additional members):

We’re now able to add additional slots for new members dynamically using the “Add member” button. We’re facing one last hurdle unfortunately; when we add a new member slot and hit the save button we’re presented with a form error:

Thankfully this is fairly easy to remedy. The issue is that when the update action handles the posted data, it creates a fresh instance of BandForm which has no knowledge of our “extra” band member form. To fix this we can override the BandForm class’ bind() method to detect the number of band members passed and expand the form as needed:

And hey presto, our form now works perfectly!

Conclusion

If you got this far I’m sure you’ll agree that this was not by any means an easy exercise. The symfony forms system is powerful and flexible, but it seems like perhaps this type of situation was not really brought into consideration when it was designed. I would love to see the symfony architects consider ways that the implementation of expanding forms could be simplified, or at least better documented.

Once again if you have any suggestions on how to improve this implementation I’d really love to hear them. I’m sure there are aspects of the symfony forms system that I don’t understand fully which could make this whole exercise somewhat simpler, and that would certainly be valuable knowledge.

If you are interested, there is a guide to implementing a similar system here, however it seems to deal with the symfony admin generator specifically, and it also seems to have the disadvantage that the parent object must exist before child objects can be added.

Good luck with your own implementations, let me know how they go!

Source code

• _form.php
• actions.class.php
• BandForm.class.php
• BandMembersForm.class.php
• BaseFormDoctrine.class.php
• EmbeddedBandMemberForm.class.php
• EmbeddedBandMemberValidatorSchema.class.php
• fixtures.yml
• memberFormSuccess.php
• schema.yml