# Person bundle

This bundle provides the ability to record people in the software. This bundle is required by other bundle.

###### Entities provided

   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:

```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:

```yaml
      chill_person:
         person_fields:
            nationality: hidden
            email: hidden
            phonenumber: hidden
```

   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.

   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
   `render(p, withLink=false)`

   `p` is an instance of `Chill\PersonBundle\Entity\Person`

   `withLink`: `boolean`
When to use this macro ?
   When you want to represent a person.
Example usage :
   ```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 `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:

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

	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.

  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.

  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:

  ```bash
    awk '{ print "php app/console chill:person:move --dump-sql --from " $1 " --to " $2;}' twins.tsv
```
