Stretching sfForm with Dynamic Elements(AJAX): A Love Story

sfForm meet AJAX, AJAX meet sfForm

The Goal

Simple: first, take a look at my previous article about building a simple todo list. Below is our target application (click to actually use it). The big addition now is that we've added a link you can click to add more input boxes. This is done through AJAX and our form is able to handle the "extra" elements.

Our advanced todo list

The Very Simple Setup (same as the simple todo list)

We're using the exact same setup as with the simple todo list. Some things have different names, but to start, the code is all the same. Click the link below to view the code.

  public function executeAdvanced(sfWebRequest $request)
  {
    $this->form = new advancedTodoForm();
  }
  public function executeAdvancedProcess(sfWebRequest $request)
  {
    $this->form = new advancedTodoForm();
    
    if($request->isMethod('post'))
    {
      $this->form->bind($request->getParameter('todo_list'));
      if($this->form->isValid())
      {
        $this->form->save();
        $this->redirect('todo/advanced');
      }
    }
    
    $this->setTemplate('advanced');
  }

class advancedTodoForm extends sfForm
{   
  public function configure()
  {    
    $todoWrapperForm = new sfForm();
    foreach(TodoPeer::doSelect(new Criteria()) as $todo)
    {
      $todoWrapperForm->embedForm('existing_'.$todo->getId(), new TodoForm($todo));
    }
    
    $todoWrapperForm->embedForm('new_1', new TodoForm());  // add one blank todo to start
    $this->embedForm('todos', $todoWrapperForm);
    
    $this->widgetSchema->setNameFormat('todo_list[%s]');
  }
  
  public function save()
  {
    $values = $this->getValues();
    
    foreach($this->embeddedForms['todos']->getEmbeddedForms() as $key=>$todoForm)
    {
      if ($values['todos'][$key]['task'])
      {
        // only save todos that aren't blank
        $todoForm->updateObject($values['todos'][$key]);
        $todoForm->getObject()->save();
      } elseif(!$todoForm->getObject()->isNew()) {
        // delete any existing todos that are now blank
        $todoForm->getObject()->delete();
      }
    }
  }
}

<form action="<?php echo url_for('todo/advancedProcess'); ?>" method="post">
  <?php echo $form->renderGlobalErrors(); ?>
    
  <div id="todo-wrapper">
    <?php foreach($form['todos'] as $fieldSchema): ?>
      <?php echo $fieldSchema['task']->render(); ?>
      <?php echo $fieldSchema['task']->renderError(); ?>
    <?php endforeach; ?>
  </div>
    
  <?php echo $form['_csrf_token']; ?>
  <input type="submit" value="save" />
</form>

Adding the Magic

So far, all we have is the same thing as our simple todo form. To add additional input boxes, we're going to make an AJAX request. I use Jquery and post that code here. The most important thing, however, is that you make an ajax call (whatever your preferred method) to the action todo/advancedAddTodoAjax and spit out the result somewhere inside your form. As you can see below, I keep a count of my new todos and send it along to our action under the parameter name 'todo_index'.

<form...>
  ...
  <a href="#" onclick="return add_todo();" class="add-another" title="add another todo item box">Add another</a>
</form>
<script type="text/javascript">
  var new_todo_index=2;
  
  add_todo = function()
  {
    $.post(
      '<?php echo url_for('todo/advancedAddTodoAjax'); ?>',
      { todo_index: new_todo_index },
      function(data, textStatus) {
        $('#todo-wrapper').append(data);
      }
    );
    new_todo_index = new_todo_index+1;
    
    return false;
  }
</script>

The AJAX Action

The job of the AJAX action is simple: to return a new todo widget that will function nicely with our form when it's finally submitted. Doing this is no different than any other situation where we output form elements. Like always, we setup our form, then render its elements. The only difference is that in this case, we only need to render 1 element (our new todo widget) instead of the entire form.

  public function executeAdvancedAddTodoAjax(sfWebRequest $request)
  {
    $todoIndex = $request->getParameter('todo_index');
    $this->forward404Unless($todoIndex);
    
    $embedName = 'new_'.$todoIndex; // the unique name to give this form
    $form = new advancedTodoForm();
    $form->addNewTodoField($embedName);
    
    $output = $form['todos'][$embedName]['task']->render();
    $this->renderText($output);
    
    return sfView::NONE;
  }

Notice that we used the todo_index request parameter to form a unique name for our new embedded form. Since the first argument in embedForm is used to construct the name attribute of each element, it's important that each be unique.

The action is simple: build your form like normal, then add in a new field. This ensures that our new input element is output as if it's been a part of the original form all along. The action introduces a new method in our form, seen here:

class advancedTodoForm extends sfForm
{   
  ...  
  public function addNewTodoField($name)
  {
    $this->embeddedForms['todos']->embedForm($name, new TodoForm());
    $this->embedForm('todos', $this->embeddedForms['todos']); // re-embed the form
  }
}

This method embeds a new blank TodoForm into the already-embedded 'todos' form. The second line "re-embed"s the 'todos' form into the main form. This line may/should look redundant to you. It's required due to the way that sfForm embeds forms. The first line alone doesn't fully embed our new blank TodoForm.

Progress Check - AJAX is up and running

At this point, you should add the following to your view right after $form->renderGlobalErrors(). Whether it be a bug or a feature, you'll need it or you won't see certain validation errors. In my opinion, if this isn't a bug, I'd like to hear the explanation as this seems like very sloppy behavior.

<?php echo $form['todos']->renderError(); ?>

You should now be able to click your "Add another" link as many times as you want to add more and more blank todo boxes. If you click save with any extra boxes, you'll get an "extra fields" error. Here's what's happening:

1. You click "add another" and a request is made to the server, which inserts a new blank todo box into your HTML
2. You click "save" and are sent to the advancedProcess action
3. This action sets up your default advancedTodoForm, which DOES NOT include the new todo element that was present in your HTML as a result of the AJAX call
4. The Symfony form validates your data and sees the additional AJAX element as "extra" data

Getting romantic with sfForm and AJAX, aka binding to the dynamic elements

As described above, the advancedTodoForm isn't aware of your new todo input fields and thus rejects them. This is where the rigidity of sfForms (good for security) meets the dynamic requirements of AJAX. Fortunately, the solution was quite simple.

class advancedTodoForm extends sfForm
{
  ...
    
  /**
   * Override to add extra form fields for new todo items (otherwise they fail as extra fields)
   */
  public function bind(array $taintedValues = null, array $taintedFiles = null)
  {
    foreach($taintedValues['todos'] as $key=>$newTodo)
    {
      if (!isset($this['todos'][$key]))
      {
        $this->addNewTodoField($key);
      }
    }
    
    parent::bind($taintedValues, $taintedFiles);
  }
  ...
}

In order to avoid validation errors, we need to properly add the missing form elements before our form is bound. To do this, we override the bind() method with the above code. The idea is stupidly simple: If our input data contains a todo field that doesn't correspond to an embedded TodoForm form, add it. Notice we use the addNewTodoField method - the same one used in our AJAX action. We're constructing our form (adding todo forms to it) to reflect the new fields that were added via AJAX.

And that's it. Now that our dynamic todo fields are detected and their forms are embedded, each form is automatically and correctly saved via our existing save function.

Is It Love?

All that I know for sure is that I love both the Symfony forms framework and sites that use AJAX to make the web function smoothly. With the forms framework being young and the importance of AJAX only being compounded, I expect that the relationship between the forms framework and AJAX will only improve. Personally, I'm actually very happy with the above solution - but I'm pretty easy to please. If not love, it's certainly the start to a beautiful relationship: it has to be.

And Happy Valentine's day in a week or so.

Attachments