diff --git a/source/development/bundles/custom-fields.rst b/source/development/bundles/custom-fields.rst new file mode 100644 index 000000000..835921154 --- /dev/null +++ b/source/development/bundles/custom-fields.rst @@ -0,0 +1,119 @@ +.. 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. `_ + + `JSON Type on postgresql documentation `_ + +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 Configuration class + +In app/config.yml file +"""""""""""""""""""""" + +Add those file under `chill_custom_fields` section : + +.. code-block:: yaml + + chill_custom_fields: + customizables_class: + - { 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 + + + + +.. glossary:: + + customFieldsGroup + TODO + diff --git a/source/development/bundles/index.rst b/source/development/bundles/index.rst new file mode 100644 index 000000000..c077c1633 --- /dev/null +++ b/source/development/bundles/index.rst @@ -0,0 +1,16 @@ +.. 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". + +Official bundles documentation +############################### + +.. toctree:: + :maxdepth: 2 + + Main Bundle + Custom Fields diff --git a/source/development/bundles/main.rst b/source/development/bundles/main.rst new file mode 100644 index 000000000..254317691 --- /dev/null +++ b/source/development/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. diff --git a/source/development/index.rst b/source/development/index.rst index db2afa25f..c06ca6db5 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -16,8 +16,9 @@ As Chill rely on the `symfony `_ framework, reading the fram Install Chill for development Instructions to create a new bundle - Bundles and tests + Testing manual/index.rst + Official bundle's documentation Help, I am lost !