=====================
Clients Custom Fields
=====================

.. index:: client custom fields

| Fleio supports custom Client fields in order to accommodate various requirements.
| A Client in Fleio has the default fields which can't be modified, however new fields
| can be added and required based on different conditions.

To setup a new custom field, we must set the ``CLIENT_CUSTOM_FIELDS`` variable in the
settings.py file.

Let's start with an example:

.. code-block:: python

    EU_COUNTRIES = ['AL', 'AD', 'AT', 'BY']  # list with a few EU countries codes

    CLIENT_CUSTOM_FIELDS = {'vat_id': {'label': 'VAT ID Field',
                                       'required': {'country': {'in': EU_COUNTRIES}},
                                       'type': 'text'}
                            }

| Each custom field has a name, given by the first key in CLIENT_CUSTOM_FIELDS.
| In our case the field name is ``vat_id``.
| Our ``vat_id`` field has a few settings, let's look at each of them and some additional settings:

* **name**: A string without spaces with the same restrictions as python variables.
    A field is ignored is it's name is the same as an existing client attribute or is invalid.
* **label**: A string used for display purposes.
* **required**: A boolean value, a rule or a callable.
    | Defaults to ``False``
    | In our case, we require this field only if the client attribute ``country`` is in ``EU_COUNTRIES``
* **optional**: A boolean value, a rule or a callable
    | Defaults to ``False``
    | Note that is both `required` and `optional` are False, the field will be ignored.
* **choices**: Used for ``select`` field types
    | A list of strings or tuples (ex: [('1', 'One'), ('2', 'Two')...])
    | The first element in a tuple is the actual value and the second is the display name
* **type**: the type of this field, mainly for frontend display.
    | Defaults to ``text`` if not set
    | Supported field types include: **'text', 'select', 'check'**

The **required** rule
=====================

.. code-block:: python


    'required': True  # always required
    'required': some_function()  # returns a boolean or a rule value like below
    'required': {'city': {'exists': True}}  # required if client.city was set
    'required': {'state': {'null': True}}  # required if client.state is None/null
    'required': {'country': {'nin': ['AB', 'CD']}}  # required if client.country is not in the list
    'required': {'<client_field>': {'<operator>': '<operand>'}}  # generic definition of a full rule

The **optional** rule
=====================
The ``optional`` rule is the same as the ``required`` rule above.
Do note that not setting or setting both `required` and `optional` to False will set the field to be ignored.

Supported rule operations include: **in, nin, eq, ne, exists, null**

Custom fields will be used for Invoices, client messages templates and other client related tasks

With the 2019.09.0 release we have added a new option regarding the client creation process:

* do not require state for some countries

In order to use this feature you will have to add a new dict in the fleio settings.py file:

.. code-block:: python

    STATE_REQUIRED_FOR_COUNTRY = {
    'FR': False,
    }

In the above case, the state will no longer be required for France.