aeppic

Appearance

Forms ​

Forms define the structure of documents. They are JSON documents themselves, with a special definition field written in FormDown, a markdown-like language for describing forms.

Example Form Down:

markdown
[Name][name]  
[Email Address][email]

This form will create a document with two data fields: name and email.

Fields default to being text fields, but you can specify the type of fields by adding specifying the type of a field. [age]: number would create a number field for example.

aeppic uses these definitions to automatically render forms for creating and editing documents. This ensures consistency and reduces development effort.

Conceptually a form is a template for a document. It defines the structure of the document and the fields that are required to be filled in. In order to understand how forms work, it is important to understand the following concepts of a document.

  • Fields: Fields are the individual data points that make up a document. For example, in a document that represents a person, fields could be name, age, and email address.
  • Field Types: Field types are the data types of the fields. For example, a field could be a text field, a number field, or a date field.
  • Controls: Controls are the UI elements that are used to show and input data into a field. For example, a text box, a dropdown, or a date picker.
  • Tags: Tags are metadata that can be added to fields. They can be used to add additional functionality to fields. For example, a <sensitive> tag could be used to mark a field as sensitive, which would hide the field from users who do not have the necessary permissions.

Fields ​

In a form, fields are defined using FormDown syntax. Each field has two parts:

Field Label and Field Name

The label is visible in the UI and optional, the name is the identifier and JSON key where the field’s data is stored. The name MUST be a valid javascript identifier without spaces or leading numbers etc.

Example:

markdown
[Label][field_name]

Field Type ​

Specified on a new line, starting with the field name in square brackets and followed by a colon we optionally define a type for a field.

Example:

markdown
[field_name]: text

TIP

Field types are optional. If not specified, the field will default to a text field. When a field is defined like [field_name]: it does not need to have a label defined anywhere. It would just becom a hidden field.

Cardinality: More Than One Value ​

By default, fields store a single value of the specified type. However, aeppic supports higher cardinality for fields, allowing them to store multiple values in an array.

Defining Cardinality ​

To specify cardinality, add it in parentheses after the field type. For example:

  • 0-n: Zero or more values.
  • 5-n: At least five values.

Example:

markdown
[Emails][emails]
[emails]: text (0-n)

This creates an emails field that allows multiple text entries.

Tags: Adding Metadata to Fields ​

Tags allow you to attach additional metadata to fields. These can define behavior, styling, or permissions. Tags are written in angle brackets (< >).

Built-In Tags ​

  1. <required>: Makes a field mandatory.
  2. <optional if>: Marks a field optional based on a condition.
  3. <sensitive>: Marks data as sensitive, enabling server-side filtering.

Example:

markdown
[Name][name]
[name]: text <required>

This marks the name field as required.

Custom Tags ​

You can define custom tags for use in controls, queries, or server-side logic. For example:

markdown
[Sensitive Info][info]
[info]: text <sensitive domain="financial">

Conditional Logic: Making Fields Dynamic ​

Fields can include conditions for visibility or optionality using JavaScript expressions. Conditions are written in curly braces ({}).

Example: Conditional Visibility ​

markdown
{hidden if status !== 'active'}
[Account Number][account_number]
[account_number]: text

This hides the account_number field unless the document’s status is 'active'.