Champ YAML

Des données structurées dans un éditeur YAML, avec validation et import de fichier

---

Propriétés

Les propriétés disponibles pour un champ yaml, regroupées par usage :

Attribut	Commentaires
basic
name string / obligatoire / unique	Field name Alfanumeric + underscore + dash This attribute represents the name of the form field.
type string / obligatoire	Field type Other attributes might only be available for some field types. Valeur : yaml
label string	Field label Free text A friendly name/label for the field. Note: if not set, the field name is used as label, but not when type is html. Since 6.0.3: Supports placeholders for dynamic labels (e.g., Label: $(fieldname)).
help string	Field help message Free text Some fields require additional help information. This help message will be shown below the field. Since 6.0.3: Supports placeholders for dynamic help text (e.g., This field depends on $(fieldname)).
subform string / obligatoire	Name of the subform that defines one row For a list field: delegates the per-row editor to a subform. For a yaml field: the value is a single object edited via a subform drilldown instead of a raw YAML editor. Set this property to the name of a top-level form of type subform declared in the same forms file (or in any loaded forms file). The same subform can be referenced by multiple fields, enabling reuse (e.g. a single Address subform shared across several forms).
data
default many	Default value The type of the value depends on the field type. Can be string,boolean, number, array or object. When using multiple, the default must be an array. When using an enum field, you can use the following special values: __auto__: select the first __none__: select none __all__: select all (if multiple is true) For yaml fields, the default can be any valid YAML structure (object or array). For list fields, the default must be an array of objects matching the referenced subform’s fields. Use it to pre-populate the list with existing rows on form load.
expression string	A javascript expression. Valid javascript By default this javascript is evaluated on the server side and limited to predefined functions (for security). However in combination with runLocal, the evaluation is ran in the browsers sandbox and allows the full javascript power. An html field always evaluates its expression in the browser, as with runLocal: true: it never runs on the server. When used in an enum field, the expression must return a flat array or array of flat objects, to make it presentable in a dropdown box. An expression supports placeholders: $(fieldname) is replaced by the value of that field before the expression runs. On the server, the predefined functions are called as fn.<name>(...), for example fn.fnTime(). tip: use the alias local (type=’expression’,runLocal=true,hide=true,output=false) tip: use the alias local_out (type=’expression’,runLocal=true,hide=true) tip: use the alias credential (type=’expression’,runLocal=true,hide=true,asCredential=true)
runLocal boolean	Run an expression locally When running expressions, by default they are run remotely on the server. But remote expressions are limited to predefined functions. To unleash more javascript power, use this property. The code will be evaluated in the sandbox of the browser, offloading the server, saving api-calls and making it more secure. Par défaut : false
dbConfig string, array or object	A database connection When you want to query data from a database, you will need the proper connection information. Name a database of Connections > Databases : it connects with the credential of type database it names (the database type, server, database and login). Since 7.5.0 : a name that is no database is looked up as a credential of type database, as older forms do, so they keep working unchanged. Legacy was to pass an object (name and type) ; it still works, its name a database or a credential. Since version 5.0.2 you can just specify the name. The type is fetched from the credential (mysql, mssql, postgres, oracle or mongodb). In case of no type set, mysql is assumed. Additionally you can set an array of names, to use multiple databases with a single query. The result will be a join of the results. Doubles will not be removed automatically.
query string	The query to select data from a database A valid sql query This is typically a classic SELECT statement. However, in the case of mongodb, the query is slightly different. See the examples. A query supports placeholders: $(fieldname) is replaced by the value of that field before the query runs. Every $(...) value is escaped for the database engine before it is pasted into the query: single quotes are doubled, backslashes are doubled too on mysql (postgres, mssql and oracle keep them as they are), and on mongodb the value is escaped as the body of a JSON string. An object or array value is pasted as json, escaped the same way. This protects a quoted placeholder (where name='$(name)') only: an unquoted one (limit $(n)) is pasted as plain text, so quote your placeholders.
interaction
dependencyFn string ajouté dans la version 4.0.0	The dependency logical function This attribute represents the logical function between multiple dependencies. Choix : and (par défaut) or nand nor
dependencies list / elements=object	Show/hide this field based on the values or other fields Reference to other formfields and their values Each dependency element is either an object with the following 2 attributes: name: holds the fieldname. values: a list of valid values for the referenced field. Or with the following 2 attributes: name: holds the fieldname. isValid: a boolean to check if the referenced is validated or not. Use in combination with attribute dependencyFn.
showLoadButton boolean ajouté dans la version 6.1.5	Show load button for file import Enables a “Load YAML” button that allows users to import data from .yml or .yaml files. For list fields, the YAML file must contain a valid array of objects. For yaml fields, the file can contain any valid YAML structure. Single objects are automatically wrapped in arrays for list fields. Par défaut : false
showDownloadButton boolean ajouté dans la version 6.1.5	Show download button for file export Enables a “Download” button that exports the field content as a .yml file. The filename is automatically generated from the field name. Par défaut : false
readonly boolean ajouté dans la version 6.1.5	Display YAML in readonly mode When set to true, displays the YAML content with syntax highlighting in a non-editable card. Useful for showing computed or retrieved YAML data without allowing modifications. The field uses v-highlightjs for pretty syntax-highlighted display. Par défaut : false
output
output boolean ajouté dans la version 6.2.0	Include field value as extravar Form fields are by default sent as extravars. Set to false to exclude a field from the extravar output. Par défaut : true
model string or array	Extravar modelling An dot-based string notation of an object, or an array of these By default, a field is sent as a root-extravar. If you want model the output of the extravars, you can specify a dot-notation of how this field should be modelled.
security
noLog boolean ajouté dans la version 2.2.3	Disable backend logging Disables logging in the backend, to hide passwords for example. Par défaut : false
validation
required boolean	Required field Makes the field required. Par défaut : false
validIf object ajouté dans la version 2.2.4	An field based validation (field must be true) Enforces a validation where a referencing (expression) field must be true. This field requires an object with 2 attributes: field: The name of the referencing field description: A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
validIfNot object ajouté dans la version 2.2.4	An field based validation (field must be false) Enforces a validation where a referencing (expression) field must be false. This field requires an object with 2 attributes: field: The name of the referencing field description: A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
ignoreIncomplete boolean	Allow form submit on non-evaluated placeholders When an expression-based field has placeholders, the default form behaviour is not to allow form submit until all placeholders are resolved. When this attribute is true, the form does not wait for placeholder completion for this field. Par défaut : false
yamlError object ajouté dans la version 6.1.5	Custom YAML validation error message Allows you to customize the error message displayed when YAML syntax validation fails. The yamlError object requires a description property containing the custom message. Supports placeholders for dynamic error messages.
visualization
group string	The field group name Free text With this attribute you can group fields together. When all fields in a group are hidden (due to dependencies), the group is also hidden.
line string ajouté dans la version 4.0.3	The field line name Free text With this attribute you can group fields in a single line together. Use together with the width parameter to set the width, if not, the width is auto.
width string ajouté dans la version 4.0.3	The field width A valid Bootstrap Column width With this attribute you can set the width of a field. Use together wit the line parameter to put fields on 1 line. see https://getbootstrap.com/ Choix : col-1 col-2 col-3 col-4 col-5 col-6 col-7 col-8 col-9 col-10 col-11 col-12

---

Exemples

Exemples de champs yaml, en YAML :

Manual YAML editing

La définition du champ, en YAML :

- type: yaml
  name: config
  label: Application Configuration
  default:
    database:
      host: localhost
      port: 5432
    features:
      - authentication
      - logging
  showLoadButton: true
  showDownloadButton: true
  yamlError:
    description: "Please enter valid YAML configuration"
  required: true

YAML from expression

La définition du champ, en YAML :

- type: yaml
  name: users
  label: User List
  expression: fn.fnRestBasic('get','https://api.example.com/users','','','')
  showDownloadButton: true
  readonly: true

YAML from local expression

La définition du champ, en YAML :

- type: yaml
  name: computed_config
  label: Computed Config
  runLocal: true
  expression: |
    (()=>{
      return {
        env: 'production',
        settings: $(environment_field)
      };
    })()
  showDownloadButton: true

YAML from query

La définition du champ, en YAML :

- type: yaml
  name: database_data
  label: Database Records
  query: "SELECT * FROM servers"
  dbConfig: mydb
  showDownloadButton: true

---

Accéder aux données du formulaire parent via __parent__

Quand un champ yaml utilise le mode subform, AnsibleForms injecte une variable __parent__ dans le sous-formulaire. Elle contient un instantané de toutes les valeurs des champs du formulaire parent au moment où l’éditeur s’ouvre, y compris les constantes et les vars.

Faites-y référence avec la syntaxe d’expression standard $(...) dans les définitions de champ du sous-formulaire :

- name: NetworkConfig
  type: subform
  fields:
    - name: interface
      type: text
      label: Interface
      required: true

    - name: vlan
      type: enum
      label: VLAN
      # filter available VLANs based on the parent's selected region
      query: "select id,name from vlans where region='$(__parent__.region)'"
      dbConfig: MYDB      # a database of Connections > Databases
      valueColumn: id
      placeholderColumn: name

    - name: mtu
      type: number
      label: MTU
      # default to 9000 in production, 1500 elsewhere
      default: "'$(__parent__.environment)' === 'production' ? 9000 : 1500"
      evalDefault: true

- name: Configure server
  type: ansible
  playbook: configure.yml
  roles: [default]
  fields:
    - name: environment
      type: enum
      values: [dev, staging, production]

    - name: region
      type: enum
      values: [eu-west-1, us-east-1, ap-southeast-1]

    - name: nic
      type: yaml
      label: Network interface
      subform: NetworkConfig

__parent__ est une aide propre au frontend. Elle est retirée des extravars Ansible et n’est jamais envoyée au playbook.