Chill-project/chill-bundles
6
0
Fork 0
mirror of https://gitlab.com/Chill-Projet/chill-bundles.git synced 2025-12-07 02:43:56 +00:00
Code Issues Actions Projects Releases Wiki Activity

Resolve "Documentation: utiliser mkdocs (avec l'extension mkdocs-material) plutôt que Sphinx"

Browse Source
This commit is contained in:
LenaertsJ
2025-12-05 11:33:14 +00:00
committed by Julien Fastré
parent b221ad1621
commit 7ad24bef8a
87 changed files with 3500 additions and 4086 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/source/bundles/activity.md Normal file
View File

@@ -0,0 +1,49 @@
# Activity bundle
This bundle provides the ability to record people in the software. This bundle is required by other bundle.
###### Entities provided
Describe the entities provided.
###### Configuration options
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.
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.
###### 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 :
```jinja
{% import 'ChillActivityBundle:ActivityReason:macro.html.twig' as m %}
{{ m.reason(r) }}
```

71
docs/source/bundles/activity.rst
View File

@@ -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 :code:`label` and a :code:`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
:code:`reason(r)`
:code:`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) }}

197
docs/source/bundles/custom-fields.rst → docs/source/bundles/custom-fields.md
View File

@@ -1,15 +1,4 @@
.. 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
====================
## Custom fields bundle
This bundle provides the ability to add custom fields to existing entities.
@@ -17,79 +6,63 @@ 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.
.. seealso::
The full specification discussed [here](https://redmine.champs-libres.coop/issues/239)
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>`_
[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.
.. contents:: Table of contents
:depth: 4
:local:
Custom Fields concepts
----------------------
### 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.
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 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).
.. 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
--------------------------------
### 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### Create a json field on your entity
Declare a json field in your database :
.. code-block:: yaml
```bash
Chill\CustomFieldsBundle\Entity\BlopEntity:
type: entity
# ...
fields:
cFData:
type: json_array
```
Create the field accordingly in the class logic :
.. code-block:: php
```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
@@ -100,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
@@ -111,9 +84,9 @@ Create the field accordingly in the class logic :
{
return $this->cFData;
}
Declare your customizable entity in configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
```
##### Declare your customizable entity in configuration
This step is necessary to allow user to create custom fields group associated with this entity.
@@ -130,26 +103,25 @@ This method is discouraged but explained first as it helps to undersand the reco
Add those file under `chill_custom_fields` section :
.. code-block:: yaml
```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 :
.. code-block:: php
Example here :
```php
class ChillYourBundleExtension extends Extension implements PrependExtensionInterface
{
/**
@@ -163,48 +135,44 @@ 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
.. seealso::
`How to simplify configuration of multiple bundles <http://symfony.com/doc/current/cookbook/bundles/prepend_extension.html>`_
`How to simplify configuration of multiple bundles ](http://symfony.com/doc/current/cookbook/bundles/prepend_extension.html)
A cookbook page about prepending configuration.
Adding options to your custom fields groups
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 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
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 :
.. code-block:: php
In the `PrependExtensionInterface::prepend` function, the options key will be added in the configuration definition :
```php
class ChillYourBundleExtension extends Extension implements PrependExtensionInterface
{
/**
@@ -218,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 ] ]
@@ -231,16 +199,15 @@ 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 :
```
.. code-block:: php
**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
{
/**
*
*
###### *
* @param ContainerBuilder $container
*/
public function prepend(ContainerBuilder $container)
@@ -251,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
@@ -271,14 +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
-------------------------------------------------------------
### 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.
Each custom field can be `active` or not. Only `active` custom fields has to be dislayed.
For rendering custom fields, two function are available :
@@ -290,8 +256,7 @@ 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
^^^^^^^^^^^^^^^^^^^^^^^^
##### chill_custom_field_label
The signature is :
@@ -300,29 +265,23 @@ The signature is :
Examples
.. code-block:: jinja
{{ chill_custom_field_label(customField) }}
chill_custom_field_widget
^^^^^^^^^^^^^^^^^^^^^^^^^
##### chill_custom_field_widget
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:
.. code-block:: jinja
```bash
{{ chill_custom_field_widget(entity.customFields, customField) }}
```
chill_custom_field_is_empty
^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### chill_custom_field_is_empty
The signature is :
@@ -331,13 +290,9 @@ The signature is :
Examples :
.. code-block:: jinja
{%- if chill_custom_field_is_empty(cFData, customField) == false -%}
chill_custom_fields_group_widget
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### chill_custom_fields_group_widget
This function only display custom fields that are `active`.
@@ -346,19 +301,17 @@ The signature is :
* array **$fields** the array raw, as stored in the db
* CustomFieldsGroup **$customFieldsGroup** the custom field group to render
.. code-block:: jinja
```bash
{{ chill_custom_fields_group_widget(entity.cFData, entity.customFieldsGroup) }}
```
Custom Fields's form
--------------------
### 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
Example :
```php
namespace Chill\ReportBundle\Form;
use Symfony\Component\Form\AbstractType;
@@ -377,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
*/
@@ -413,29 +366,25 @@ Example :
return 'chill_reportbundle_report';
}
}
```
Available configuration
------------------------
### Available configuration
Those options are available in the configuration, under the `chill_custom_field` key.
Example :
.. code-block:: yaml
```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::
### Glossary
custom fields group
A group of custom fields

16
docs/source/bundles/event.rst → docs/source/bundles/event.md
View File

@@ -1,24 +1,18 @@
.. Copyright (C) 2016 Champs Libres Cooperative SCRLFS
Permission is granted to copy, distribute and/or modify this document
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
Event bundle
############
Template & Menu
===============
## 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
----------------------------------
### ChillEventBundle::layout.html.twig
This layout extends `ChillMainBundle::layoutWithVerticalMenu.html.twig` and add the menu `event`
@@ -26,4 +20,4 @@ It proposes a new block :
* event_content
* where to display content relative to the event.
* where to display content relative to the event.

33
docs/source/bundles/group.md Normal file
View File

@@ -0,0 +1,33 @@
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
Allow to group people in a group. This group may be a family, an activity group, ...
###### Entities
###### 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 :
```jinja
{% import 'ChillGroupBundle:Group:macro.html.twig' as m %}
{{ m._render(g) }}
```

49
docs/source/bundles/group.rst
View File

@@ -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
:code:`_render`
Macro envelope
:code:`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) }}

23
docs/source/bundles/index.md Normal file
View File

@@ -0,0 +1,23 @@
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.
- [Main bundle](main.md)
- [Custom Fields bundle](custom-fields.md)
- [Person bundle](person.md)
- [Report bundle](report.md)
- [Activity bundle](activity.md)
- [Group bundle](group.md)
- [Event bundle](event.md)
- [Ldap bundle (synchronisation between ldap and database)](ldap.md)
### 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).

29
docs/source/bundles/index.rst
View File

@@ -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 <main.rst>
Custom Fields bundle <custom-fields.rst>
Person bundle <person.rst>
Report bundle <report.rst>
Activity bundle <activity.rst>
Group bundle <group.rst>
Event bundle <event.rst>
Ldap bundle (synchronisation between ldap and database) <ldap.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>`_.

109
docs/source/bundles/ldap.rst → docs/source/bundles/ldap.md
View File

@@ -1,94 +1,70 @@
.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS
Permission is granted to copy, distribute and/or modify this document
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
###########
# 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
*******************
###### 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
Entities provided
*****************
This bundle provides only one entity : :class:[Chill\\LdapBundle\\Entity\\UserLdapBinding`
This bundle provides only one entity : :class:`Chill\\LdapBundle\\Entity\\UserLdapBinding`
###### How the synchronizer works ?
How the synchronizer works ?
****************************
#. The synchronizer performs a query on :code:`dn` and :code:`query` defined in the :ref:`configuration <configuration>`.
#. For each entry returned by the query, it looks if the :code:`dn` exists in the database
#. The synchronizer performs a query on `dn` and `query` defined in the [configuration ](configuration.md).
#. 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 :code:`username_attr`, and bind it with the :code:`dn` if it exists.
#. else, a user is created with username defined by :code:`username_attr` (if the ldap contains more than one attribute, the first attribute returned is used)
#. 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 :code:`dn`, the entry is ignored.
#. 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.
#. 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 :code:`enabled=false`: they are not allowed to login.
#. If they exists, those user are set to `enabled=false`: they are not allowed to login.
Installation
************
###### Installation
This bundle requires :
This bundle requires :
- PHP LDAP ext
- :code:`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
- `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
In your composer.json, for stable version :
"require": {
// .. other dependencies
// .. other dependencies
"symfony/ldap" : "~3.1",
"chill-project/ldap": "~1.0"
}
And for dev version :
.. code-block:: json
"require": {
// .. other dependencies
// .. other dependencies
"symfony/ldap" : "~3.1",
"chill-project/ldap": "dev-master@dev"
}
###### Configuration
.. _configuration:
Configuration
**************
Configuration of the bundle
============================
.. code-block:: yaml
## Configuration of the bundle
# Default configuration for extension with alias: "chill_ldap"
chill_ldap:
@@ -125,10 +101,7 @@ Configuration of the bundle
# The attribute which will provide username (=login)
username_attr: cn
Example :
.. code-block:: yaml
Example :
chill_ldap:
server:
@@ -140,16 +113,12 @@ Example :
dn: dc=champs-libres,dc=coop
query: "(&(objectClass=inetOrgPerson)(userPassword=*))"
Configuration of the security part of chill
============================================
## 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
Example of a configuration :
# in app/config/security.yml
@@ -168,37 +137,23 @@ Example of a configuration :
# 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,
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 :code:`form_login` entry and all his options.
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
Command and crontab
===================
Synchronize the database :
.. code-block:: bash
Synchronize the database :
php app/console chill:ldap:synchronize
For getting more debug message :
.. code-block:: bash
For getting more debug message :
php app/console chill:ldap:synchronize -vvv
You should run this command regularly (using crontab or
`systemd timer <https://www.freedesktop.org/software/systemd/man/systemd.timer.html#>`_)
You should run this command regularly (using crontab or
`systemd timer ](https://www.freedesktop.org/software/systemd/man/systemd.timer.html#))
to synchronize ldap and database automatically.

33
docs/source/bundles/main.rst → docs/source/bundles/main.md
View File

@@ -1,15 +1,12 @@
.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS
Permission is granted to copy, distribute and/or modify this document
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
###########
# Main bundle
This bundle is **required** for running Chill.
@@ -18,32 +15,24 @@ This bundle provide :
* Access control model (users, groups, and all concepts)
* ...
.. warning::
this section is incomplete.
.. _main-bundle-macros:
###### Macros
Macros
******
Address sticker
===============
## Address sticker
Macro file
`ChillMainBundle:Address:macro.html.twig`
Macro name
:code:`_render`
`_render`
Macro envelope
:code:`address`, instance of :class:`Chill\MainBundle\Entity\Address`
`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) }}
```jinja
{% import 'ChillMainBundle:Address:macro.html.twig' as m %}
{{ m._render(address) }}
```

138
docs/source/bundles/person.rst → docs/source/bundles/person.md
View File

@@ -1,65 +1,41 @@
.. 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
#############
# 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::
###### Entities provided
describe entities provided by person bundle
Search terms
************
The class `Chill\PersonBundle\Search\PersonSearch` provide the search module.
Domain
======
###### 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
=========
## 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 <http://www.iso.org/iso/fr/home/standards/country_codes.htm>`_. Example : `nationality:FR`.
* `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
=======
## 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
*********************
###### Configuration options
Those options are available under `chill_person` key.
Example of configuration:
.. code-block:: yaml
```yaml
chill_person:
validation:
birthdate_not_after: P15Y
@@ -73,17 +49,18 @@ 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>`_.
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).
Example: `P1D`, `P18Y`
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 :
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`
@@ -97,73 +74,62 @@ person_fields *array*
Default value : `visible`, which means that all fields are visible.
Example:
.. code-block:: yaml
Example:
```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 <http://symfony.com/doc/current/book/templating.html#overriding-bundle-templates>`_ about this feature.
If you hide multiple fields, for a better integration you may want to override the template, for a better appeareance. See `the symfony documentation ](http://symfony.com/doc/current/book/templating.html#overriding-bundle-templates) about this feature.
.. _person-bundle-macros:
###### Macros
Macros
******
Sticker for a person
=====================
## Sticker for a person
Macro file
`ChillPersonBundle:Person:macro.html.twig`
Macro envelope
:code:`render(p, withLink=false)`
`render(p, withLink=false)`
:code:`p` is an instance of :class:`Chill\PersonBundle\Entity\Person`
`p` is an instance of `Chill\PersonBundle\Entity\Person`
:code:`withLink` :class:`boolean`
`withLink`: `boolean`
When to use this macro ?
When you want to represent a person.
Example usage :
.. code-block:: html+jinja
```jinja
{% import "ChillPersonBundle:Person:macro.html.twig" as person_ %}
{% import "ChillPersonBundle:Person:macro.html.twig" as person_ %}
{{ person_.render(person, true) }}
```
{{ person_.render(person, true) }}
###### Layout events and delegated blocks
Layout events and delegated blocks
***********************************
:code:`chill_block.person_post_vertical_menu` event
====================================================
## `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 :
The context is :
- :code:`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
*******
###### Widgets
Add a list of person on homepage
================================
## 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
```yaml
chill_main:
widgets:
homepage:
-
homepage:
-
order: 10
widget_alias: person_list
person_list:
@@ -180,15 +146,11 @@ 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
********
```
###### Commands
:code:`chill:person:move`
=========================
.. code-block:: txt
## `chill:person:move`
Usage:
chill:person:move [options]
@@ -213,21 +175,17 @@ Commands
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:
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 :code:`dump-sql` option and, then, use the :code:`force` option.
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:
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 :code:`twins.tsv` and contains two columns: the first one with :code:`from` ids, and the second one with :code:`to` ids:
.. code-block:: bash
awk '{ print "php app/console chill:person:move --dump-sql --from " $1 " --to " $2;}' twins.tsv
```bash
awk '{ print "php app/console chill:person:move --dump-sql --from " $1 " --to " $2;}' twins.tsv
```

23
docs/source/bundles/report.md Normal file
View File

@@ -0,0 +1,23 @@
# Report bundle
This bundle provides the ability to record report about people. We use custom fields to let user add fields to reports.
The documentation about report is not written
## 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.

46
docs/source/bundles/report.rst
View File

@@ -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.