Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config
lib/form
LICENSE
README
package.xml

README

# ahDoctrineEasyEmbeddedRelations plugin #

The `ahDoctrineEasyEmbeddedRelationsPlugin` is a symfony plugin that provides a Doctrine base form class to allow easy and more powerful embedding of forms.

For the inspiration of this plugin please read this blog post: [Embedding Relations in Forms with Symfony 1.3 and Doctrine](http://prendreuncafe.com/blog/post/2009/11/29/Embedding-Relations-in-Forms-with-Symfony-1.3-and-Doctrine). Thanks, Nicolas! :)

## Installation ##

  * Install the plugin (via a package)

        symfony plugin:install ahDoctrineEasyEmbeddedRelationsPlugin

  * Install the plugin (via a Subversion checkout)
  
        svn co http://svn.symfony-project.com/plugins/ahDoctrineEasyEmbeddedRelationsPlugin/trunk
                                              plugins/ahDoctrineEasyEmbeddedRelationsPlugin

  * Activate the plugin in `config/ProjectConfiguration.class.php`
  
        [php]
        class ProjectConfiguration extends sfProjectConfiguration
        {
          public function setup()
          {
            $this->enablePlugins(array(
              'sfDoctrinePlugin', 
              'ahDoctrineEasyEmbeddedRelationsPlugin',
              '...'
            ));
          }
        }
  
  * Change the parent class in `lib/form/doctrine/BaseFormDoctrine.class.php` to `ahBaseFormDoctrine `
  
        [php]
        abstract class BaseFormDoctrine extends ahBaseFormDoctrine
        {
          ...
        }
  
  * Clear your cache
  
        symfony cc

## Embedding relations ##

Here is an example schema definition:
  
    [yml]
    ahIntranetSubversionRepository:
      actAs:
        Timestampable:  ~
      tableName:        ah_intranet_subversion_repository
      columns:
        id:             { type: integer(4), primary: true, autoincrement: true }
        project_id:     { type: integer(4), notnull: true }
        name:           { type: string(64), notnull: true }
        repo_path:      { type: string(255), notnull: true }
        repo_username:  { type: string(64), notnull: true }
        repo_password:  { type: string(128), notnull: true }
      relations:
        ahProjectmanagerProject: { local: project_id, foreign: id, type: one, onDelete: CASCADE, foreignAlias: Repositories }

To embed one or more relations, add this to one of your form's configure method (or in a plugin form class: to the setup method):

    [php]
    public function configure()
    {
      ...
      $this->embedRelations(array(
        'Repositories' => array(
          'considerNewFormEmptyFields' => array('name', 'repo_path', 'repo_username', 'repo_password'),
          'noNewForm' => true,
          'newFormLabel' => 'New repository!!!', 
          'newFormClass' => 'ahIntranetSubversionRepositoryNewForm',
          'newFormClassArgs' => array(array('sf_user' => $this->getOption('sf_user'))),
          'displayEmptyRelations' => false,
          'formClass' => 'ahIntranetSubversionRepositoryEmbeddedForm',
          'formClassArgs' => array(array('ah_add_delete_checkbox' => false, 'another_form_option' => ...))
        ),
        '...' => array(
          ...
        )
      ));
    }

Be careful if you're using the new useFields method as this would unset the embedded forms again!

Also, please be aware that the `embedRelations` method does not follow the `embedRelation` method in that you cannot define an alias to use for the relation, you need to specify the relation key you used in the schema, which is, in this case, `Repositories`!

Each array defines one embedded relation and you can define a handful of options.

  * The minimal code is this:
  
        [php]
        public function configure()
        {
          ...
          $this->embedRelations(array(
            'Repositories' => array(
              'considerNewFormEmptyFields' => array('name', 'repo_path', 'repo_username', 'repo_password')
            )
          ));
        }

### Options explained ###

Only the first option is required, the rest can be guessed using the schema and Doctrine. :)

  * `considerNewFormEmptyFields` (the only required option, array): trouble starts when the user does not want to add a new related object but only wants to edit the main object's properties.
    As the embedded forms are validated, an error is thrown if one of the embedded form's field's is required.
    To remedy that you'll have to add all the fields to this array and if all of these are empty (read: only works for text fields for now), the empty form is dropped and no empty object is saved to the database (or validation errors thrown).
  
  * `noNewForm` (boolean, not required): if false, no empty form to add a new related object is embedded so you can only manage existing related objects.
  
  * `newFormLabel` (string, not required): the label that is shown for the new embedded form. If the form is used in the admin generator, label definitions in the generator.yml take precedence over this option:
        
        [yml]
        generator:
          ...
          param:
            ...
        
            config:
              actions: ~
              fields:
                ...
                new_Repositories:
                  label:           New repository
              list:
                ...
    
    The key to use in the fields array above is 'new_relationName' ('new_Repositories' in this case, see the example above).
    
  * `newFormClass` (string, not required): the form class to use for the empty form
  
  * `newFormClassArgs` (array of arrays, not required): form class options to pass to the empty form class on instantiation.
    Explanation for why it's an array of arrays: the way embedRelation works uses reflection to construct the right form objects. Now, the first argument is always the model object, the second is the form option array and the third is the local CSRF secret for the form.
    You don't need to worry about the first one (the model object) because this is always null for the new form. If you want to pass some more options to the related form object (like the user object to avoid using sfContext) just follow the example above.
    I could have changed this (because I implemented it) but I don't want to confuse the developer because when you look at the option `formClassArgs` below it's the same mechanism and I can't change that short of copying the whole embedRelation method over to the ahBaseFormDoctrine class, thereby losing the chance to automatically get upstream bugfixes. :)
  
  * `formClass` (string, not required): the form class to use for the existing related objects. 
  
  * `formClassArgs` (array of arrays, not required): form class options to pass to the existing related objects form class on instantiation
    As of version 1.1 it's not necessary to create a separate form class for the existing related forms to display the delete checkbox.
    This is now handled by the symfony event dispatcher. If you want to change how that works you can always copy over this method and change it to suit your needs:
    
        [php]
        public function listenToFormPostConfigureEvent(sfEvent $event)
        {
          $form = $event->getSubject();
          
          if($form instanceof sfFormDoctrine && $form->getOption('ah_add_delete_checkbox', false) && !$form->isNew())
          {
            $form->setWidget('delete_object', new sfWidgetFormInputCheckbox(array('label' => 'Just destroy the damn object!')));
            $form->setValidator('delete_object', new sfValidatorPass());
          }
        }
        
    Or if you're like me and want to save space, here's another version you can use:
    
        [php]    
        public function listenToFormPostConfigureEvent(sfEvent $event)
        {
          if ($form = parent::listenToFormPostConfigureEvent($event))
          {
            $form->widgetSchema['delete_object']->setOption('label', 'Just destroy the damn object!');
          }
        }
    
    This works because we're calling the plugin's event handler method.
    This either returns the form so it added the delete checkbox and the validator and you can act on that, or it returns false and you don't act on that. Neat and tidy. :)
  
  * `displayEmptyRelations` (boolean, not required): set this to true (false is the default) if you want to check for existing related objects yourself. This can be done in the form template and is useful if you want to let the user know that 'There are no related repositories yet.'. The default is just not displaying anything in this case, which works for me. :)

## Questions, bugs, feature requests? ##

I can be reached via e-mail: info@asapdesign.de

If you find bugs, have questions and/or feature requests, you can post to the symfony-user mailing list, 
of which I am an avid follower. :)
Something went wrong with that request. Please try again.