Champ List

Un tableau de lignes, chacune modifiée dans un sous-formulaire

Un champ list affiche un tableau de lignes, chacune créée et modifiée dans un volet de sous-formulaire dédié (un modèle d’exploration). Il remplace le champ table, supprimé dans la 7.0.0.

Fonctionnalités clés

Le champ list offre les possibilités suivantes :

  • Chaque ligne est modifiée dans un sous-formulaire plein écran, qui donne accès à tous les types de champ, y compris les listes imbriquées.
  • Le sous-formulaire est un formulaire à part entière, de type subform, et peut être réutilisé par plusieurs champs list dans différents formulaires (par ex. un seul sous-formulaire Address partagé par les clients, les fournisseurs, les commandes…).
  • Les propriétés de marqueur (insertMarker, updateMarker, deleteMarker) permettent des modèles de playbook idempotents.
  • Avec allowDelete: false, les lignes préexistantes sont protégées ; seules les lignes ajoutées pendant la session en cours (qui portent l’insertMarker) peuvent être supprimées.
  • La propriété columns contrôle quels champs du sous-formulaire apparaissent comme colonnes dans le tableau récapitulatif.
  • La sortie est toujours un tableau d’objets. model, output, outputObject et valueColumn déclarés sur les champs du sous-formulaire sont respectés lors de la génération des extravars.

Déclaration d’un sous-formulaire

Un sous-formulaire est un formulaire à part entière avec type: subform, dans un fichier du dossier des formulaires comme n’importe quel autre formulaire. Il accepte le même tableau fields que tout autre formulaire, mais il n’apparaît jamais dans la liste des tuiles de formulaires et n’est jamais soumis directement.

- name: Address
  type: subform
  fields:
    - name: street
      type: text
      label: Street
      required: true
    - name: city
      type: text
      label: City
      required: true
    - name: country
      type: text
      label: Country

Propriétés

Les propriétés disponibles pour un champ list, 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 :
list
Exemples

Text

- type: text
  name: username
  label: Username
  default: ansibleguy
  placeholder: type a username
  required: true
  minLength: 4
  maxLength: 10
  regex:
    expression: "^[a-zA-Z]*$"
    description: Must be alpha numeric
  icon: user
  help: A help message    

# more examples per type, check out the links at the top of the page
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)

Exemples

Get a list of users from a rest api

- name: users
  type: enum
  expression: fn.fnRestBasic('get','http://myapi/user','','credential_name')

Filter and sort an array of objects

- name: superheros
  type: enum
  expression: |
    fnArray.from($(mylist))
    .filterBy({has_ability:true})
    .selectAttr('name','ability')
    .sortBy('name')"
  runLocal: true

Make a numbered list

- name: numbers
  type: enum
  expression: "Array.from({length: 10}, (_, i) => i + 1)"
  runLocal: true

Use the alias `local`

- name: uppercase
  type: local
  expression: "'test'.toUpperCase()"
  # with type local, these are the defaults:
  # runLocal: true
  # hide: true
  # output: false

Use the alias `local_out`

- name: uppercase
  type: local_out
  expression: "'test'.toUpperCase()"
  # with type local_out, these are the defaults:
  # runLocal: true
  # hide: 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.

Exemples

get information from a mysql database (legacy example - deprecated)

# Old style (deprecated) - type was required separately:
- name: cities
  type: enum
  dbConfig:
    name: CMDB_CONN
    type: mysql
  query: select name, country from cities
# New style - just use the name of the database (or of the credential):
- name: cities
  type: enum
  dbConfig: CMDB_CONN
  query: select name, country from cities

get information from a mysql database (new example)

- name: cities
  type: enum
  dbConfig: CMDB_CONN # a database of Connections > Databases ; the type is its credential's
  query: select name, country from cities

get information from a mysql database (array example)

- name: cities
  type: enum
  dbConfig: # the query will be a union of the results of the 2 databases
  - CMDB_CONN1
  - CMDB_CONN2
  query: select name, country from cities

get information from a mongodb

- name: user
  type: expression
  dbConfig: USER_DB_CONN
  query: cmdb~users~{"name":"ansibleguy"}
  # the query in mongodb has 3 parts, separated by ~  
  # database, collection and the query in valid json
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.

Exemples

get information from a mysql database

- name: cities
  type: enum
  dbConfig: CMDB_CONN
  query: select name, country from cities

get information from a mongodb

- name: user
  type: expression
  dbConfig: USER_DB_CONN
  query: cmdb~users~{"name":"ansibleguy"}
  # the query in mongodb has 3 parts, separated by ~  
  # database, collection and the query in valid json
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.

Exemples

Show a field based on a checkbox

- name: add_extra_comment
  label: Add extra comment ?
  type: checkbox
- name: extra_comment
  type: text
  label: Type your extra comment
  dependencies:
  - name: add_extra_comment
    values:
    - true

Show a field if another field is valid

- name: code
  type: text
  regex: 
    expression: "^[a-z]{3}$"
    description: Must be 3 characters lowercase
  required: true
- name: code_uppercase
  type: expression
  runLocal: true
  expression: "'$(code)'.toUpperCase()"
  dependencies:
  - name: code
    isValid: true     # new in 4.0.13 -> code_uppercase will only be shown if code is validated

Show a field based on 2 fields, using the 'or' function

- name: job_type
  label: Job type
  type: enum
  values:
  - IT
  - HR
  - Sales
  - Management
- name: has_private_office
  type: checkbox
  label: Has private office ?
- name: office_name
  type: text
  label: What's the name of the office
  dependencyFn: or
  dependencies:
  - name: job_type
    values:
    - Sales
    - Management
  - name: has_private_office
    values:
    - true
- name: office_name2
  type: text
  label: What's the name of the office
  dependencyFn: or
  dependencies:
  - name: "!job_type"     # this will invert/negate - note the wrapping quotes!! needed for valid yaml
    values:
    - IT
    - HR
  - name: has_private_office
    values:
    - true
allowInsert
boolean

Allow table/list insert

A table or list can be used to modify existing data. If new data is not allowed, set this property to false.

Par défaut :
true
allowDelete
boolean

Allow table/list delete

A table can be used to modify existing data. If you don’t was recoreds to be deleted, set this property to false.

Par défaut :
true
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
Exemples

List with YAML import

- type: list
  name: users
  label: Users
  subform: User         # a form of type subform with the fields username and email
  showLoadButton: true
  showDownloadButton: true

YAML field with file import

- type: yaml
  name: config
  label: Configuration
  showLoadButton: true
  showDownloadButton: true
  default:
    key: value
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
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.

Exemples

Model 2 fields together as a single object

- name: diskName
  type: text
  model: disk[0].name
- name: diskSize
  type: number
  model: disk[0].size
# the extravars of this example will be like this:
# disk:
# - name: mydisk
#   size: 123
deleteMarker
string

Adds an additional deletemarker field

When you remove a record in a table, it gets removed.
When working with ansible and idempotency, the playbook never knew it got removed.
You need to explicitly set the status to absent.
So you can add a custom property to the deleted record, marking the record as deleted and sending it to the playbook for removal.

Since 6.4.1 the markers of a list field reach the playbook as well: a removed row is sent with its delete marker instead of looking like a live row. Before, a list row only carried a marker when its subform declared it as a (hidden) field. When rows can be deleted or updated but no insertMarker is set, new rows are marked __inserted__.

Exemples

Mark delete record

- type: list
  name: member
  subform: Member       # a form of type subform with the fields firstname and lastname
  expression: "[{firstname:'ansible',lastname:'guy'}]"
  deleteMarker: deleted
insertMarker
string

Adds an additional insertmarker field

When you add a record in a table, it simply gets added.
When working with ansible and idempotency, your playbook doesn’t know which records are new and which are not.
You might want to explicitly run a taks on only the new records.
So you can add a custom property to the inserted record, marking the record as new.

Exemples

Mark new record

- type: list
  name: member
  subform: Member       # a form of type subform with the fields firstname and lastname
  expression: "[{firstname:'ansible',lastname:'guy'}]"
  insertMarker: new
updateMarker
string
ajouté dans la version 5.1.0

Adds an additional updatemarker field

In addition to the insert and delete markers, you can also add an update marker.

Exemples

Mark updated record

- type: list
  name: member
  subform: Member       # a form of type subform with the fields firstname and lastname
  expression: "[{firstname:'ansible',lastname:'guy'}]"
  updateMarker: updated
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
Exemples

hide password in log

- name: password
  type: password
  label: Enter password
  noLog: true
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)

Exemples

Ip must be pingable

validIf:
  field: rest_api_ping_test  # an other expression field that is returning true or false
  description: The ip is not pingable
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)

Exemples

Check if powered off

validIfNot:
  field: rest_api_ping_test  # an other expression field that is returning true or false
  description: The ip is still pingable, shut down the machine first
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
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

Name and lastname

- type: text
  name: name
  label: Firstname
  group: login
  line: names
- type: text
  name: lastname
  label: Lastname
  group: login
  line: names
titleAdd
string

Title shown in the subform pane when adding a new row

When you add a row through a list field, the subform pane shows Add <label> as subtitle.
Use this property to override the subtitle (e.g. Add address).
titleEdit
string

Title shown in the subform pane when editing an existing row

When you edit a row through a list field, the subform pane shows Edit <label> as subtitle.
Use this property to override the subtitle (e.g. Edit address).
columns
array

The list of columns visible in the dropdown/table

For an enum field: all properties are shown by default. Use this property to choose which columns are visible in the dropdown.
For a list field: all scalar subform fields are shown by default. Use this property to pick which subform fields render as columns in the list table (missing names soft-fail and render as empty columns).

Exemples

Show only wanted columns

- name: users
  type: enum
  dbConfig: CMDB
  query: SELECT id, name, username, zip, city FROM users
  columns:
  - name
  - username

Exemples

Sous-formulaire d’adresse partagé

Un sous-formulaire Address réutilisé par deux champs list du même formulaire :

- name: Address
  type: subform
  fields:
    - name: street
      type: text
      label: Street
      required: true
    - name: city
      type: text
      label: City
      required: true
    - name: country
      type: text
      label: Country

- name: Create customer
  type: ansible
  playbook: customer.yaml
  roles: [default]
  fields:
    - name: name
      type: text
      label: Customer name
      required: true
    - name: addresses
      type: list
      label: Addresses
      subform: Address
      columns:
        - city
        - country
      titleAdd: Add address
      titleEdit: Edit address
      allowInsert: true
      allowDelete: true

Suivi par marqueurs (compatible avec l’idempotence)

Les lignes préchargées sont protégées, et les marqueurs indiquent au playbook quelles lignes sont nouvelles, modifiées ou supprimées :

- name: people
  type: list
  label: People
  subform: Person
  allowDelete: false       # preloaded rows are protected
  insertMarker: added      # session-added rows remain removable
  updateMarker: updated
  deleteMarker: removed
  columns:
    - name
    - email

Pré-remplir les lignes

Une liste peut être pré-remplie depuis trois sources. Dans tous les cas, les lignes obtenues doivent être des objets dont les clés correspondent aux noms des champs du sous-formulaire référencé.

default statique

Des lignes écrites dans le formulaire lui-même :

- name: addresses
  type: list
  label: Addresses
  subform: Address
  columns:
    - city
    - country
  default:
    - street: Main 1
      city: Brussels
      country: BE
    - street: Side 22
      city: Paris
      country: FR

Depuis une API REST (expression)

Des lignes chargées depuis une API REST par une expression côté serveur :

- name: users
  type: list
  label: Users
  subform: User
  columns:
    - username
    - email
  expression: fn.fnRestBasic('get','https://api.example.com/users','','my_api_cred','')

Depuis une requête de base de données (dbConfig + query)

Des lignes chargées depuis une requête de base de données :

- name: servers
  type: list
  label: Servers
  subform: Server
  columns:
    - hostname
    - role
  dbConfig: CMDB_CONN
  query: SELECT hostname, role FROM servers WHERE active = 1

dbConfig nomme une base de données de Connexions > Bases de données (depuis la 7.5.0), ou sinon un identifiant de type base de données, comme avant (voir Les bases de données dans les formulaires).

Depuis une expression locale (runLocal)

Des lignes calculées dans le navigateur par une expression locale :

- name: ports
  type: list
  label: Open ports
  subform: Port
  columns:
    - port
    - protocol
  runLocal: true
  expression: |
    [
      { port: 22,  protocol: 'tcp' },
      { port: 80,  protocol: 'tcp' },
      { port: 443, protocol: 'tcp' }
    ]

Listes imbriquées

Un sous-formulaire peut contenir son propre champ list, pour avoir une liste dans chaque ligne :

- name: Address
  type: subform
  fields:
    - name: street
      type: text
      label: Street
    - name: city
      type: text
      label: City

- name: Person
  type: subform
  fields:
    - name: name
      type: text
      label: Name
      required: true
    - name: addresses
      type: list
      label: Addresses
      subform: Address
      columns:
        - street
        - city

- name: My Form
  type: ansible
  playbook: people.yaml
  roles: [default]
  fields:
    - name: people
      type: list
      label: People
      subform: Person
      columns:
        - name
        - addresses

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

Quand l’éditeur de ligne d’un sous-formulaire s’ouvre, AnsibleForms injecte une variable __parent__ dans le sous-formulaire. Elle contient un instantané de toutes les valeurs des champs du formulaire parent, 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: NodeConfig
  type: subform
  fields:
    - name: node_name
      type: text
      label: Node name
      required: true

    - name: node_type
      type: enum
      # only offer gpu in production environments (parent field)
      expression: |
        '$(__parent__.environment)' === 'production'
          ? ['standard', 'high-memory', 'gpu']
          : ['standard', 'high-memory']
      runLocal: true
      default: __auto__

- name: Deploy cluster
  type: ansible
  playbook: deploy.yml
  roles: [default]
  fields:
    - name: environment
      type: enum
      values: [dev, staging, production]
      required: true

    - name: nodes
      type: list
      subform: NodeConfig
      columns: [node_name, node_type]

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