# sfN1IterationPlugin plugin #

The `sfN1IterationPlugin` makes easy the edition of simple iterations of a table with N-1 relations.

## Installation ##

      ./symfony plugin-install http://plugins.symfony-project.com/sfN1IterationPlugin

## Usage ##

      <?php use_helper('N1Iteration') ?>
      <?php echo N1iteration($partial, $className, $vars, $iteratorSuffix); ?>

`$partial` is the partial to be iterated.

`$className` is the class name of the object iterated.

`$vars` the same array as usually used in the partials. The first item of this array must be the objects iterated.

`$iteratorSuffix` an optional suffix for the iterator name. 

The partial must have an html tag with the string %id% in the id property, the helper will replace this with an 
unique identifier for every iteration. For example:

      <div id="%id%">
      <!--here your code -->
      </div>

### Javascript helpers ###

The plugin provides some simple javascript helpers to use in the partial:

`N1Iteration.Insertion.After('%id%')` for insert a iteration after this one.

`N1Iteration.Insertion.Before('%id%')` for insert before.

`N1Iteration.Remove('%id%')` for remove the iteration.

## An example ##

Let's see an example with the example data model of chapter 14:

[[Image(F1401.png)]]

The purpose is to easily edit all the comments of an article, in the same page of the article's edition page.
You can have this template to edit an article:

      <?php
        echo form_tag('article/save');
        echo input_tag('title', $article->getTitle());
        echo input_tag('content', $article->getContent());
        echo N1Iteration('iterationComment', 'Comment', 'comment' => $article->getComments());
        echo submit_tag('Save');
      ?>

And the partial (named `_iterationComment`) for the iteration:

      <div id="%id%">
      <?php
        echo input_tag('author[]', $comment->getAuthor());
        echo input_tag('content[]', $comment->getComment());
        echo button_to_function('Add comment', "N1Iteration.Insertion.After('%id%')");
        echo button_to_function('Remove comment', "N1Iteration.Remove('%id%')");
      ?>
      </div>

**Note: the names of inputs must have the `[]`, so you can get them as arrays later in the action.**

You can add, remove or edit easily the comments related to the article.

## N1IterationToolkit ##

Provides an easy way of saving and deleting rows related to an object. It receives four parameters:

 * ``$object``: the object whom related are going to be saved
 * ``$related_class_name``: the classname of related objects
 * ``$related_arrays``: the arrays with data to save
 * ``$options``: associative array with extra options:
   * ``order_field``: if you wish to save the order, here you can specify the name of the field who stores the order
   * ``delete_criteria``: you may want to filter rows to delete by any other fields, not only by object ID, so you can pass a Criteria object instance

Example: Delete only related rows with 'motorcycle' as their `type`

      $dC = new Criteria();
      $dC->add(VehiclePeer::TYPE, 'motorcycle');
      ...
      N1IterationToolkit::saveRelated($transportUser, 'Vehicle', array(
        'id'   => $this->getRequestParameter('id', array()),
        'type' => $this->getRequestParameter('type', array()),
        ...
      ), array(
        'order_field' => 'order_field_name',
        'delete_criteria' => $dC
      ));


## Changelog ##

### Version 0.1.4-beta ###

 * Minor changes, and fixed a little bug.

### Version 0.1.3-beta ###

 * Added N1IterationToolkit.class.php with a method to easily save related objects.

### Version 0.1.2-beta ###

 * Added an optional parameter (iteratorSuffix) to the helper, to deal with various iterators.

### Version 0.1.1-beta ###

 * Renamed the function in helper to avoid confusion.

### Version 0.1.0-beta ###
 
 * Initial public release.