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

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) }}