264 lines
6.5 KiB
ReStructuredText
264 lines
6.5 KiB
ReStructuredText
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 <namingconvention>`
|
|
|
|
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.
|
|
|
|
* - help, _help
|
|
|
|
`string`
|
|
- Additional help associated with the family.
|
|
|
|
.. seealso:: tutorial with a real world sample :ref:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
|
|
|
|
* - mode, _mode
|
|
|
|
`string`
|
|
- Family mode.
|
|
|
|
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.
|
|
|
|
This mode also allows you to define the default mode for variables or families included in this family.
|
|
|
|
.. seealso:: tutorial with a real world sample :ref:`mode parameter <tutorial/mode>` (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 `calculation`
|
|
- Invisible family.
|
|
|
|
Allows you 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.
|
|
|
|
The default value is `false`.
|
|
|
|
.. seealso:: tutorial with a real world sample :ref:`hidden parameter <tutorial/properties>`
|
|
|
|
* - disabled, _disabled
|
|
|
|
`boolean` or `calculation`
|
|
|
|
- Disabled family.
|
|
|
|
Allows you 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`.
|
|
|
|
The default value is `false`.
|
|
|
|
.. seealso:: tutorial with a real world sample :ref:`disabled parameter <tutorial/properties>`
|
|
|
|
* - dynamic, _dynamic
|
|
|
|
`calculation` or a list of `calculation` or `string`
|
|
|
|
- Dynamic identifiers.
|
|
|
|
.. important:: this parameter is only available for dynamically built family
|
|
|
|
.. note::
|
|
|
|
If a subfamily or a subvariable already has the name of a parameter it is possible to use the "_<parameter>" name.
|
|
You can have a look at the tutorial with a real world sample :ref:`of parameter with "_" <tutorial/underscore_parameter>`.
|
|
|
|
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 <tutorial/family>`
|
|
- :ref:`help parameter <tutorial/examples>` (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 <tutorial/dynfam>`
|
|
|
|
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 <tutorial/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 <tutorial/family>`
|