List-Feld

Eine Tabelle aus Zeilen, jede in einem Unterformular bearbeitet

Ein list-Feld zeigt eine Tabelle aus Zeilen, die jeweils in einem eigenen Unterformular-Bereich erstellt und bearbeitet werden (ein Drilldown-Muster). Es ersetzt das Feld table, das in 7.0.0 entfernt wurde.

Hauptfunktionen

Das list-Feld bietet folgende Möglichkeiten:

Jede Zeile wird in einem Unterformular im Vollbild bearbeitet, mit Zugriff auf alle Feldtypen, einschließlich verschachtelter Listen.
Das Unterformular ist ein eigenes Formular vom Typ subform und kann in mehreren list-Feldern verschiedener Formulare wiederverwendet werden (z. B. ein einziges Unterformular Address, das Kunden, Lieferanten, Bestellungen… gemeinsam nutzen).
Die Marker-Eigenschaften (insertMarker, updateMarker, deleteMarker) unterstützen idempotente Playbook-Muster.
Bei allowDelete: false sind bereits vorhandene Zeilen geschützt; nur in der aktuellen Sitzung hinzugefügte Zeilen (mit dem insertMarker) können gelöscht werden.
Die Eigenschaft columns steuert, welche Felder des Unterformulars als Spalten in der Übersichtstabelle erscheinen.
Die Ausgabe ist immer ein Array von Objekten. model, output, outputObject und valueColumn, die auf Feldern des Unterformulars deklariert sind, werden beim Erzeugen der Extravars berücksichtigt.

Deklaration des Unterformulars

Ein Unterformular ist ein eigenes Formular mit type: subform, in einer Datei des Formularordners wie jedes andere Formular. Es akzeptiert dasselbe Array fields wie jedes andere Formular, erscheint aber nie in der Kachelliste der Formulare und wird nie direkt abgesendet.

- 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

Eigenschaften

Die für ein list-Feld verfügbaren Eigenschaften, nach Zweck gruppiert:

Attribut	Kommentare
basic
name string / erforderlich / eindeutig	Field name Alfanumeric + underscore + dash This attribute represents the name of the form field.
type string / erforderlich	Field type Other attributes might only be available for some field types. Wert: list Beispiele 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 / erforderlich	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) Beispiele 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. Standard: 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. Beispiele 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. Beispiele 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 hinzugefügt in Version 4.0.0	The dependency logical function This attribute represents the logical function between multiple dependencies. Auswahlmöglichkeiten: and (Standard) 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`. Beispiele 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. Standard: 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. Standard: true
showLoadButton boolean hinzugefügt in 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. Standard: false Beispiele 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 hinzugefügt in 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. Standard: false
output
output boolean hinzugefügt in 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. Standard: 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. Beispiele 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__`. Beispiele 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. Beispiele 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 hinzugefügt in Version 5.1.0	Adds an additional updatemarker field In addition to the insert and delete markers, you can also add an update marker. Beispiele 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 hinzugefügt in Version 2.2.3	Disable backend logging Disables logging in the backend, to hide passwords for example. Standard: false Beispiele hide password in log `- name: password type: password label: Enter password noLog: true`
validation
required boolean	Required field Makes the field required. Standard: false
validIf object hinzugefügt in 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) Beispiele 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 hinzugefügt in 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) Beispiele 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. Standard: 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 hinzugefügt in 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 hinzugefügt in 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/ Auswahlmöglichkeiten: col-1 col-2 col-3 col-4 col-5 col-6 col-7 col-8 col-9 col-10 col-11 col-12 Beispiele 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). Beispiele Show only wanted columns `- name: users type: enum dbConfig: CMDB query: SELECT id, name, username, zip, city FROM users columns: - name - username`

Beispiele

Gemeinsames Adress-Unterformular

Ein Unterformular Address, das von zwei list-Feldern desselben Formulars wiederverwendet wird:

- 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

Nachverfolgung mit Markern (idempotent)

Vorab geladene Zeilen sind geschützt, und die Marker teilen dem Playbook mit, welche Zeilen neu, geändert oder entfernt sind:

- 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

Zeilen vorab füllen

Eine Liste kann aus drei Quellen vorab gefüllt werden. In jedem Fall müssen die entstehenden Zeilen Objekte sein, deren Schlüssel zu den Feldnamen des referenzierten Unterformulars passen.

Statisches `default`

Zeilen, die im Formular selbst stehen:

- 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

Aus einer REST-API (`expression`)

Zeilen, die ein serverseitiger Ausdruck aus einer REST-API lädt:

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

Aus einer Datenbankabfrage (`dbConfig` + `query`)

Zeilen, die aus einer Datenbankabfrage geladen werden:

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

dbConfig nennt eine Datenbank unter Verbindungen > Datenbanken (ab 7.5.0) oder sonst Anmeldedaten vom Typ Datenbank, wie bisher (siehe Datenbanken in Formularen).

Aus einem lokalen Ausdruck (`runLocal`)

Zeilen, die ein lokaler Ausdruck im Browser berechnet:

- 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' }
    ]

Verschachtelte Listen

Ein Unterformular kann ein eigenes list-Feld enthalten, für eine Liste innerhalb jeder Zeile:

- 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

Über `parent` auf Daten des übergeordneten Formulars zugreifen

Wenn sich der Zeileneditor eines Unterformulars öffnet, fügt AnsibleForms eine Variable __parent__ in das Unterformular ein. Sie enthält eine Momentaufnahme aller Feldwerte des übergeordneten Formulars, einschließlich Konstanten und Vars.

Verweisen Sie darauf mit der üblichen Ausdruckssyntax $(...) in den Felddefinitionen des Unterformulars:

- 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__ ist ein Hilfsmittel nur für das Frontend. Es wird aus den Ansible-Extravars entfernt und nie an das Playbook gesendet.