rougail/doc/fill/README.md

Table of Contents

• Les valeurs par défault calculées
• Synopsis
• Paramètres
• Exemples
• Calcul via un template Jinja
• Variable meneuse ou suiveuse avec valeur calculé
• Variable dynamique avec une valeur calculée
• Variable avec valeur calculée obligatoire
• Rédéfinition
• Redéfinition des calcules
• Redéfinition avec suppression d'un calcul

Les valeurs par défault calculées

Synopsis

Une valeur peut être calculée. Dans ce cas on a quatre possibilités :

• calcul via Jinja
• calcul via une variable
• calcul via une information
• calcul via un suffix : dans le cas d'une variable dans une famille dynamique
• calcul via un index : dans le cas d'une variable suiveuse

Si l'utilisateur modifie la valeur de la variable, la valeur par défaut n'est plus utilisé, donc le calcul n'est plus réalisé. C'est le cas également si la variable à l'attribut auto_save.

Par contre si la variable est caché (avec le paramètre hidden) c'est la valeur par défaut qui est utilisé et non la valeur personnalisée par l'utilisateur.

Paramètres

Suivant les types de calcul les paramètres vont être différents :

Type de calcul	Paramètre	Commentaires	Exemple
	type string mandatory	Nom du calcul, les valeurs possible sont : jinja, variable, information, suffix ou index	jinja
Jinja	jinja string mandatory	Template Jinja. Pour une variable multiple, chaque ligne représente une valeur.	{% if rougail.variable %}{{ rougail.variable }}{% endif %}
Jinja	params list	Paramètres complémentaire passé au template Jinja
Variable (mandatory) Information	variable string	Nom de la variable associée	rougail.variable
Variable	propertyerror boolean	Si l'accès à la variable n'est pas possible à cause d'une propriété (par exemple disabled) par défaut une erreur est retournée. Si l'attribut est à False, la valeur calculée est vide. Valeur par défaut : True	False
Information	information string mandatory	Nom de l'information dont on veut récupérer la valeur.	doc

Dans le cas d'un calcul de type Jinja, il est possible d'avoir des paramètres.

Il existe deux types de paramètre :

• les paramètres standards (string, boolean, integer, null), dans ce il suffit de faire : "key: value"

• les paramètres avancés :

  • paramètre via une variable
  • paramètre via une information
  • paramètre via un suffix : dans le cas d'une variable dans une famille dynamique
  • paramètre via un index : dans le cas d'une variable suiveuse

| Type du paramètre | Paramètre | Commentaires | Exemple | | | name
string
mandatory | Le nom du paramètre | my_param | | | type
string
mandatory | Type du paramètre, les valeurs possible sont : variable, information, suffix ou index| suffix | | Variable | variable
string
mandatory | Nom de la variable | rougail.variable | | Variable (mandatory)
Information | propertyerror
boolean | Si l'accès à la variable n'est pas possible à cause d'une propriété (par exemple disabled) par défaut une erreur est retournée. Si l'attribut est à False, le paramètre n'est pas passé au template Jinja.
Valeur par défaut : True | False | | Variable | optional
boolean | La variable peut ne pas exister suivant les importations de fichier YAML. Si le paramètre optional est à True, le paramètre sera tout simplement supprimer si la variable n'existe pas.
Valeur par défaut : False | True | | Information | information
string
mandatory | Nom de l'information dont on veut récupérer la valeur. | doc |

Exemples

Calcul via un template Jinja

Commençons par exemple à partir d'un simple template Jinja :

---
version: '1.0'
my_calculated_variable:
  default:
    type: jinja
    jinja: 'no'

Voici un deuxième exemple avec une variable de type booléen :

---
version: '1.0'
my_calculated_variable:
  type: boolean
  default:
    type: jinja
    jinja: 'false'

Et une valeur multiple de type nombre :

---
version: '1.0'
my_calculated_variable:
  type: number
  multi: true
  default:
    type: jinja
    jinja: |
      1
      2
      3      

Créons une variable dont la valeur est retournée par une fonction Python :

---
version: '1.0'
my_calculated_variable:
  default:
    type: jinja
    jinja: '{{ return_no() }}'

Puis créons la fonction "return_no" :

def return_no():
    return 'no'

Enfin voici un exemple avec un paramètre :

---
version: '1.0'
my_calculated_variable:
  default:
    type: jinja
    jinja: |
      {{ param1 }}{% if param2 is defined %}_{{ param2 }}{% endif %}      
    params:
      param1: value
      param2:
        type: variable
        variable: rougail.unknown_variable
        optional: true

Variable meneuse ou suiveuse avec valeur calculé

Une variable suiveuse ne peut pas être calculé automatiquement. Une variable meneuse peut être calculé automatiquement. Si la variable n'est pas multiple, il ne faut pas que le calcule retourne une liste.

Variable dynamique avec une valeur calculée

Il est également possible de calculer une variable d'une famille dynamique à partir d'une variable standard :

---
version: '1.0'
suffixes:
  type: string
  description: Suffixes of dynamic family
  multi: true
  default:
    - val1
    - val2
my_variable:
  type: string
  description: My variable
  default: val
dyn_:
  type: dynamic
  variable: rougail.suffixes
  my_calculated_variable_dyn_:
    type: string
    description: My calculated variable
    default:
      type: variable
      variable: rougail.my_variable

Dans ce cas, les variables dynamiques "rougail.dyn_.my_calculated_variable_dyn_" seront calculés à partir de la valeur de la variable "my_variable". Que cela soit pour la variable "rougail.dynval1.my_calculated_variable_dyn_val1" ou "rougail.dynval2.my_calculated_variable_dyn_val2".

Par contre, il n'est pas possible de faire un calcul pour une seule des deux variables issues de la variable dynamique. Si c'est ce que vous cherchez à faire, il faudra prévoir un traitement particulier dans votre fonction.

Dans ce cas, il faut explicitement demander le suffix et faire un traitement :

---
version: '1.0'
suffixes:
  type: string
  description: Suffixes of dynamic family
  multi: true
  default:
    - val1
    - val2
my_variable:
  type: string
  description: My variable
  default: val
dyn_:
  type: dynamic
  variable: rougail.suffixes
  my_calculated_variable_dyn_:
    type: string
    description: My calculated variable
    default:
      type: jinja
      jinja: "{% if suffix == 'val1' %}value{% endif %}"
      params:
        suffix:
          type: suffix

Variable avec valeur calculée obligatoire

Par défaut les variables calculées ne sont pas des variables obligatoires. Dans ce cas un calcul peut retourner "None" ou "", mais surtout un utilisateur peut spécifier une valeur nulle à cette variable. Dans ce cas le calcul ne sera plus réalisé.

Une variable calculée est une variable donc sa valeur est le résultat d'une fonction Python.

Rédéfinition

Redéfinition des calcules

Dans un premier dictionnaire déclarons notre variable et notre calcule :

---
version: '1.0'
my_calculated_variable:
  default:
    type: jinja
    jinja: '{{ return_no() }}'

Dans un second dictionnaire il est possible de redéfinir le calcul :

---
version: '1.0'
my_calculated_variable:
  redefine: true
  default:
    type: jinja
    jinja: '{{ return_yes() }}'

Dans ce cas, à aucun moment la fonction "return_no" ne sera exécuté. Seul la fonction "return_yes" le sera.

Redéfinition avec suppression d'un calcul

Il se peut que dans un dictionnaire on décide de définir une valeur par défaut à une variable via un calcul.

Dans un second dictionnaire il est possible de supprimer ce calcul.

Dans un premier dictionnaire déclarons notre variable et notre calcule :

---
version: '1.0'
my_calculated_variable:
  default:
    type: jinja
    jinja: '{{ return_no() }}'

Dans un second dictionnaire supprimer ce calcul :

---
version: '1.0'
my_calculated_variable:
  redefine: true
  default: null