From 449c5ba4f2d161e4223ea595e7f88705e1050cf6 Mon Sep 17 00:00:00 2001 From: Julie Lenaerts Date: Mon, 24 Nov 2025 11:49:54 +0100 Subject: [PATCH] Fix formatting issues --- docs/source/bundles/activity.md | 12 +- docs/source/bundles/custom-fields.md | 109 +++-- docs/source/bundles/group.md | 3 +- docs/source/bundles/person.md | 21 +- docs/source/bundles/report.md | 15 +- docs/source/bundles/rst/activity.rst | 71 --- docs/source/bundles/rst/custom-fields.rst | 441 ------------------ docs/source/bundles/rst/event.rst | 29 -- docs/source/bundles/rst/group.rst | 49 -- docs/source/bundles/rst/index.rst | 29 -- docs/source/bundles/rst/ldap.rst | 204 -------- docs/source/bundles/rst/main.rst | 49 -- docs/source/bundles/rst/person.rst | 233 --------- docs/source/bundles/rst/report.rst | 46 -- docs/source/development/crud.md | 2 +- docs/source/development/routing.md | 2 + docs/source/development/run-tests.md | 12 +- .../installation/enable-collabora-for-dev.md | 8 +- .../installation/installation-development.md | 82 ++-- .../installation/installation-production.md | 73 ++- docs/source/installation/msgraph-configure.md | 17 +- .../installation/prod-calendar-sms-sending.md | 2 +- 22 files changed, 197 insertions(+), 1312 deletions(-) delete mode 100644 docs/source/bundles/rst/activity.rst delete mode 100644 docs/source/bundles/rst/custom-fields.rst delete mode 100644 docs/source/bundles/rst/event.rst delete mode 100644 docs/source/bundles/rst/group.rst delete mode 100644 docs/source/bundles/rst/index.rst delete mode 100644 docs/source/bundles/rst/ldap.rst delete mode 100644 docs/source/bundles/rst/main.rst delete mode 100644 docs/source/bundles/rst/person.rst delete mode 100644 docs/source/bundles/rst/report.rst diff --git a/docs/source/bundles/activity.md b/docs/source/bundles/activity.md index fb4832d5e..f98f9b009 100644 --- a/docs/source/bundles/activity.md +++ b/docs/source/bundles/activity.md @@ -1,16 +1,7 @@ -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". - # Activity bundle This bundle provides the ability to record people in the software. This bundle is required by other bundle. - :local: - ###### Entities provided Describe the entities provided. @@ -21,11 +12,13 @@ Those options are available under `chill_activity` key. Example of configuration: +```yaml chill_activity: form: time_duration: - { label: '12 minutes', seconds: 720 } - { label: '30 minutes', seconds: 1800 } +``` form.time_duration *array* The duration which might be suggested when the user create or update an activity. The value must be an array of object, where each object must have a `label` and a `seconds` key. The label provide which is shown to user (the label will be translated, if possible) and the seconds the duration. @@ -48,6 +41,7 @@ Macro envelope When to use this macro ? When you want to represent an activity reason. Example usage : + ```jinja {% import 'ChillActivityBundle:ActivityReason:macro.html.twig' as m %} diff --git a/docs/source/bundles/custom-fields.md b/docs/source/bundles/custom-fields.md index 197637209..646de34f6 100644 --- a/docs/source/bundles/custom-fields.md +++ b/docs/source/bundles/custom-fields.md @@ -1,11 +1,3 @@ -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 provides the ability to add custom fields to existing entities. @@ -14,14 +6,10 @@ Those custom fields contains extra data and will be stored in the DB, along with In the database, custom fields are stored in json format. - 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) - The documentation of json type, which is used to store data in the database. - + The full specification discussed [here](https://redmine.champs-libres.coop/issues/239) - :depth: 4 - :local: + [JSON Type on postgresql documentation](http://www.postgresql.org/docs/9.3/static/datatype-json.html) + The documentation of json type, which is used to store data in the database. ### Custom Fields concepts @@ -33,12 +21,12 @@ Automatically, those fields are added at the person form. They are also printed ##### Custom fields and custom fields group -Custom fields are associated to a custom fields group. When a user want to add custom fields on an entity, he must first create a custom fields group and associate this field with an entity. Then he may add add custom fields to this groups. +Custom fields are associated to a custom fields group. When a user want to add custom fields on an entity, he must first create a custom fields group and associate this field with an entity. Then he may add add custom fields to this groups. Some entities needs a **default** custom fields group. For instance, the default custom fields group will be printed on the main form for person, and will be appended on the main person view. Some bundle does not use this feature (i.e. the `report` bundle). In the future of the `person bundle`, other custom fields group will be added in forms accessible from the menu, allowing users to completely customize and separate their entities. - + ### Allow custom fields on an entity As a developer, you must allow your users to add custom fields on your entities. @@ -48,31 +36,33 @@ As a developer, you must allow your users to add custom fields on your entities. ##### Create a json field on your entity Declare a json field in your database : - +```bash Chill\CustomFieldsBundle\Entity\BlopEntity: type: entity # ... fields: cFData: type: json_array - +``` + Create the field accordingly in the class logic : +```bash namespace Chill\CustomFieldsBundle\Entity; - + /** * BlopEntity */ class BlopEntity { - + /** * @var array */ private $cFData; - + /** - * You must set a setter in order to save automatically custom + * You must set a setter in order to save automatically custom * fields from forms, using Form Component * * @param array $cFData @@ -83,9 +73,9 @@ Create the field accordingly in the class logic : $this->cFData = $cFData; return $this; } - + /** - * You also must create a getter in order to let Form + * You also must create a getter in order to let Form * component populate form fields * * @return array @@ -94,7 +84,8 @@ Create the field accordingly in the class logic : { return $this->cFData; } - +``` + ##### Declare your customizable entity in configuration This step is necessary to allow user to create custom fields group associated with this entity. @@ -112,22 +103,25 @@ This method is discouraged but explained first as it helps to undersand the reco Add those file under `chill_custom_fields` section : +```yaml chill_custom_fields: customizables_entities: - { class: Chill\YourBundleBundle\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 DependencyInjection/Extension class (recommended) """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -This is the recommended way for declaring customizable classes. +This is the recommended way for declaring customizable classes. You can prepend configuration of `custom fields bundle` from the class `YourBundle\DependencyInjection\YourBundleExtension`. **Note** that you also have to implements `Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface` on this class to make the `prepend` function being taken into account. -Example here : +Example here : +```php class ChillYourBundleExtension extends Extension implements PrependExtensionInterface { /** @@ -141,16 +135,17 @@ Example here : } $container->prependExtensionConfig('chill_custom_fields', - array('customizables_entities' => + array('customizables_entities' => array( array( - 'class' => 'Chill\YourBundleBundle\Entity\BlopEntity', + 'class' => 'Chill\YourBundleBundle\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 @@ -162,19 +157,22 @@ Example here : You may add options to the groups associated with an entity. -In `config.yml` the declaration should be : +In `config.yml` the declaration should be : +```yaml chill_custom_fields: customizables_entities: - - + - class: Chill\YourBundleBundle\Entity\BlopEntity name: BlopEntity options: # this will create a "myFieldKey" field as text, with a maxlength attribute to 150 (see http://symfony.com/doc/master/reference/forms/types/text.html) - myFieldKey: {form_type: text, form_options: {attr: [maxlength: 150]}} + myFieldKey: {form_type: text, form_options: {attr: [maxlength: 150]}} +``` -In the `PrependExtensionInterface::prepend` function, the options key will be added in the configuration definition : +In the `PrependExtensionInterface::prepend` function, the options key will be added in the configuration definition : +```php class ChillYourBundleExtension extends Extension implements PrependExtensionInterface { /** @@ -188,10 +186,10 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad } $container->prependExtensionConfig('chill_custom_fields', - array('customizables_entities' => + array('customizables_entities' => array( array( - 'class' => 'Chill\YourBundleBundle\Entity\BlopEntity', + 'class' => 'Chill\YourBundleBundle\Entity\BlopEntity', 'name' => 'BlopEntity', 'options' => array( 'myFieldKey' => [ 'form_type' => 'text', 'form_options' => [ 'attr' => [ 'maxlength' => 150 ] ] @@ -201,9 +199,11 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad ); } } - -**Example :** the entity `Report` from **ReportBundle** has to pick some custom fields belonging to a group to print them in *summaries* the timeline page. The definition will use the special type `custom_fields_group_linked_custom_field` which will add a select input with all fields associated with the current custom fields group : +``` +**Example :** the entity `Report` from **ReportBundle** has to pick some custom fields belonging to a group to print them in *summaries* the timeline page. The definition will use the special type `custom_fields_group_linked_custom_field` which will add a select input with all fields associated with the current custom fields group : + +```php class ChillReportExtension extends Extension implements PrependExtensionInterface { /** @@ -218,15 +218,15 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad } $container->prependExtensionConfig('chill_custom_fields', - array('customizables_entities' => + array('customizables_entities' => array( array( - 'class' => 'Chill\ReportBundle\Entity\Report', + 'class' => 'Chill\ReportBundle\Entity\Report', 'name' => 'ReportEntity', 'options' => array( 'summary_fields' => array( 'form_type' => 'custom_fields_group_linked_custom_fields', - 'form_options' => + 'form_options' => [ 'multiple' => true, 'expanded' => false @@ -238,12 +238,13 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad ); } } +``` Note that `custom_fields_group_linked_custom_fields` does not create any input on `CustomFieldsGroup` creation : there aren't any fields associated with the custom fields just after the group creation... You have to add custom fields and associate them with the newly created group to see them appears. ### Rendering custom fields and custom fields group in a template - Each custom field can be `active` or not. Only `active` custom fields has to be dislayed. +Each custom field can be `active` or not. Only `active` custom fields has to be dislayed. For rendering custom fields, two function are available : @@ -271,12 +272,14 @@ Examples The signature is : * array **$fields** the array raw, as stored in the db -* CustomField **$customField** a customField instance +* CustomField **$customField** a customField instance * string **$documentType** the type of document. Default to `html`. Examples: +```bash {{ chill_custom_field_widget(entity.customFields, customField) }} +``` ##### chill_custom_field_is_empty @@ -298,14 +301,17 @@ The signature is : * array **$fields** the array raw, as stored in the db * CustomFieldsGroup **$customFieldsGroup** the custom field group to render +```bash {{ chill_custom_fields_group_widget(entity.cFData, entity.customFieldsGroup) }} +``` ### 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's type. -Example : +Example : +```php namespace Chill\ReportBundle\Form; use Symfony\Component\Form\AbstractType; @@ -324,14 +330,14 @@ Example : $builder ->add('user') - ->add('date', 'date', + ->add('date', 'date', array('required' => true, 'widget' => 'single_text', 'format' => 'dd-MM-yyyy')) #add the custom fields : - ->add('cFData', 'custom_field', + ->add('cFData', 'custom_field', array('attr' => array('class' => 'cf-fields'), 'group' => $options['cFGroup'])) ; } - + /** * @param OptionsResolverInterface $resolver */ @@ -360,22 +366,25 @@ Example : return 'chill_reportbundle_report'; } } +``` ### Available configuration Those options are available in the configuration, under the `chill_custom_field` key. Example : - +```yaml chill_custom_field: show_empty_values_in_views: false +``` show_empty_values_in_views *boolean*: Allow to hide / show empty values in views. The aim of this configuration parameter is to hide (or show) empty values when :term:`custom fields group` are rendered. Default value : `true` + ### Glossary custom fields group - A group of custom fields \ No newline at end of file + A group of custom fields diff --git a/docs/source/bundles/group.md b/docs/source/bundles/group.md index a86400ea7..1a69b9cdc 100644 --- a/docs/source/bundles/group.md +++ b/docs/source/bundles/group.md @@ -9,8 +9,6 @@ Permission is granted to copy, distribute and/or modify this document Allow to group people in a group. This group may be a family, an activity group, ... - :local: - ###### Entities ###### Macros @@ -27,6 +25,7 @@ Macro envelope When to use this macro ? When you want to represent group. Example usage : + ```jinja {% import 'ChillGroupBundle:Group:macro.html.twig' as m %} diff --git a/docs/source/bundles/person.md b/docs/source/bundles/person.md index b659dba53..1d9b0ad2c 100644 --- a/docs/source/bundles/person.md +++ b/docs/source/bundles/person.md @@ -1,16 +1,7 @@ -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. - :local: - ###### Entities provided describe entities provided by person bundle @@ -44,6 +35,7 @@ Those options are available under `chill_person` key. Example of configuration: +```yaml chill_person: validation: birthdate_not_after: P15Y @@ -57,6 +49,7 @@ Example of configuration: marital_status: visible spoken_languages: hidden address: visible +``` birthdate_not_after *string* The period duration before today during which encoding birthdate is not possible. The period is a string matching the format of `ISO_8601`, which is also use to build `DateInterval classes ](http://php.net/manual/en/dateinterval.construct.php). @@ -83,7 +76,7 @@ person_fields *array* Example: - ```yaml +```yaml chill_person: person_fields: nationality: hidden @@ -104,9 +97,9 @@ Macro file Macro envelope `render(p, withLink=false)` - `p` is an instance of :class:`Chill\PersonBundle\Entity\Person` + `p` is an instance of `Chill\PersonBundle\Entity\Person` - `withLink` :class:`boolean` + `withLink`: `boolean` When to use this macro ? When you want to represent a person. Example usage : @@ -124,7 +117,7 @@ This event is available to add content below of the vertical menu (on the right) The context is : -- `person` : the current person which is rendered. Instance of :class:`Chill\PersonBundle\Entity\Person` +- `person` : the current person which is rendered. Instance of `Chill\PersonBundle\Entity\Person` ###### Widgets @@ -132,6 +125,7 @@ The context is : The bundle provide a way to add a list of accompanyied person on the homepage: +```yaml chill_main: widgets: homepage: @@ -152,6 +146,7 @@ The bundle provide a way to add a list of accompanyied person on the homepage: # when the view is overriden, you can add some custom fields # to the view custom_fields: [school-2fb5440e-192c-11e6-b2fd-74d02b0c9b55] +``` ###### Commands diff --git a/docs/source/bundles/report.md b/docs/source/bundles/report.md index fb3a2242c..717f9e9d6 100644 --- a/docs/source/bundles/report.md +++ b/docs/source/bundles/report.md @@ -1,17 +1,8 @@ -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". - # Report bundle This bundle provides the ability to record report about people. We use custom fields to let user add fields to reports. - :local: - - The documentation about report is not writtend +The documentation about report is not written ## Concepts @@ -27,6 +18,6 @@ This bundle provides the ability to record report about people. We use custom fi ### Default -The report's date is the default value. +The report's date is the default value. -An error is thrown if an argument `date` and a default is used. \ No newline at end of file +An error is thrown if an argument `date` and a default is used. diff --git a/docs/source/bundles/rst/activity.rst b/docs/source/bundles/rst/activity.rst deleted file mode 100644 index bf7faf28d..000000000 --- a/docs/source/bundles/rst/activity.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. 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". - -.. _activity-bundle: - -Activity bundle -############### - -This bundle provides the ability to record people in the software. This bundle is required by other bundle. - -.. contents:: Table of content - :local: - -Entities provided -***************** - -.. todo:: - - Describe the entities provided. - - -Configuration options -********************* - -Those options are available under `chill_activity` key. - -Example of configuration: - -.. code-block:: yaml - - chill_activity: - form: - time_duration: - - { label: '12 minutes', seconds: 720 } - - { label: '30 minutes', seconds: 1800 } - -form.time_duration *array* - The duration which might be suggested when the user create or update an activity. The value must be an array of object, where each object must have a `label` and a `seconds` key. The label provide which is shown to user (the label will be translated, if possible) and the seconds the duration. - - Example: see the example above - - Default value: the values available are 5, 10, 15, 20, 25, 30, 45 minutes, and 1 hour, 1 hour 15, 1 hour 30, 1 hour 45 and 2 hours. - -.. _activity-bundle-macros: - -Macros -****** - -Activity reason sticker -======================= - -Macro file - `ChillActivityBundle:ActivityReason:macro.html.twig` -Macro envelope - `reason(r)` - - `p` is an instance of :class:`Chill\ActivityBundle\Entity\ActivityReason` - -When to use this macro ? - When you want to represent an activity reason. -Example usage : - .. code-block:: html+jinja - - {% import 'ChillActivityBundle:ActivityReason:macro.html.twig' as m %} - - {{ m.reason(r) }} diff --git a/docs/source/bundles/rst/custom-fields.rst b/docs/source/bundles/rst/custom-fields.rst deleted file mode 100644 index f56b0dc23..000000000 --- a/docs/source/bundles/rst/custom-fields.rst +++ /dev/null @@ -1,441 +0,0 @@ -.. 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: - -Custom fields bundle -==================== - -This bundle provides 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 entities. - -In the database, custom fields are stored in json format. - -.. seealso:: - - The full specification discussed `here. `_ - - `JSON Type on postgresql documentation `_ - The documentation of json type, which is used to store data in the database. - -.. contents:: Table of contents - :depth: 4 - :local: - -Custom Fields concepts ----------------------- - -Custom fields are extra data which may be added to entities by user. If a developer implements custom fields on a entity, users will be able to add more fields on this entity. - -Example: the `person bundle` allows to record `firstname`, `lastname`, `date of birth` fields. But users need to store information about the kind of house he has (if he owns his house, if he rents it, ...). Custom fields allows to create those fields. - -Automatically, those fields are added at the person form. They are also printed in the person view and in exports. - -Custom fields and custom fields group -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Custom fields are associated to a custom fields group. When a user want to add custom fields on an entity, he must first create a custom fields group and associate this field with an entity. Then he may add add custom fields to this groups. - -Some entities needs a **default** custom fields group. For instance, the default custom fields group will be printed on the main form for person, and will be appended on the main person view. Some bundle does not use this feature (i.e. the `report` bundle). - -.. note:: - - In the future of the `person bundle`, other custom fields group will be added in forms accessible from the menu, allowing users to completely customize and separate their entities. - -Allow custom fields on an entity --------------------------------- - -As a developer, you must allow your users to add custom fields on your entities. - -.. warning:: - For having custom fields, the class of the entity must contain a variable for storing the custom data. **By convention this variable must be called $cFData** - - -Create a json field on your entity -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Declare a json field in your database : - -.. code-block:: yaml - - Chill\CustomFieldsBundle\Entity\BlopEntity: - type: entity - # ... - fields: - cFData: - type: json_array - -Create the field accordingly in the class logic : - -.. code-block:: php - - namespace Chill\CustomFieldsBundle\Entity; - - /** - * BlopEntity - */ - class BlopEntity - { - - /** - * @var array - */ - private $cFData; - - /** - * You must set a setter in order to save automatically custom - * fields from forms, using Form Component - * - * @param array $cFData - * @return BlopEntity - */ - public function setCFData(array $cFData) - { - $this->cFData = $cFData; - return $this; - } - - /** - * You also must create a getter in order to let Form - * component populate form fields - * - * @return array - */ - public function getCFData() - { - return $this->cFData; - } - -Declare your customizable entity in configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This step is necessary to allow user to create custom fields group associated with this entity. - -Two methods are available. - -The recommended method is to do it in DependencyInjection/Extension class. It is recommended as your bundle will be well set up (for custom field) in every chill installation that use it. - -The discouraged method is to declare via the app/config.yml file. This is very quick to set up for a given chill installation but it is not done automatically : in every chill installation that use your bundle, this step has to be performed. - -In app/config.yml file (discouraged) -"""""""""""""""""""""""""""""""""""" - -This method is discouraged but explained first as it helps to undersand the recommended method. - -Add those file under `chill_custom_fields` section : - -.. code-block:: yaml - - chill_custom_fields: - customizables_entities: - - { class: Chill\YourBundleBundle\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 DependencyInjection/Extension class (recommended) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -This is the recommended way for declaring customizable classes. - -You can prepend configuration of `custom fields bundle` from the class `YourBundle\DependencyInjection\YourBundleExtension`. **Note** that you also have to implements `Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface` on this class to make the `prepend` function being taken into account. - -Example here : - -.. code-block:: php - - class ChillYourBundleExtension extends Extension implements PrependExtensionInterface - { - /** - * @param ContainerBuilder $container - */ - public function prepend(ContainerBuilder $container) - { - $bundles = $container->getParameter('kernel.bundles'); - if (!isset($bundles['ChillCustomFieldsBundle'])) { - throw new MissingBundleException('ChillCustomFieldsBundle'); - } - - $container->prependExtensionConfig('chill_custom_fields', - array('customizables_entities' => - array( - array( - 'class' => 'Chill\YourBundleBundle\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 - -.. seealso:: - - `How to simplify configuration of multiple bundles `_ - A cookbook page about prepending configuration. - - -Adding options to your custom fields groups -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You may add options to the groups associated with an entity. - -In `config.yml` the declaration should be : - -.. code-block:: yaml - - chill_custom_fields: - customizables_entities: - - - class: Chill\YourBundleBundle\Entity\BlopEntity - name: BlopEntity - options: - # this will create a "myFieldKey" field as text, with a maxlength attribute to 150 (see http://symfony.com/doc/master/reference/forms/types/text.html) - myFieldKey: {form_type: text, form_options: {attr: [maxlength: 150]}} - -In the `PrependExtensionInterface::prepend` function, the options key will be added in the configuration definition : - -.. code-block:: php - - class ChillYourBundleExtension extends Extension implements PrependExtensionInterface - { - /** - * @param ContainerBuilder $container - */ - public function prepend(ContainerBuilder $container) - { - $bundles = $container->getParameter('kernel.bundles'); - if (!isset($bundles['ChillCustomFieldsBundle'])) { - throw new MissingBundleException('ChillCustomFieldsBundle'); - } - - $container->prependExtensionConfig('chill_custom_fields', - array('customizables_entities' => - array( - array( - 'class' => 'Chill\YourBundleBundle\Entity\BlopEntity', - 'name' => 'BlopEntity', - 'options' => array( - 'myFieldKey' => [ 'form_type' => 'text', 'form_options' => [ 'attr' => [ 'maxlength' => 150 ] ] - )) - ) - ) - ); - } - } - -**Example :** the entity `Report` from **ReportBundle** has to pick some custom fields belonging to a group to print them in *summaries* the timeline page. The definition will use the special type `custom_fields_group_linked_custom_field` which will add a select input with all fields associated with the current custom fields group : - -.. code-block:: php - - class ChillReportExtension extends Extension implements PrependExtensionInterface - { - /** - * - * - * @param ContainerBuilder $container - */ - public function prepend(ContainerBuilder $container) - { - $bundles = $container->getParameter('kernel.bundles'); - if (!isset($bundles['ChillCustomFieldsBundle'])) { - throw new MissingBundleException('ChillCustomFieldsBundle'); - } - - $container->prependExtensionConfig('chill_custom_fields', - array('customizables_entities' => - array( - array( - 'class' => 'Chill\ReportBundle\Entity\Report', - 'name' => 'ReportEntity', - 'options' => array( - 'summary_fields' => array( - 'form_type' => 'custom_fields_group_linked_custom_fields', - 'form_options' => - [ - 'multiple' => true, - 'expanded' => false - ] - ) - )) - ) - ) - ); - } - } - -Note that `custom_fields_group_linked_custom_fields` does not create any input on `CustomFieldsGroup` creation : there aren't any fields associated with the custom fields just after the group creation... You have to add custom fields and associate them with the newly created group to see them appears. - -Rendering custom fields and custom fields group in a template -------------------------------------------------------------- - -.. warning:: - Each custom field can be `active` or not. Only `active` custom fields has to be dislayed. - -For rendering custom fields, 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_is_empty` indicates if the content of the custom fields is empty (return a boolean) - -For rendering custom fields group, a function is available : - -* `chill_custom_fields_group_widget` to render the widget. It will display the custom fields of the group in a dd / dt structure. - -chill_custom_field_label -^^^^^^^^^^^^^^^^^^^^^^^^ - -The signature is : - -* `CustomField` **$customField** 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_widget -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The signature is : - -* array **$fields** the array raw, as stored in the db -* CustomField **$customField** a customField instance -* string **$documentType** the type of document. Default to `html`. - -Examples: - -.. code-block:: jinja - - {{ chill_custom_field_widget(entity.customFields, customField) }} - -chill_custom_field_is_empty -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The signature is : - -* array **$fields** the array raw, as stored in the db -* CustomField **$customField** a customField instance - -Examples : - -.. code-block:: jinja - - {%- if chill_custom_field_is_empty(cFData, customField) == false -%} - - -chill_custom_fields_group_widget -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function only display custom fields that are `active`. - -The signature is : - -* array **$fields** the array raw, as stored in the db -* CustomFieldsGroup **$customFieldsGroup** the custom field group to render - -.. code-block:: jinja - - {{ chill_custom_fields_group_widget(entity.cFData, entity.customFieldsGroup) }} - -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's type. - -Example : - -.. code-block:: php - - namespace Chill\ReportBundle\Form; - - use Symfony\Component\Form\AbstractType; - use Symfony\Component\Form\FormBuilderInterface; - use Symfony\Component\OptionsResolver\OptionsResolverInterface; - - class ReportType extends AbstractType - { - /** - * @param FormBuilderInterface $builder - * @param array $options - */ - public function buildForm(FormBuilderInterface $builder, array $options) - { - $entityManager = $options['em']; - - $builder - ->add('user') - ->add('date', 'date', - array('required' => true, 'widget' => 'single_text', 'format' => 'dd-MM-yyyy')) - #add the custom fields : - ->add('cFData', 'custom_field', - array('attr' => array('class' => 'cf-fields'), 'group' => $options['cFGroup'])) - ; - } - - /** - * @param OptionsResolverInterface $resolver - */ - public function setDefaultOptions(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'data_class' => 'Chill\ReportBundle\Entity\Report' - )); - - $resolver->setRequired(array( - 'em', - 'cFGroup', - )); - - $resolver->setAllowedTypes(array( - 'em' => 'Doctrine\Common\Persistence\ObjectManager', - 'cFGroup' => 'Chill\CustomFieldsBundle\Entity\CustomFieldsGroup' - )); - } - - /** - * @return string - */ - public function getName() - { - return 'chill_reportbundle_report'; - } - } - - -Available configuration ------------------------- - -Those options are available in the configuration, under the `chill_custom_field` key. - -Example : - -.. code-block:: yaml - - chill_custom_field: - show_empty_values_in_views: false - -show_empty_values_in_views *boolean*: - Allow to hide / show empty values in views. The aim of this configuration parameter is to hide (or show) empty values when :term:`custom fields group` are rendered. - - Default value : `true` - -Glossary --------- - -.. glossary:: - - custom fields group - A group of custom fields diff --git a/docs/source/bundles/rst/event.rst b/docs/source/bundles/rst/event.rst deleted file mode 100644 index b902ee444..000000000 --- a/docs/source/bundles/rst/event.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. Copyright (C) 2016 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". - -.. _event-bundle: - -Event bundle -############ - -Template & Menu -=============== - -The event bundle has a special template with a specific menu for actions on -events. This menu is called `event`. - -ChillEventBundle::layout.html.twig ----------------------------------- - -This layout extends `ChillMainBundle::layoutWithVerticalMenu.html.twig` and add the menu `event` - -It proposes a new block : - -* event_content - - * where to display content relative to the event. diff --git a/docs/source/bundles/rst/group.rst b/docs/source/bundles/rst/group.rst deleted file mode 100644 index d678f31d9..000000000 --- a/docs/source/bundles/rst/group.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. Copyright (C) 2016 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". - -.. _group-bundle: - -Group bundle -############ - -Allow to group people in a group. This group may be a family, an activity group, ... - -.. contents:: Table of content - :local: - -Entities -******** - -.. figure:: /_static/bundles/group/group_classes_uml.png - - -.. _group-bundle-macros: - -Macros -****** - -Group sticker -============== - -Macro file - `ChillGroupBundle:Group:macro.html.twig` -Macro name - `_render` -Macro envelope - `group`, instance of :class:`Chill\GroupBundle\Entity\CGroup` - -When to use this macro ? - When you want to represent group. -Example usage : - .. code-block:: html+jinja - - {% import 'ChillGroupBundle:Group:macro.html.twig' as m %} - - {{ m._render(g) }} - - diff --git a/docs/source/bundles/rst/index.rst b/docs/source/bundles/rst/index.rst deleted file mode 100644 index 2c4f3f17e..000000000 --- a/docs/source/bundles/rst/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. 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 - Custom Fields bundle - Person bundle - Report bundle - Activity bundle - Group bundle - Event bundle - Ldap bundle (synchronisation between ldap and database) - -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 `_. diff --git a/docs/source/bundles/rst/ldap.rst b/docs/source/bundles/rst/ldap.rst deleted file mode 100644 index 5db77f1cd..000000000 --- a/docs/source/bundles/rst/ldap.rst +++ /dev/null @@ -1,204 +0,0 @@ -.. 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". - -.. _ldap-bundle: - -LDAP bundle -########### - -This bundle binds the database with an ldap directory. - -The bundle synchronize the ldap directory with users in the database. It also -provides a way to check user credentials against the ldap directory. - - -.. contents:: Table of content - :local: - -Current limitations -******************* - -- The length of the ldap dn must be < 255 characters -- if the username extracted from the ldap is updated, the changes are not reflected in the database and remains the same - - -Entities provided -***************** - -This bundle provides only one entity : :class:`Chill\\LdapBundle\\Entity\\UserLdapBinding` - -How the synchronizer works ? -**************************** - -#. The synchronizer performs a query on `dn` and `query` defined in the :ref:`configuration `. -#. For each entry returned by the query, it looks if the `dn` exists in the database - - #. If the entry does not exists : - - #. the synchronizer looks for user with same username as defined by `username_attr`, and bind it with the `dn` if it exists. - #. else, a user is created with username defined by `username_attr` (if the ldap contains more than one attribute, the first attribute returned is used) - - #. if a user exists which is already binded with the `dn`, the entry is ignored. - -#. The synchronizer looks for dn existing in database and which were not returned by the query performed in 1. - - #. If they exists, those user are set to `enabled=false`: they are not allowed to login. - -Installation -************ - -This bundle requires : - -- PHP LDAP ext -- `symfony/ldap` with minimal version 3.1. Note that, currently, Chill uses Symfony 2.8: you should add the dependency on this single package manually - -In your composer.json, for stable version : - -.. code-block:: json - - "require": { - // .. other dependencies - "symfony/ldap" : "~3.1", - "chill-project/ldap": "~1.0" - } - - - -And for dev version : - -.. code-block:: json - - "require": { - // .. other dependencies - "symfony/ldap" : "~3.1", - "chill-project/ldap": "dev-master@dev" - } - - -.. _configuration: - -Configuration -************** - -Configuration of the bundle -============================ - -.. code-block:: yaml - - # Default configuration for extension with alias: "chill_ldap" - chill_ldap: - server: # Required - - # the host of the ldap directory - host: ~ # Required, Example: localhost - - # the port to reach the ldap directory - port: 389 - - # the version of the ldap directory - version: 3 - - # Is the use of ssl required to establish connection - use_ssl: false - - # Is the use of startssl required to establish connection - use_starttls: false - - # the user to bind to dn directory. Required for searching existing users. - bind_dn: ~ # Required, Example: cn=user,dn=chill,dn=social - - # the user's password to bind to dn directory. - bind_password: ~ # Required, Example: paSSw0rD - user_query: # Required - - # The DN where the query is executed - dn: ~ # Example: ou=People,dc=champs-libres,dc=coop - - # The query which will allow to retrieve users - query: ~ # Example: (&(objectClass=inetOrgPerson)(userPassword=*)) - - # The attribute which will provide username (=login) - username_attr: cn - - -Example : - -.. code-block:: yaml - - chill_ldap: - server: - # host, bind_dn and bind_password are imported from parameters.yml - host: "%ldap_host%" - bind_dn: "%ldap_bind_dn%" - bind_password: "%ldap_bind_password%" - user_query: - dn: dc=champs-libres,dc=coop - query: "(&(objectClass=inetOrgPerson)(userPassword=*))" - - -Configuration of the security part of chill -============================================ - -Simply add the following config in the firewall of the security bundle : -`chill_ldap_form_login: ~`. This config is located in `app/config/security.yml` - -Example of a configuration : - -.. code-block:: yaml - - # in app/config/security.yml - - firewalls: - dev: - pattern: ^/(_(profiler|wdt)|css|images|js)/ - security: false - - default: - anonymous: ~ - # enable the login check by a form, agaisnt the database - form_login: - csrf_parameter: _csrf_token - csrf_token_id: authenticate - csrf_provider: form.csrf_provider - # enable the login check by a form, against the ldap - chill_ldap_form_login: ~ # this is the line you should add - - -Note that, if you enable the login check by form **and** by the ldap, -the password will be checked against the database **and** against the ldap. -If one of them match, the login will succeed. - -If you want to completely disable login check against the database, -simply remove the `form_login` entry and all his options. - -.. _command-and-crontab: - -Command and crontab -=================== - -Synchronize the database : - -.. code-block:: bash - - php app/console chill:ldap:synchronize - - -For getting more debug message : - -.. code-block:: bash - - php app/console chill:ldap:synchronize -vvv - - - -You should run this command regularly (using crontab or -`systemd timer `_) -to synchronize ldap and database automatically. - - - diff --git a/docs/source/bundles/rst/main.rst b/docs/source/bundles/rst/main.rst deleted file mode 100644 index b3a990e31..000000000 --- a/docs/source/bundles/rst/main.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. 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: - -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. - -.. _main-bundle-macros: - -Macros -****** - -Address sticker -=============== - -Macro file - `ChillMainBundle:Address:macro.html.twig` -Macro name - `_render` -Macro envelope - `address`, instance of :class:`Chill\MainBundle\Entity\Address` - -When to use this macro ? - When you want to represent an address. -Example usage : - .. code-block:: html+jinja - - {% import 'ChillMainBundle:Address:macro.html.twig' as m %} - - {{ m._render(address) }} - diff --git a/docs/source/bundles/rst/person.rst b/docs/source/bundles/rst/person.rst deleted file mode 100644 index 69d3963c2..000000000 --- a/docs/source/bundles/rst/person.rst +++ /dev/null @@ -1,233 +0,0 @@ -.. 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: - -Person bundle -############# - -This bundle provides the ability to record people in the software. This bundle is required by other bundle. - -.. contents:: Table of content - :local: - -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 Depardieu) -* `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 `_. 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 Depardieu` or 'Jean Depagelles', but not 'Charline Depardieu' (missing 'Ge' in word). - -Configuration options -********************* - -Those options are available under `chill_person` key. - -Example of configuration: - -.. code-block:: yaml - - chill_person: - validation: - birthdate_not_after: P15Y - person_fields: - # note: visible is the default config. This key may be omitted if visible is chosen. - nationality: hidden - email: hidden - place_of_birth: visible - phonenumber: hidden - country_of_birth: hidden - marital_status: visible - spoken_languages: hidden - address: visible - -birthdate_not_after *string* - The period duration before today during which encoding birthdate is not possible. The period is a string matching the format of `ISO_8601`, which is also use to build `DateInterval classes `_. - - Example: `P1D`, `P18Y` - - Default value: `P1D` which means that birthdate before the current day (= yesterday) are allowed. - -person_fields *array* - This define the visibility of some fields. By default, all fields are visible, but you can choose to hide some of them. Available keys are : - - * `nationality` - * `country_of_birth` - * `place_of_birth` - * `phonenumber` - * `email` - * `marital_status` - * `spoken_languages` - * `address` - - Possibles values: `hidden` or `visible` (all other value will raise an Exception). - - Default value : `visible`, which means that all fields are visible. - - Example: - - .. code-block:: yaml - - chill_person: - person_fields: - nationality: hidden - email: hidden - phonenumber: hidden - -.. note:: - If all the field of a "box" are hidden, the whole box does not appears. Example: if the fields `phonenumber` and `email` are hidden, the title `Contact information` will be hidden in the UI. - -.. note:: - If you hide multiple fields, for a better integration you may want to override the template, for a better appeareance. See `the symfony documentation `_ about this feature. - -.. _person-bundle-macros: - -Macros -****** - -Sticker for a person -===================== - -Macro file - `ChillPersonBundle:Person:macro.html.twig` -Macro envelope - `render(p, withLink=false)` - - `p` is an instance of :class:`Chill\PersonBundle\Entity\Person` - - `withLink` :class:`boolean` -When to use this macro ? - When you want to represent a person. -Example usage : - .. code-block:: html+jinja - - {% import "ChillPersonBundle:Person:macro.html.twig" as person_ %} - - {{ person_.render(person, true) }} - -Layout events and delegated blocks -*********************************** - -`chill_block.person_post_vertical_menu` event -==================================================== - -This event is available to add content below of the vertical menu (on the right). - -The context is : - -- `person` : the current person which is rendered. Instance of :class:`Chill\PersonBundle\Entity\Person` - -Widgets -******* - -Add a list of person on homepage -================================ - -The bundle provide a way to add a list of accompanyied person on the homepage: - -.. code-block:: yaml - - chill_main: - widgets: - homepage: - - - order: 10 - widget_alias: person_list - person_list: - # customize the number of items - number_of_items: 20 - - # only active - only_active: true - - # you can add some filtering class, which will implements - # Chill\PersonBundle\PersonListWidget\PersonFilteringInterface - filtering_class: "\Hepc\HomepagePersonFiltering" - - # when the view is overriden, you can add some custom fields - # to the view - custom_fields: [school-2fb5440e-192c-11e6-b2fd-74d02b0c9b55] - -Commands -******** - - -`chill:person:move` -========================= - -.. code-block:: txt - - Usage: - chill:person:move [options] - - Options: - -f, --from=FROM The person id to delete, all associated data will be moved before - -t, --to=TO The person id which will received data - --dump-sql dump sql to stdout - --force execute sql instead of dumping it - -h, --help Display this help message - -q, --quiet Do not output any message - -V, --version Display this application version - --ansi Force ANSI output - --no-ansi Disable ANSI output - -n, --no-interaction Do not ask any interactive question - -e, --env=ENV The Environment name. [default: "dev"] - --no-debug Switches off debug mode. - -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug - - Help: - Move all the associated entities on a "from" person to a "to" person and remove the old person - -Move all the entities associated to a person onto another one, and remove the old person. - -.. warning:: - - Some entities are ignored and will be deleted: - - - the accompanying periods ; - - the data attached to a person entity: name, address, date of birth, etc. Thos should be merge before the move. - -It is advised to run first the command with the `dump-sql` option and, then, use the `force` option. - -The moving and suppression is executed inside a transaction, ensuring no data loss if the migration fails. - -.. note:: - - Using bash and awk, it is easy to use a TSV file (values separated by a tab, not a comma) to create move commands. Assuming our file is named `twins.tsv` and contains two columns: the first one with `from` ids, and the second one with `to` ids: - - .. code-block:: bash - - awk '{ print "php app/console chill:person:move --dump-sql --from " $1 " --to " $2;}' twins.tsv diff --git a/docs/source/bundles/rst/report.rst b/docs/source/bundles/rst/report.rst deleted file mode 100644 index d71caa0be..000000000 --- a/docs/source/bundles/rst/report.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. 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". - -.. _report-bundle: - -Report bundle -############# - -This bundle provides the ability to record report about people. We use custom fields to let user add fields to reports. - -.. contents:: Table of content - :local: - -.. todo:: - - The documentation about report is not writtend - -Concepts -======== - - -Search -====== - -Domain ------- - -* `@report` is the domain search for reports. - - -Arguments ---------- - -* `date` : The date of the report - -Default -------- - -The report's date is the default value. - -An error is thrown if an argument `date` and a default is used. diff --git a/docs/source/development/crud.md b/docs/source/development/crud.md index 4d0be080d..2796dff8e 100644 --- a/docs/source/development/crud.md +++ b/docs/source/development/crud.md @@ -94,7 +94,7 @@ The form: use Symfony\Component\Form\Extension\Core\Type\NumberType; /** -###### * + * */ class ClosingMotiveType extends AbstractType { diff --git a/docs/source/development/routing.md b/docs/source/development/routing.md index 15cddb9b3..2d635d039 100644 --- a/docs/source/development/routing.md +++ b/docs/source/development/routing.md @@ -8,11 +8,13 @@ A Chill bundle may rely on the Routing Loader defined in ChillMain. The loader will load `yml` or `xml` files. You simply have to add them into `chill_main` config +```yaml chill_main: # ... other stuff here routing: resources: - @ChillMyBundle/Resources/config/routing.yml +``` ### Load routes automatically diff --git a/docs/source/development/run-tests.md b/docs/source/development/run-tests.md index 077499bc9..4c2ee7e16 100644 --- a/docs/source/development/run-tests.md +++ b/docs/source/development/run-tests.md @@ -13,12 +13,14 @@ In reason of the Chill architecture, test should be runnable from the bundle's d This is the most convenient method for developer: run test for chill bundle from the main app. +```bash # run into a container `docker-compose exec --user $(id -u) php bash` # execute all tests suites `bin/phpunit` # ... or execute a single test `bin/phpunit vendor/chill-project/chill-bundles/src/Bundle/ChillMainBundle/Tests/path/to/FileTest.php` +``` You can also run tests in a single command: @@ -32,6 +34,7 @@ For ease, the app is cloned using a `git submodule`, which clone the main app in You may boostrap the tests for the chill bundle this way: +```bash # ensure to be located into the environment (provided by docker suits well) `docker-compose exec --user $(id -u) php bash` # go to chill subdirectory @@ -43,12 +46,13 @@ You may boostrap the tests for the chill bundle this way: `curl -sS https://getcomposer.org/installer | php` # run tests `bin/phpunit` +``` If you are on a fresh installation, you will need to migrate database schema. The path to the console tool must be adapted to the app. To load migration and add fixtures, one can execute the following commands: - ```bash - tests/app/bin/console doctrine:migrations:migrate - tests/app/bin/console doctrine:fixtures:load - ``` +```bash + tests/app/bin/console doctrine:migrations:migrate + tests/app/bin/console doctrine:fixtures:load +``` diff --git a/docs/source/installation/enable-collabora-for-dev.md b/docs/source/installation/enable-collabora-for-dev.md index ff1dbf6d9..8132b7aab 100644 --- a/docs/source/installation/enable-collabora-for-dev.md +++ b/docs/source/installation/enable-collabora-for-dev.md @@ -28,9 +28,9 @@ exists for your ngrok application ([See the CODE documentation: ](https://sdk.co ##### Configure your app -Set the [EDITOR_SERVER` variable to point to your collabora server, this should be done in your `.env.local` file. +Set the `EDITOR_SERVER` variable to point to your collabora server, this should be done in your `.env.local` file. -At this point, everything must be fine. In case of errors, watch the log from your collabora server, use the `profiler ](https://symfony.com/doc/current/profiler.html) +At this point, everything must be fine. In case of errors, watch the log from your collabora server, use the [profiler](https://symfony.com/doc/current/profiler.html) to debug the requests. In case of error while validating proof (you'll see those messages in the collabora's logs), you can temporarily disable @@ -61,16 +61,18 @@ Ensure that the proxy is running. ##### Create a certificate database for collabora -Collabora must validate your certificate generated by the symfony console. For that, you need `to create a NSS database ` +Collabora must validate your certificate generated by the symfony console. For that, you need [to create a NSS database](https://sdk.collaboraonline.com/docs/installation/Configuration.html#validating-digital-signatures) and configure collabora to use it. At first, export the certificate for symfony development. Use the graphical interface from your browser to get the certificate as a PEM file. +```bash # create your database in a custom directory `mkdir /path/to/your/directory` `certutil -N -d /path/to/your/directory` `cat /path/to/your/ca.crt | certutil -d . -A symfony -t -t C,P,C,u,w -a` +``` Launch CODE properly configured diff --git a/docs/source/installation/installation-development.md b/docs/source/installation/installation-development.md index 504795c7a..8c79bc8f5 100644 --- a/docs/source/installation/installation-development.md +++ b/docs/source/installation/installation-development.md @@ -4,64 +4,76 @@ You will need: -- [Composer ](https://getcomposer.org)_; -- [Symfony-cli tool ](https://symfony.com/download)_; -- [docker ](https://docs.docker.com/engine/install/)_ and - [docker-compose ](https://docs.docker.com/compose/)_ +- [Composer ](https://getcomposer.org); +- [Symfony-cli tool ](https://symfony.com/download); +- [docker ](https://docs.docker.com/engine/install/) and [docker-compose ](https://docs.docker.com/compose/) - node > 20 and yarn 1.22 ### First initialization 1. clone the repository and move to the cloned directory: - git clone https://gitlab.com/Chill-Projet/chill-bundles.git - cd chill-bundles + ```bash + git clone https://gitlab.com/Chill-Projet/chill-bundles.git + cd chill-bundles + ``` 2. install dependencies using composer - composer install + ```bash + composer install + ``` 3. Install and compile assets: - yarn install - yarn run encore production + ```bash + yarn install + yarn run encore production + ``` -**note** double-check that you have the node version > 20 using the -``node --version`` command. + **note** double-check that you have the node version > 20 using the `node --version` command. -1. configure your project: create a ``.env.local`` file at the root, and - add the admin password: +4. Configure your project: create a `.env.local` file at the root, and add the admin password: - # for this installation mode, the environment should always be "dev" - APP_ENV=dev - ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm - # note: if you copy-paste the line above, the password will be "admin". + **note** for this installation mode, the environment should always be "dev" + ``` + APP_ENV=dev + ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm + ``` + **note**: if you copy-paste the line above, the password will be "admin". -2. start the stack using ``docker compose up -d``, check the status of - the start with ``docker compose ps`` +5. Start the stack using `docker compose up -d`, check the status of the start with `docker compose ps` -3. configure all the necessary third-party tools +6. Configure all the necessary third-party tools. On the first start, it may last a bit longer. You can always check with `docker compose ps` -` # the first start, it may last some seconds, you can check with docker compose ps - # run migrations - symfony console doctrine:migrations:migrate - # setup messenger - symfony console messenger:setup-transports - # prepare some views - symfony console chill:db:sync-views - # generate jwt token, required for some api features (webdav access, ...) - symfony console lexik:jwt:generate-keypair` + ```bash + # Run migrations + symfony console doctrine:migrations:migrate -4. add some fixtures + # Setup messenger + symfony console messenger:setup-transports -This will truncate all the existing data of the database. But remember, -we are in dev mode! + # Prepare some views + symfony console chill:db:sync-views - symfony console doctrine:fixtures:load + # Generate jwt token, required for some api features (webdav access, ...) + symfony console lexik:jwt:generate-keypair + ``` -5. launch symfony dev-server +7. Add some fixtures - `symfony server:start -d` + This will truncate all the existing data of the database. But remember, + we are in dev mode! + + ```bash + symfony console doctrine:fixtures:load + ``` + +8. launch symfony dev-server + + ```bash + symfony server:start -d + ``` And visit the web page it suggests. You can log in with user `center a_social` and password `password`, or login `admin` with diff --git a/docs/source/installation/installation-production.md b/docs/source/installation/installation-production.md index 559106bad..b85deb7d4 100644 --- a/docs/source/installation/installation-production.md +++ b/docs/source/installation/installation-production.md @@ -19,40 +19,44 @@ Symfony apps ](https://symfony.com/doc/current/deployment.html). - `docker` with the plugin `compose`: https://docs.docker.com/engine/install/ and https://docs.docker.com/compose/install/ ### Initialize the project and it's dependencies - +```bash symfony new --version=5.4 my_chill_project cd my_chill_project +``` We strongly encourage you to initialize a git repository at this step, to track further changes. - +```bash # add the flex endpoints required for custom recipes `cat <<< "$(jq '.extra.symfony += {"endpoint": ["flex://defaults", "https://gitlab.com/api/v4/projects/57371968/repository/files/index.json/raw?ref=main"]}' composer.json)" > composer.json` # install chill and some dependencies `symfony composer require -W chill-project/chill-bundles ^3.7.1 champs-libres/wopi-lib dev-master@dev champs-libres/wopi-bundle dev-master@dev symfony/amqp-messenger` +``` We encourage you to accept the inclusion of the "Docker configuration from recipes": this is the documented way to run the database. You must also accept to configure recipes from the contrib repository, unless you want to configure the bundles manually). -` # fix some configuration +```bash + # fix some configuration ./post-install-chill.sh # populate the cache for the first time. This is necessary to dump some translation files, required for the asset compilation symfony console cache:clear # install node dependencies yarn install # and compile assets - yarn run encore production` + yarn run encore production +``` If you encounter this error during asset compilation ([yarn run encore production`) (repeated multiple times): - ```bash - [tsl] ERROR in /tmp/chill/v1/public/bundles/chillcalendar/types.ts(2,65) - TS2307: Cannot find module '../../../ChillMainBundle/Resources/public/types' or its corresponding type declarations. +```bash + [tsl] ERROR in /tmp/chill/v1/public/bundles/chillcalendar/types.ts(2,65) + TS2307: Cannot find module '../../../ChillMainBundle/Resources/public/types' or its corresponding type declarations. ``` run: - ```bash - rm -rf public/bundles/* +```bash + rm -rf public/bundles/* ``` Then restart the compilation of assets (```yarn run encore production```) @@ -76,8 +80,10 @@ The required variables are: ##### `ADMIN_PASSWORD` -You can generate a hashed and salted admin password using the command: `symfony console security:hash-password 'Symfony\Component\Security\Core\User\User'[.Then, -you can either: +You can generate a hashed and salted admin password using the command: +`symfony console security:hash-password 'Symfony\Component\Security\Core\User\User'` + +Then, you can either: - add this password to the `.env.local` file, you must escape the character `$`: if the generated password is `$2y$13$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm`, your `.env.local` file will be: @@ -98,14 +104,15 @@ You can set it to `null://null` if you do not plan to use sending SMS. OVHCLOUD_DSN=null://null -If you plan to do it, you can configure the notifier component `as described in the symfony documentation ](https://symfony.com/doc/current/notifier.html#notifier-sms-channel). +If you plan to do it, you can configure the notifier component `as described in the [symfony documentation](https://symfony.com/doc/current/notifier.html#notifier-sms-channel). -Some environment variables are available for the JWT authentication bundle in the [.env` file. +Some environment variables are available for the JWT authentication bundle in the `.env` file. ### Prepare database, messenger queue, and other configuration To continue the installation process, you will have to run migrations: +```bash # start databases and other services docker compose up -d # the first start, it may last some seconds, you can check with docker compose ps @@ -119,12 +126,13 @@ To continue the installation process, you will have to run migrations: symfony console chill:main:languages:populate # generate jwt token, required for some api features (webdav access, ...) symfony console lexik:jwt:generate-keypair +``` If you encounter this error: - ``` - No transport supports the given Messenger DSN. - ``` +``` +No transport supports the given Messenger DSN. +``` Please check that you installed the package `symfony/amqp-messenger`. @@ -133,14 +141,16 @@ To continue the installation process, you will have to run migrations: At this step, Chill will be ready to be served locally, but without any configuration. You can run the project locally using the `local symfony server ](https://symfony.com/doc/current/setup/symfony_server.html): +```bash # see the whole possibilities at https://symfony.com/doc/current/setup/symfony_server.html symfony server:start -d +``` If you need to test the instance with accounts and some basic configuration, please install the fixtures (see below). ## Add capabilities for dev -If you need to add custom bundles, you can develop them in the [src/` directory, like for any other symfony project. You +If you need to add custom bundles, you can develop them in the `src/` directory, like for any other symfony project. You can rely on the whole chill framework, meaning there is no need to add them to the original `chill-bundles`. You will require some bundles to have the following development tools: @@ -150,23 +160,28 @@ You will require some bundles to have the following development tools: ### Install fixtures +```bash # generate fixtures for chill symfony composer require --dev doctrine/doctrine-fixtures-bundle nelmio/alice # now, you can generate fixtures (this will reset your database) symfony console doctrine:fixtures:load +``` This will generate user accounts, centers, and some basic configuration. -The accounts created are: `center a_social`, `center b_social`, `center a_direction`, ... The full list is -visible in the "users" table: `docker compose exec database psql -U app -c "SELECT username FROM users"`. +The accounts created are: `center a_social`, `center b_social`, `center a_direction`, ... + +The full list is visible in the "users" table: `docker compose exec database psql -U app -c "SELECT username FROM users"`. The password is always `password`. - The fixtures are not fully functional. See the `corresponding issue ](https://gitlab.com/Chill-Projet/chill-bundles/-/issues/280). +The fixtures are not fully functional. See the `corresponding issue ](https://gitlab.com/Chill-Projet/chill-bundles/-/issues/280). ### Add web profiler and debugger +```bash symfony composer require --dev symfony/web-profiler-bundle symfony/debug-bundle +``` ### Working on chill bundles @@ -179,6 +194,7 @@ You will have to download chill-bundles as a git repository (and not as an archi In your `composer.json` file, add these lines: +```bash { "config": { + "preferred-install": { @@ -186,6 +202,7 @@ In your `composer.json` file, add these lines: "*": "dist" + } } +``` Then, run `symfony composer reinstall chill-project/chill-bundles` to re-install the package from source. @@ -199,8 +216,10 @@ In order to update your app, you must update dependencies: After each update, you must update your database schema: +```bash symfony console doctrine:migrations:migrate symfony console chill:db:sync-views +``` ## Commit and share your project @@ -220,25 +239,29 @@ When another developer clones your project, they will have to: run those commands: -` # for production (or in dev, when you don't need to work on your assets and need some speed) +```bash + # for production (or in dev, when you don't need to work on your assets and need some speed) yarn run encore production # in dev, when you want to reload the assets on each changes yarn run encore dev --watch` +``` ### How to execute the console ? -` # start the console with all required variables +```bash + # start the console with all required variables symfony console # you can add your command after that: - symfony console list` + symfony console list +``` ### How to generate documents -Documents are generated asynchronously by `"consuming messages" ](https://symfony.com/doc/current/messenger.html#consuming-messages-running-the-worker). +Documents are generated asynchronously by [consuming messages](https://symfony.com/doc/current/messenger.html#consuming-messages-running-the-worker). You must generate them using a dedicated process: - symfony console messenger:consume async priority + `symfony console messenger:consume async priority` To avoid memory issues, we encourage you to also use the `--limit` parameter of the command. diff --git a/docs/source/installation/msgraph-configure.md b/docs/source/installation/msgraph-configure.md index 315aa4080..e6d6003a9 100644 --- a/docs/source/installation/msgraph-configure.md +++ b/docs/source/installation/msgraph-configure.md @@ -25,7 +25,11 @@ Go to the "Single sign-on" ("Authentication unique") section. Choose "SAML" as a 2. The url response must be your Chill's URL appended by `/saml/acs` 3. The only used attributes is `emailaddress`, which must match the user's email one. -You must download the certificate, as base64. The format for the download is `cer`: you will remove the first and last line (the ones with `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`), and remove all the return line. The final result should be something as `MIIAbcdef...XyZA=`. +You must download the certificate, as base64. The format for the download is `cer`: you will remove the first and last line + +(the ones with `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`), + +and remove all the return line. The final result should be something as `MIIAbcdef...XyZA=`. This certificat will be your `SAML_IDP_X509_CERT` variable. @@ -35,10 +39,12 @@ Remember to provider user's access to your app, using the "Utilisateurs et group You must now have gathered all the required variables for SSO: +```bash SAML_BASE_URL=https://test.chill.be # must be SAML_ENTITY_ID=https://test.chill.be # must match the one entered SAML_IDP_APP_UUID=42XXXXXX-xxxx-xxxx-xxxx-xxxxxxxxxxxx SAML_IDP_X509_CERT: MIIC...E8u3bk # truncated +``` ###### Configure chill app @@ -212,21 +218,20 @@ The sync daemon must have write access: At this step, you might choose to accept those permissions for all users or let them do it by yourself. -Grab your client id: -This will be your `OAUTH_AZURE_CLIENT_ID` variable. +Grab your client id: This will be your `OAUTH_AZURE_CLIENT_ID` variable. -Generate a secret: - -This will be your `OAUTH_AZURE_CLIENT_SECRET` variable. +Generate a secret: This will be your `OAUTH_AZURE_CLIENT_SECRET` variable. And get you azure's tenant id, which is the same as the `SAML_IDP_APP_UUID` (see above). Your variables will be: +```bash OAUTH_AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx OAUTH_AZURE_CLIENT_TENANT=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx OAUTH_AZURE_CLIENT_SECRET: 3-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` Then, configure chill: diff --git a/docs/source/installation/prod-calendar-sms-sending.md b/docs/source/installation/prod-calendar-sms-sending.md index 383c83fac..2987fa56b 100644 --- a/docs/source/installation/prod-calendar-sms-sending.md +++ b/docs/source/installation/prod-calendar-sms-sending.md @@ -16,6 +16,6 @@ To configure this, add this config variable in your environment: SHORT_MESSAGE_DSN=ovh://applicationKey:applicationSecret@endpoint?consumerKey=xxxx&sender=yyyy&service_name=zzzz ``` -To generate the application key, secret, and consumerKey, refers to their `documentation ](https://docs.ovh.com/gb/en/api/first-steps-with-ovh-api/). +To generate the application key, secret, and consumerKey, refers to their [documentation ](https://docs.ovh.com/gb/en/api/first-steps-with-ovh-api/). Before to be able to send your first sms, you must enable your account, grab some credits, and configure a sender. The service_name is an internal configuration generated by OVH.