The families ============= Synopsis --------- .. glossary:: family subfamily A family (or a subfamily) is simply a collection of variables that refer to the same business model category. It's just a variables container. Think of it as a container as well as a namespace. .. attention:: A family without a subfamily or subvariable will be automatically deleted. Naming --------- It is with its name that we will be able to interact with the family. .. seealso:: Have a look at the :ref:`family naming convention ` Shorthand declaration ---------------------------- Shorthand declaration is a way to declare a family in a single line. To create a family, just add a key with it's name and variables as values. Here is a simple example: .. code-block:: yaml %YAML 1.2 --- version: 1.1 my_family: variable: ... By default, the description of the variable is the family name. It's a best practice to description a family. Just add comment in same line of name, this comment is use as description. .. code-block:: yaml %YAML 1.2 --- version: 1.1 my_family: # This is a great family variable: ... But in shorthand notation, you can only define family name and description. .. attention:: Any other parameters will be considered as a variable. Do not use shorthand in this case. Parameters --------------- .. list-table:: :widths: 15 45 :header-rows: 1 * - Parameter - Comments * - **description**, **_description** `string` - Description of the family. User information to understand the usefulness of the family. .. seealso:: tutorial with a real world sample :ref:`description parameter ` * - **help**, **_help** `string` - Additional help associated with the family. .. seealso:: tutorial with a real world sample :ref:`help parameter ` (the tutorial focuses on variable, but the principle is the same for a family) * - **mode**, **_mode** `string` - Family mode. The mode is a way of classifying the importance, the level of expertise required, or the access rights to a family. This parameter allows you to define the family mode, and also the default mode for variables or families included in this family. .. attention:: Mode is not configured by default. You have to define mode level before use this parameter. **Default value**: The default mode of a family is the smallest mode of the parent families, child variables, or child families that are contained in that family. .. seealso:: tutorial with a real world sample :ref:`mode parameter ` (the tutorial focuses on variable, but the principle is the same for a family) * - **type**, **_type** `string` - possible values: - `family` (**default value**) - `dynamic` - `leadership` * - **hidden**, **_hidden** `boolean` or :term:`calculation` - Invisible family. Enables us to *hide* a family as well as the variables or families included in this family. This means that the family will no longer be visible in `read-write` mode, but only for calculations or in `read-only` mode. **Default value**: `false` .. seealso:: tutorial with a real world sample :ref:`hidden parameter ` * - **disabled**, **_disabled** `boolean` or :term:`calculation` - Disabled family. Allows us to *deactivate* a family as well as the variables or families included in this family. This means that the family will no longer be visible to the user but also to a :term:`calculation`. **Default value**: `false` .. seealso:: tutorial with a real world sample :ref:`disabled parameter ` * - **dynamic**, **_dynamic** :term:`calculation` or a list of :term:`calculation` or `string` - Dynamic identifiers. .. important:: This parameter is only available for dynamically built family. See the explanations about this below. * - **redefine** `boolean` - It is possible to define a family in one :term:`structure file` and change its behavior in a second :term:`structure file`. In this case you must explicitly redefine the family. **Default value**: `false` * - **exists** `boolean` - This parameter does two things: - creates a family if it does not exist in another :term:`structure file` (otherwise do nothing), in this case the value of the parameter must be `true` - in conjunction with the `redefine` parameter set to `true`, only modifies the behavior if it is pre-existing, in which case the parameter's value must be `false`. **Default value**: `null` .. note:: If a subfamily or a subvariable already has the name of a parameter it is possible to use the "_" name. You can have a look at the tutorial with a real world sample :ref:`of parameter with "_" `. A family --------- Here is a simple example: .. code-block:: yaml %YAML 1.2 --- version: 1.1 my_family: description: This is a great family help: This family is great because we have great variables inside variable: ... .. seealso:: You can have a look at the tutorial with a real world sample: - :ref:`family ` - :ref:`help parameter ` (the tutorial focuses on variable, but the principle is the same for a family) A dynamically built family ----------------------------- To create a family dynamically, you must create a fictitious family linked to a list of uniq identifiers. This list could be hard coded or resulting from a calculation In this case if the result of calculation were to evolve, new dynamic families will appear or disappear. The name of this family is particular. You have to add `{{ identifier }}` string inside. It will be replace by each identifiers. Here is an simple example: .. code-block:: yaml %YAML 1.2 --- version: 1.1 my_{{ identifier }}_family: description: 'A family for {{ identifier }}' dynamic: - one thing - another variable: description: 'A variable for {{ identifier }}' ... This will dynamically create two families: - "my_one_thing_family" - "my_another_family" .. seealso:: You can have a look at the tutorial with a real world sample :ref:`dynamically built family ` Similar object sequence ------------------------- A family with `type` set to `leadership` is a sequence of similar object. Let's start the explanation with a concrete example: .. code-block:: yaml %YAML 1.2 --- version: 1.1 accounts: description: All accounts type: leadership login: description: Account login type: unix_user secret: description: Account secret type: secret ... What is expected, it's something like: .. code-block:: yaml --- accounts: - login: foo secret: 0hM%G0dW4a7ASecr3t - login: bar secret: NotGoodSecret It's what we call a sequence of similar object. .. attention:: A sequence cannot contain other families. .. seealso:: You can have a look at the tutorial with a real world sample :ref:`similar object sequence ` A custom type family ---------------------- In short, a custom type is nothing more than a kind of a template for a family. Define a custom type family is much like defining families. This custom type family can be used as many times as desired and customized as you wish. .. seealso:: You can have a look at the tutorial with a real world sample :ref:`family custom type `