add form types into the service container, update documentation

Builder/ORM/FormContractor.php

@@ -83,7 +83,7 @@ class FormContractor implements FormContractorInterface
         }
 
         // retrieve the related object
-        $childBuilder = $formBuilder->create($fieldName, new AdminType(), array(
+        $childBuilder = $formBuilder->create($fieldName, 'sonata_model_admin', array(
             'field_description' => $fieldDescription
         ));
 
@@ -160,7 +160,7 @@ class FormContractor implements FormContractorInterface
 
             // create a collection type with the generated prototype
             $options = $fieldDescription->getOption('form_field_options', array());
-            $options['type'] = new AdminType;
+            $options['type'] = 'sonata_model_admin';
             $options['modifiable'] = true;
             $options['type_options'] = array(
                 'field_description' => $fieldDescription,
@@ -194,15 +194,15 @@ class FormContractor implements FormContractorInterface
      */
     protected function defineManyToManyField(FormBuilder $formBuilder, FieldDescriptionInterface $fieldDescription)
     {
-        $type     = $fieldDescription->getOption('form_field_type', false);
+        $type     = $fieldDescription->getOption('form_field_type', 'sonata_admin_model');
         $options  = $fieldDescription->getOption('form_field_options', array());
 
-        if (!$type) {
-            $type = new ModelType($fieldDescription->getAdmin()->getModelManager());
+        if ($type == 'sonata_admin_model') {
             $options['class']               = $fieldDescription->getTargetEntity();
             $options['multiple']            = true;
             $options['field_description']   = $fieldDescription;
             $options['parent']              = 'choice';
+            $options['model_manager']       = $fieldDescription->getAdmin()->getModelManager();
         }
 
         $formBuilder->add($fieldDescription->getName(), $type, $options);

Form/Type/ModelType.php

@@ -24,13 +24,6 @@ use Sonata\AdminBundle\Model\ModelManagerInterface;
 
 class ModelType extends AbstractType
 {
-    private $modelManager;
-
-    public function __construct(ModelManagerInterface $modelManager)
-    {
-        $this->modelManager = $modelManager;
-    }
-
     public function buildForm(FormBuilder $builder, array $options)
     {
         if ($options['multiple']) {
@@ -45,16 +38,16 @@ class ModelType extends AbstractType
     public function getDefaultOptions(array $options)
     {
         $defaultOptions = array(
-            'template' => 'choice',
-            'multiple' => false,
-            'expanded' => false,
-            'model_manager' => $this->modelManager,
-            'class' => null,
-            'property' => null,
-            'query' => null,
-            'choices' => array(),
+            'template'      => 'choice',
+            'multiple'      => false,
+            'expanded'      => false,
+            'model_manager' => null,
+            'class'         => null,
+            'property'      => null,
+            'query'         => null,
+            'choices'       => array(),
+            'parent'        => 'choice',
             'preferred_choices' => array(),
-            'parent'  => 'choice',
             'field_description' => false,
         );
 

Resources/config/form_types.xml

@@ -13,6 +13,10 @@
             <tag name="form.type" alias="sonata_admin_collection" />
         </service>
 
+        <service id="sonata.admin.form.type.model" class="Sonata\AdminBundle\Form\Type\ModelType">
+            <tag name="form.type" alias="sonata_admin_model" />
+        </service>
+
     </services>
 
 </container>

Resources/doc/index.rst

@@ -20,6 +20,8 @@ Reference Guide
    reference/list_field_definition
    reference/filter_field_definition
    reference/form_field_definition
+   reference/form_types_and_transformers
+   reference/saving_hooks
    reference/routing
    reference/dashboard
 

Resources/doc/reference/form_types_and_transformers.rst

@@ -0,0 +1,24 @@
+Form types and data transformers
+================================
+
+The AdminBundle is shipped with custom form types and data transfomers in order
+to handle the diffent model's workflows and lifecycle.
+
+Form types
+----------
+
+    - ``sonata_model_admin`` : this type is linked to an Admin class and the field construction is
+      delegated to an Admin class.
+    - ``sonata_admin_collection`` : this type works like the native ``CollectionType`` but contains two extra
+      features : the data layer is abstracted to work with any implemented layer and a delete option is added
+      so a collection entry can be deleted.
+    - ``sonata_admin_model`` : this type works like the native ``EntityType`` but this internal is abstracted
+      to work with any implemented layer.
+
+
+Datatransformer
+---------------
+
+    - ``ArrayToModelTransformer`` : transform an array to an object
+    - ``ModelsToArrayTransformer`` : transform a collection of array into a collection of object
+    - ``ModelToIdTransformater`` : transform an ``id`` into an object

Resources/doc/reference/saving_hooks.rst

@@ -0,0 +1,79 @@
+Saving hooks
+============
+
+When the model is persited upon on the object stated two Admin methods are always call. You can extends this
+method to add custom business logic.
+
+    - new object : ``prePersist($object)`` / ``postPersist($object)``
+    - new object : ``preUpdate($object)`` / ``postUpdate($object)``
+    - deleted object : ``preRemove($object)`` / ``postRemove($object)``
+
+
+Example used with the FOS/UserBundle
+------------------------------------
+
+The ``FOSUserBundle`` provides authentication features for your Symfony2 Project. Compatible with Doctrine ORM & ODM.
+See https://github.com/FriendsOfSymfony/UserBundle for more information.
+
+The user management system requires to perform specific call when the user password or username are updated. This
+is how the Admin bundle can be used to solve the issue by using the ``prePersist`` saving hook.
+
+.. code-block:: php
+
+    <?php
+    namespace FOS\UserBundle\Admin\Entity;
+
+    use Sonata\AdminBundle\Admin\Admin;
+    use FOS\UserBundle\Model\UserManagerInterface;
+
+    class UserAdmin extends Admin
+    {
+        protected $userManager;
+
+        protected $form = array(
+            'username',
+            'email',
+            'enabled',
+            'plainPassword' => array('type' => 'string'),
+            'locked',
+            'expired',
+            'credentialsExpired',
+            'credentialsExpireAt',
+            'groups'
+        );
+
+        public function prePersist($user)
+        {
+            $this->getUserManager()->updateCanonicalFields($user);
+            $this->getUserManager()->updatePassword($user);
+        }
+
+        public function setUserManager(UserManagerInterface $userManager)
+        {
+            $this->userManager = $userManager;
+        }
+
+        /**
+         * @return UserManagerInterface
+         */
+        public function getUserManager()
+        {
+            return $this->userManager;
+        }
+    }
+
+
+The service declaration where the ``UserManager`` is injected into the Admin class.
+
+.. code-block:: xml
+
+    <service id="fos.user.admin.user" class="%fos.user.admin.user.class%">
+        <tag name="sonata.admin" manager_type="orm" group="fos_user" />
+        <argument />
+        <argument>%fos.user.admin.user.entity%</argument>
+        <argument />
+
+        <call method="setUserManager">
+            <argument type='service' id='fos_user.user_manager' />
+        </call>
+    </service>