Upgrading views and documentation

Author: abdielcs

README.md

@@ -1,15 +1,59 @@
-Work in progress...
+Work in progress ...
 
 Expanded Collection List
 ========================
 
 --picture here--
 
-Symfony 2 and 3 bundle for rendering related collections of entities
-as an expanded selectable list.
+Symfony 2 and 3 bundle for rendering a collection of entities as an expanded selectable list.
+Include some usefull form types extending the native entity form field, so all entity options
+could by used (like query_builder), except expanded and multiple, since all the bundle types are based in those
+options setted to true. Read more about entity type field in the [symfony documentation](https://getcomposer.org/doc/00-intro.md).
+
 
 **Features**
 
-  * Render OneToMany related collection as a selectable list.
-  * Render ManyToMany related collection as a selectable list.
-  * Configurable entity properties to be rendered.
+  * [Be able to configure wich entity properties or get method should be rendered and how](Resources/doc/1-fields-configuration.md)
+  * [Render a collection of entities as an expanded checkbox list](Resources/doc/2-expanded-onetomany.md)
+  * [Handling ManyToMany related collection as an expanded checkbox list](Resources/doc/3-expanded-manytomany.md)
+  * [Support for bootstrap 3 symfony theme](Resources/doc/4-bootstrap_3_example.md)
+
+Installation
+------------
+
+### Step 1: Download the Bundle
+
+```bash
+$ composer require abdielcs/expanded-collection-bundle
+```
+
+This command requires you to have Composer installed globally, as explained
+in the [Composer documentation](https://getcomposer.org/doc/00-intro.md).
+
+### Step 2: Enable the Bundle
+
+```php
+<?php
+// app/AppKernel.php
+
+// ...
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = array(
+            // ...
+            new abdielcs\ExpandedCollectionBundle\ExpandedCollectionBundle(),
+        );
+    }
+
+    // ...
+}
+```
+
+That's it!. Now you can start to use it.
+
+License
+-------
+
+This software is published under the [MIT License](LICENSE.md)

Resources/doc/1-expanded-OneToMany.md

@@ -0,0 +1,253 @@
+Collection of entities as an expanded list
+==========================================
+
+Let's say that we need to create some shipment entity, and in the same step
+choose wich product to send. If we also need to show for each product more
+than the name, then the expanded native option of symfony form would'n be
+enougth. For that situation you can use the 'expanded_otm' form.
+
+An example of product entity:
+
+```php
+<?php
+
+namespace AppBundle\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * Product
+ *
+ * @ORM\Table()
+ * @ORM\Entity
+ */
+class Product
+{
+    /**
+     * @var integer
+     *
+     * @ORM\Column(name="id", type="integer")
+     * @ORM\Id
+     * @ORM\GeneratedValue(strategy="AUTO")
+     */
+    private $id;
+
+    /**
+     * @var string
+     *
+     * @ORM\Column(name="name", type="string", length=255)
+     */
+    private $name;
+
+    /**
+     * @var string
+     *
+     * @ORM\Column(name="code", type="string", length=255)
+     */
+    private $code;
+
+    /**
+     * @var string
+     *
+     * @ORM\Column(name="price", type="decimal")
+     */
+    private $price;
+
+    /**
+     * @var \stdClass
+     *
+     * @ORM\ManyToOne(targetEntity="Shipment", inversedBy="products")
+     * @ORM\JoinColumn(name="id_shipment", referencedColumnName="id")
+     */
+    private $shipment;
+
+    // ...
+
+    /**
+     * Set shipment
+     *
+     * @param \AppBundle\Entity\Shipment $shipment
+     * @return Product
+     */
+    public function setShipment(\AppBundle\Entity\Shipment $shipment = null)
+    {
+        $this->shipment = $shipment;
+
+        return $this;
+    }
+
+    /**
+     * Get shipment
+     *
+     * @return \AppBundle\Entity\Shipment
+     */
+    public function getShipment()
+    {
+        return $this->shipment;
+    }
+
+    public function __toString()
+    {
+        return $this->getName();
+    }
+}
+```
+
+And the shippment entity:
+
+```php
+<?php
+
+namespace AppBundle\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * Shipment
+ *
+ * @ORM\Table()
+ * @ORM\Entity
+ */
+class Shipment
+{
+    /**
+     * @var integer
+     *
+     * @ORM\Column(name="id", type="integer")
+     * @ORM\Id
+     * @ORM\GeneratedValue(strategy="AUTO")
+     */
+    private $id;
+
+    /**
+     * @var \DateTime
+     *
+     * @ORM\Column(name="created", type="datetime")
+     */
+    private $created;
+
+    /**
+     * @var array
+     *
+     * @ORM\OneToMany(targetEntity="Product", mappedBy="shipment", cascade={"all"})
+     */
+    private $products;
+
+    /**
+     * Constructor
+     */
+    public function __construct()
+    {
+        $this->products = new \Doctrine\Common\Collections\ArrayCollection();
+    }
+
+    // ...
+
+    /**
+     * Add products
+     *
+     * @param \AppBundle\Entity\Product $products
+     * @return Shipment
+     */
+    public function addProduct(\AppBundle\Entity\Product $products)
+    {
+        $this->products[] = $products;
+
+        return $this;
+    }
+
+    /**
+     * Remove products
+     *
+     * @param \AppBundle\Entity\Product $products
+     */
+    public function removeProduct(\AppBundle\Entity\Product $products)
+    {
+        $this->products->removeElement($products);
+    }
+
+    /**
+     * Get products
+     *
+     * @return \Doctrine\Common\Collections\Collection
+     */
+    public function getProducts()
+    {
+        return $this->products;
+    }
+}
+```
+
+With that in place them we can create the form type.
+
+```php
+<?php
+
+namespace AppBundle\Form;
+
+// ...
+
+class ShipmentType extends AbstractType
+{
+    /**
+     * @param FormBuilderInterface $builder
+     * @param array $options
+     */
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder
+            ->add('created')
+            ->add('products','expanded_otm',array(
+                'class'    => 'AppBundle\Entity\Product',
+                'fields' => array('name','code','price'),
+            ))
+        ;
+    }
+
+    // ...
+}
+```
+
+For get the expected view also we need to set a for theme in the show and edit views:
+
+```twig
+{% extends '::base.html.twig' %}
+
+{% form_theme form '@ExpandedCollection/Form/fields.html.twig' %}
+
+{% block body -%}
+    <h1>Shipment creation</h1>
+
+    {{ form(form) }}
+
+        <ul class="record_actions">
+    <li>
+        <a href="{{ path('shipment') }}">
+            Back to the list
+        </a>
+    </li>
+</ul>
+{% endblock %}
+```
+
+And that's all, the collection will be rendered as a checkbox list.
+
+Important: You could consider including the option 'by_reference' => false in the form
+and the next code in the Shipment class in order to handle the product's shipment reference.
+
+```php
+/**
+  * Add products
+  *
+  * @param \AppBundle\Entity\Product $products
+  * @return Shipment
+  */
+  public function addProduct(\AppBundle\Entity\Product $products)
+  {
+      $products->setShipment($this);  //include this line
+
+      $this->products[] = $products;
+
+      return $this;
+  }
+```