Creating a document definition

Defining fields

A dynamic document consists of a number of fields with corresponding values. A dynamic document definition holds all the metadata of those fields, it is in turn comprised of a number of field definitions.

A single field definition at minimum defines a unique id for that field, as well as a field type. The id identifies the field. The type determines how the field will be stored and treated in code (see dynamic field types).

A field id must be unique in the scope of its parent (usually the document itself or a fieldset). The field id will be used to build a fully qualified, unique path to that field in a document.

Example field id and path

document-definition:
  name: sample-document
  content:
    - id: name (1)
      type: string
    - id: address (2)
      type: fieldset
      fields:
      - id: street (3)
        type: string
      - id: number (4)
        type: number

1	top-level field with id `name` has path `name`
2	top-level field with id `address` has path `address`
3	fieldset member with id `street` has path `address.street`
4	fieldset member with id `number` has path `address.number`

Add field validators

A document field can have any number of validators attached to it. When a document is validated, every field will be checked against its validators to determine if the field value is valid.

Validators are specified under the validators key as a list of configuration settings. Configuration settings can either be a single String value identifying the validator, or a map with String keys.

The default administration UI will not allow saving an invalid document. However, document validation is a separate step that needs to be performed manually.

See the chapter on validating a document in code for more information.

Example YAML document definition with field validators

document-definition:
  name: sample-document
  types:
    - id: telephone-number
      base-type: number
      validators: (1)
        - my-custom-pattern-validator: "+xxxx/xx.xx.xx"
  content:
    - id: name
      type: string
      validators:  (1)
       - required
    - id: telephone
      type: telephone-number
      validators:  (2)
       - required

1	Validators can be added on both type and field definitions.
2	The set of validators defined on type and field definition will be merged. For our `telephone` field, both `my-custom-pattern-validator` and `required` would be applied.

There are separate pages with the list of the available validators and information on creating a custom validator.

Configure custom messages and labels

You can add custom messages to be used in the user interface for any field or type. Messages are specified under the messages key as a map of message code and message entries.

A label can also be provided for every field definition.

Example YAML document definition with custom messages

document-definition:
  name: sample-document
  types:
    - id: telephone-number
      base-type: string
      messages: (1)
        tooltip: "Enter your telephone number"
        help: "+32 xxxx/xx.xx.xx"
  content:
    - id: name
      type: string
      messages: (1)
        description: "Your personal name"
    - id: telephone
      label: "Telephone number" (2)
      type: telephone-number
      messages: (3)
        help: "0032 xxxx/xx.xx.xx"

1	You can define a `messages` block on both a type or a content field definition.
2	This is the label used to display as the column heading in a list view or the label of the form.
3	A message defined on a content field will replace a message with the same code on the type definition. In this example, the `help` code from the base type will be overwritten and contain `0032 xxxx/xx.xx.xx`.

Translations

Any message or label can be translated by specifying it under the corresponding IETF language tag in the messages section.

Example YAML document definition with custom messages and locales

document-definition:
  name: sample-document
  content:
    - id: name
      type: string
      label: "Name"
      messages: (1)
        description: "Your personal name" (1)
        en:
          description: "Your personal name in English" (2)
        ja-JP:
          label: "名"
          description: "あなたの個人的な名前" (3)
        no-NO-NY:
          label: "Navn"
          description: "Ditt personlige navn"  (4)
  messages: (5)
    name.plural: "Sample documents"
    nl:
      name.singular: "Voorbeeld document"

1	The default description, used when no matching locale was found.
2	The description for all English speaking countries (Australia, Candara, India, Ireland, Malta, …).
3	The description for Japan.
4	The description for Norvegian Norsk, a variant of standard Norvegian Bokmål.
5	Global document messages - like document name - can also be specified directly under a `messages` attribute at the root level.

The default messages do not require being grouped under a language tag, but - for consistency - it is allowed to group them under a default language tag.

Default message codes

The following global message codes can be configured:

name.singular: The translated singular name of the document type.
name.plural: Plural form of the document type name.

The following message codes can be configured per field:

label: Descriptive label of the field.
description: On a form, this shows a description message above the control for that field.
help: On a form, this shows a help text below the control for that field.
tooltip: On a form, this is the text behind a tooltip (question mark) icon next to the field label.
placeholder: For a textbox form control, this is the placeholder message shown if the textbox is empty.
validation.VALIDATION_CODE: Feedback message if validation fails with the specified VALIDATION_CODE.

Field message codes can be configured under the global messages attribute if they are in the qualified form without the document definition prefix (see the next section).

Using properties files

DynamicFormsModule uses entity views and corresponding message codes for its UI. It is possible to customize dynamic document messages directly in shared properties by using the fully qualified message code. Every document specific message code will be prefixed with the document definition key in the form of DynamicDocument[DEFINITION_KEY].

Example messages in properties file

DynamicDocument[dataset\:document].name.singular=My document
DynamicDocument[dataset\:document].properties.field\:address=Address
DynamicDocument[dataset\:document].properties.field\:address[help]=Please enter your home address.
DynamicDocument[dataset\:document].validation.required.binderMap[address]=Address field is required

Properties files require colons to be escaped.