move bundle directory at root

This should ease the browsing fo documentation (less menu and submenus)

source/bundles/custom-fields.rst

@@ -0,0 +1,239 @@
+.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
+   Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+   
+Custom fields bundle
+====================
+
+This bundle provide the ability to add custom fields to existing entities.
+
+Those custom fields contains extra data and will be stored in the DB, along with other data's entities. It may be string, text, date, ... or a link to an existing or to-be-created other entities.
+
+In the database, custom fields are stored in json format.
+
+.. seealso::
+
+   The full specification discussed `here. <https://redmine.champs-libres.coop/issues/239>`_
+   
+   `JSON Type on postgresql documentation <http://www.postgresql.org/docs/9.3/static/datatype-json.html>`_
+   
+Custom Fields concepts
+----------------------
+
+.. warning::
+
+   This section is incomplete
+   
+Allow custom fields on a entity
+--------------------------------
+
+As a developer, you may allow your users to add custom fields on your entities.
+
+Create a json field on your entity
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Declare a json field in your database :
+
+.. code-block:: yaml
+
+   Chill\CustomFieldsBundle\Entity\BlopEntity:
+      type: entity
+      # ...
+      fields:
+         customField:
+            type: json_array
+            
+Create the field accordingly :
+
+.. code-block:: php
+
+   namespace Chill\CustomFieldsBundle\Entity;
+   
+   /**
+   * BlopEntity
+   */
+   class BlopEntity
+   {
+   
+   /**
+   * @var array
+   */
+   private $customField = array();
+   
+   /**
+   * This method will be required for the Form component to record the 
+   * custom fields into the class
+   *
+   * @param array $customField
+   * @return BlopEntity
+   */
+   public function setCustomField(array $customField)
+   {
+      $this->customField = $customField;
+      return $this;
+   }
+   
+   /**
+   * Required by Forms to retrieve informations
+   *
+   * @return array
+   */
+   public function getCustomField()
+   {
+      return $this->customField;
+   }
+            
+Declare your customizable class in configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Two methods are available :
+
+* In your app/config.yml file. This is the easiest method, but discouraged because it will reduce the ease for installation.
+* In your Extension class : harder for devs, easier for installers.
+
+In app/config.yml file
+""""""""""""""""""""""
+
+Add those file under `chill_custom_fields` section :
+
+.. code-block:: yaml
+
+   chill_custom_fields:
+      customizables_entities:
+         - { class: Chill\CustomFieldsBundle\Entity\BlopEntity, name: blop_entity }
+         
+* The `name` allow you to define a string which is translatable. This string will appears when chill's admin will add/retrieve new customFieldsGroup.
+* The class, which is a full FQDN class path
+
+Automatically, in DepedencyInjection/Extension class
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. todo::
+
+   Explain how to declare customizable entitites in DepedencyInjection/Extension.
+
+Rendering custom fields in a template
+--------------------------------------
+
+Two function are available :
+
+* `chill_custom_field_widget` to render the widget. This function is defined on a customFieldType basis.
+* `chill_custom_field_label` to render the label. You can customize the label rendering by choosing the layout you would like to use.
+
+**chill_custom_field_label**
+
+The signature is :
+
+* `CustomField|object|string` **$customFieldOrClass** either a customField OR a customizable_entity OR the FQDN of the entity
+*  `string` **$slug** only necessary if the first argument is NOT a CustomField instance
+* `array` **params** the parameters for rendering. Currently, 'label_layout' allow to choose a different label. Default is 'ChillCustomFieldsBundle:CustomField:render_label.html.twig'
+
+Examples
+
+.. code-block:: jinja
+
+   {{ chill_custom_field_label(customField) }}
+
+   {{ chill_custom_field_label(entity, 'slug') }}
+
+   {{ chill_custom_field_label('Path\To\Entity', 'slug') }}
+
+
+**chill_custom_field_widget**
+
+*  array **$fields** the array raw, as stored in the db
+*  CustomField|object|string $customFieldOrClass either a customField OR a customizable_entity OR the FQDN of the entity
+*  string **$slug** only necessary if the first argument is NOT a CustomField instance
+
+Examples:
+
+.. code-block:: jinja
+
+   {{ chill_custom_field_widget(entity.customFields, customField) }}
+
+   {{ chill_custom_field_widget(entity.customFields, entity, 'slug') }}
+
+   {{ chill_custom_field_widget(fields, 'Path\To\Entity', 'slug') }}
+
+.. warning::
+
+   This feature is not fully tested. See `the corresponding issue <https://redmine.champs-libres.coop/issues/283>`_
+
+
+Custom Fields's form
+---------------------
+
+You should simply use the 'custom_field' type in a template, with the group you would like to render in the `group` option
+
+Example : 
+
+.. warning::
+
+   The above code isn't tested.
+
+.. todo:: 
+
+   Test the above code.
+
+.. code-block:: php
+
+   use Symfony\Component\Form\AbstractType;
+   use Symfony\Component\Form\FormBuilderInterface;
+   use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+   use Chill\CustomFieldsBundle\Form\Type\CustomFieldType;
+   use Chill\CustomFieldsBundle\Entity\CustomFieldsGroup;
+
+   class BlopEntityType extends AbstractType
+   {
+
+      public $group;
+
+      public function __construct(CustomFieldsGroup $group)
+      {
+         $this->group = $group;
+      }
+
+
+       /**
+        * @param FormBuilderInterface $builder
+        * @param array $options
+        */
+      public function buildForm(FormBuilderInterface $builder, array $options)
+      {
+         $builder
+            ->add('field1')
+            ->add('field2')
+            //->add('adress', new AdressType())
+            ->add('customField', 'custom_field', array('group' => $group))
+           ;
+       }
+   }
+
+
+
+
+Development tips
+-----------------
+
+If you want to test the rendering of a custom fields group, you may use this method :
+
+1. Run the built-in server **from the custom-fields directory** :
+
+.. code-block:: bash
+
+   ./run-server.sh
+
+2. assuming that your custom fields id is `1`, go to your navigator and enter url : `http://localhost:8000/customfieldsgroup/test/render/1`
+
+
+
+
+.. glossary::
+
+   customFieldsGroup
+      TODO
+      

source/bundles/index.rst

@@ -0,0 +1,24 @@
+.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
+   Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+Bundles documentation
+###############################
+
+You will find here documentation about bundles working with Chill.
+
+.. toctree::
+    :maxdepth: 2
+
+    Main bundle <main.rst>
+    Custom Fields bundle <custom-fields.rst>
+    Person bundle <person.rst>
+
+Your bundle here ?
+-------------------
+
+The contributors still do not have a policy about those bundle integration, but we would like to be very open on this subject. Please write to us `or open an issue <https://redmine.champs-libres.coop/projects/chill/issues>`_.

source/bundles/main.rst

@@ -0,0 +1,22 @@
+.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
+   Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+   
+Main bundle
+###########
+
+This bundle is **required** for running Chill.
+
+This bundle provide :
+
+* Access control model (users, groups, and all concepts)
+* ...
+
+
+.. warning::
+
+   this section is incomplete.

source/bundles/person.rst

@@ -0,0 +1,47 @@
+.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
+   Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+   
+Person bundle
+###########
+
+This bundle provides the ability to record people in the software. This bundle is required by other bundle
+
+Entities provided
+*****************
+
+.. todo::
+
+   describe entities provided by person bundle
+   
+   
+Search terms
+*************
+
+The class `Chill\PersonBundle\Search\PersonSearch` provide the search module.
+
+Domain
+=======
+
+The search upon "person" is provided by default. The `@person` domain search may be omitted.
+
+* `@person` is the domain search for people.
+
+
+Arguments
+=========
+
+* `firstname` : provide the search on firstname. Example : `firstname:Depardieu`. May match part of the firstname (`firsname:dep` will match **Dep**ardieu)
+* `lastname` : provide the search on lastname. May match part of the lastname.
+* `birthdate` : provide the search on the birthdate. Example : `birthdate:1996-01-19`
+* `gender`: performs search on man/woman. The accepted values are `man` or `woman`.
+* `nationality` : performs search on nationality. Value must be a country code `as described in ISO 3166 <http://www.iso.org/iso/fr/home/standards/country_codes.htm>`_. Example : `nationality:FR`.
+
+Default
+=======
+
+The default search is performed on firstname and/or lastname. Both are concatened before search. If values are separated by spaces, the clause `AND` is used : the search `dep ge` will match '**Gé**rard **Dep**ardieu` or 'Jean **Dep**a**ge**lles', but not 'Charline **Dep**ardieu' (missing 'Ge' in word).