Chill-project/chill-bundles
6
0
Fork 0
mirror of https://gitlab.com/Chill-Projet/chill-bundles.git synced 2025-08-20 14:43:49 +00:00
Code Issues Actions Projects Releases Wiki Activity

prepare for merging doc into mono-repository

Browse Source
This commit is contained in:
Julien Fastré
2021-03-25 17:06:29 +01:00
parent daec8c892c
commit d9759024ef
68 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,71 @@
.. 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) }}

441
docs/source/bundles/custom-fields.rst Normal file
View File

@@ -0,0 +1,441 @@
.. 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. <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.
.. 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 <http://symfony.com/doc/current/cookbook/bundles/prepend_extension.html>`_
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

29
docs/source/bundles/event.rst Normal file
View File

@@ -0,0 +1,29 @@
.. 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.

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

@@ -0,0 +1,49 @@
.. 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) }}

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

@@ -0,0 +1,29 @@
.. 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>`_.

204
docs/source/bundles/ldap.rst Normal file
View File

@@ -0,0 +1,204 @@
.. 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 :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
#. 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)
#. if a user exists which is already binded with the :code:`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 :code:`enabled=false`: they are not allowed to login.
Installation
************
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
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 :code:`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 <https://www.freedesktop.org/software/systemd/man/systemd.timer.html#>`_)
to synchronize ldap and database automatically.

49
docs/source/bundles/main.rst Normal file
View File

@@ -0,0 +1,49 @@
.. 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
:code:`_render`
Macro envelope
:code:`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) }}

233
docs/source/bundles/person.rst Normal file
View File

@@ -0,0 +1,233 @@
.. 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 <http://www.iso.org/iso/fr/home/standards/country_codes.htm>`_. Example : `nationality:FR`.
Default
=======
The default search is performed on firstname and/or lastname. Both are concatened before search. If values are separated by spaces, the clause `AND` is used : the search `dep ge` will match 'Gérard 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 <http://php.net/manual/en/dateinterval.construct.php>`_.
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 <http://symfony.com/doc/current/book/templating.html#overriding-bundle-templates>`_ about this feature.
.. _person-bundle-macros:
Macros
******
Sticker for a person
=====================
Macro file
`ChillPersonBundle:Person:macro.html.twig`
Macro envelope
:code:`render(p, withLink=false)`
:code:`p` is an instance of :class:`Chill\PersonBundle\Entity\Person`
:code:`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
***********************************
:code:`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 :
- :code:`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
********
:code:`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 :code:`dump-sql` option and, then, use the :code:`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 :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

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

@@ -0,0 +1,46 @@
.. 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.