Dynamic Documents & Forms Module

General information

1.1. Artifact

<dependencies>
	<dependency>
		<groupId>com.foreach.across.modules</groupId>
		<artifactId>dynamic-forms-module</artifactId>
		<version>0.0.1-SNAPSHOT</version>
	</dependency>
</dependencies>

1.2. Module dependencies

Table 1. Module dependencies
Module Type Description

EntityModule

required

Enables the ability to define and render custom forms.

AcrossHibernateJpaModule

required

Required for the JPA domain model.

About the DynamicFormsModule

The DynamicFormsModule enables users to manage custom documents, which can be used to create a custom form, or add additional fields to an existing form.

It is useful for

  • defining documents at runtime

  • quickly changing data models

  • adding metadata to entities

  • little code interaction is required for documents that are defined

    • logic should not be tightly coupled with documents as they are ever-changing

  • working with a small data sets

    • depending on performance requirements

It is not advised for

  • replacing actual entities

  • using documents that must never be modified

  • working with documents being mostly steered through code

    • logic should not be tightly coupled with documents as they can be changed at runtime.

  • working with large data sets

    • depending on performance requirements

Documents

Documents are the base building blocks to create manageable groups of fields. They are split up in various parts, being a template for a document, the types that can be used in a document and filled in data for a document.

A document definition is a template defining the fields and sets of fields that the document represents. The document holds the content for the various fields of its definition.

1.1. Document definition

Document definitions represent groups of fields and are in turn grouped within datasets. Each definition is defined as a RawDocumentDefinition, which is the base representation of a document template in a json or yaml format. A RawDocumentDefinition can be converted to a DynamicDocumentDefinition, which represents a fully usable document.

Conversion is done through the DynamicDocumentDefinitionBuilder, which creates property descriptors with the correct type and validation for the various fields defined in the document definition. Aside of creating the DynamicDocumentDefinition, it will also ensure that document definitions have a correct configuration.

Example document definition
document-definition:
  name: Event (1)
  content:
  - id: location (2)
    type: string
    label: Location
  - id: date (2)
    type: date
    label: Date
1 We create a definition for an event.
2 An event has 2 fields, being the location and date of the event.

1.2. Type definition

Type definitions enable documents to use typed fields, as well as provide the necessary configuration for a specific field. The default type definitions are the building blocks to create new custom types and have a java representation.

Table 2. Default types
Type Backing java type Description

string

String.class

Represents a field containing a single line of text.

text

String.class

text represents a field containing multiple lines of text.

boolean

Boolean.class

Represents true or false

date

LocalDate.class

Represents a specific year, month and day.

time

LocalTime.class

Represents a combination of hours, minutes, seconds, milliseconds and nanoseconds.

datetime

LocalDateTime.class

Represents a specific point in time. Per se datetime is a combination of date and time.

number

Long.class

Represents a whole number.

decimal

BigDecimal.class

Represents a decimal number. Can optionally define a precision.

currency

BigDecimal.class

Represents a value in a specific currency.

percentage

BigDecimal.class

Represents a fraction. Optionally, the multiplier and precision can be specified.

A type can also represent a group of fields. This enables the possibility to define custom data-types, without any code intervention.

Example type definition
document-definition:
  name: Sample document
  types:
  - id: address (1)
    base-type: fieldset
    fields:
    - id: street (2)
      type: string
    - id: number (2)
      type: number
    - id: zip-code (2)
      type: number
      label: Zipcode
    - id: city (2)
      type: string
1 We define a custom address type.
2 An address consists of a street, a house number, a zip-code and a city.

1.3. Document data

Document data holds the content for a specified document definition.

Example document data