A dynamic family
================

.. objectives:: Objectives

   In this section we will learn how to create a dynamically created family.

.. prerequisites:: Reminder

   We handled the HTTPS mode in the previous section. But there's more.
   Let's have a look at the firefox's configuration page:

.. image:: images/soksv5.png

In fact we shall not only handle the HTTPS configuration but the SOCKS configuration too.
And we can see that these two group of variables are very similar: 
they both have two variables, that is a host and a port.

Creating a generic family
----------------------------

There are two proxies that are to be configured : 

- the HTTP proxy
- the SOCKS proxy

It's not the place here to describe what the HTTP and SOCKS protocols are. 
The interesting point is that : 

- they are similar in terms of our firefox's configuration
- we can use a generic family declaration mode in this use case (we call this genericity "dynamic creation")

Instead of doing something like this: 

.. code-block:: yaml

   https_proxy:
     description: HTTPS Proxy
     ...

     address:
       description: HTTPS address
       ...

     port:
       description: HTTPS Port
       ...

And this:


.. code-block:: yaml

   sock_proxy:
     description: SOCKS Proxy
     ...

     address:
       description: SOCKS address
       ...

     port:
       description: SOCKS Port
       ...

With Rougail we have the ability to say this:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_037/firefox/20-manual.yml
   :language: yaml
   :caption: firefox/20-proxy.yml

What is an identifier?
-------------------------

We define what we call an :term:`identifier`, which is a local variable, used only for creating 
multiple families at one time (that is, being more generic in our declaration style). 
This is this syntax that allows the declaration of multiple families at one time:

.. code-block:: yaml

  "{{ identifier }}_proxy":
    description: "{{ identifier }} Proxy"
    dynamic:
      - HTTPS
      - SOCKS

This identifier is a parameter that enables us to create two families named `https_proxy` and `socks_proxy`.

.. note:: The declaration syntax is a :term:`jinja` templating syntax, which is commonly used 
          in the python coding field.

So yes, we have gained in genericity but we have lost in readability, you would say.
But we haven't just been generic. We now have the ability to create conditional hidden family
(and not only conditionnal hidden variables like we did earlier).

A conditional hidden family with jinja
------------------------------------------