Field Overview

Field-definitions in YAML are a simple and straight forward way to define fields for user input in the frontend. You can define a wide range of input fields in the YAML-configuration file with a simple list of field-characteristics. TYPEMILL will read all your field definitions and create a user interface on the fly.

Field definitions are part of the plugin YAML-configuration file and they always start with the keywords forms and fields followed by a list of fields:

forms:
  fields:

    myfieldname:
      type: text
      label: My Field

    anotherfield:
      type: text
      label: Another Field

Fields can have a lot of characteristics like:

The field type like text, select or textarea.
Boolean field attributes like required, checked or disabled.
Field attributes with values like placeholder, id or pattern.
The field label, which is standard for a field.
A field help text, which is an optional explanation text for a field.

The field input of a user is also validated in the backend automatically. The backend validation is pretty tight right now, so that you should always test the input fields intensively. If you run into unwanted validation errors, please report it in github.

Field Types

Note, that field types in TYPEMILL are not equivalent to HTML field types in every case, because TYPEMILL has its own field types like a checkboxlist and textarea, which is not a HTML field type but a HTML tag. But everything will be transformed into valid HTML, of course.

TYPEMILL accepts the following field type definitions:

checkbox
checkboxlist
color
date
email
hidden
number
password
radio
select
text
textarea
tel
url
fieldset
paragraph

A simple field definition looks like this:

forms:
  fields:

    myfieldname:
      type: text
      label: My Label
      placeholder: please insert text.

Label, Help and Description

TYPEMILL supports labels, help-text and descriptions in the field definition:

Label: Will add the label for the field.
Help: Will add a question mark next to the label. Help-text is displayed on hover.
Description: Will add a description (explanation) below the field.

This is an example:

website:
  type: url
  label: Url of your website
  description: Only valid and full urls are accepted.
  help: Url should start with a protocol like 'https://' or 'http://'.

Paragraph

You can add a paragraph within your form. This is useful if you want integrate a longer text into your form, for example a legal notice. You can also add markdown-content to a paragraph.

settings:
  legalnotice: Please check the [imprint](/imprint).

forms:
  fields:
    legalnotice:
      type: paragraph

Attributes

You can add attributes to a field definition. TYPEMILL supports these boolean attributes (with value: true):

auto: true
checked: true
disabled: true
formnovalidate: true
multiple: true
readonly: true
required: true

TYPEMILL also supports the following attributes with values:

id: 'myId'
placeholder: 'my placeholder-text here'
size: 5
rows: 5
cols: 5
class: 'myClass'
pattern: '[0-9]{4}'

So a field definition can become pretty comprehensive like this:

year:
  type: text
  label: Add a year
  placeholder: '2018'
  required: true
  pattern: '[0-9]{4}'
  class: 'fc-year'
  id: 'app-year'

The pattern attribute accepts every valid regex for an input validation in the frontend. Please note, that there is also a backend validation that might conflict with your frontend validation. So please double check your validation pattern and test the input intensively.

Fields With Options

TYPEMILL supports three field types with options:

Select
Radio
Checkboxlist

The standard field type with options is a select field. You can add any options with the keyword options followed by a list of value-label-pairs like this:

theme:
  type: select
  label: Select A Theme
  options:
    edgeless: Edgeless Theme
    block: Block Theme
    classic: Classic Theme

The value on the left side (e.g. edgeless) is the value of the option, that is transported to the server. The label on the right side (e.g. Edgeless Theme) is the label of the option, that is visible for the user in the select-box.

To make your live a bit easier, you can also define options for radio field-types and for a special field type called checkboxlist. A list of radio buttons can be defined like this:

Radio:
  type: radio
  label: Select an Option
  options:
    red: Red
    green: Green
    blue: Blue
    yellow: Yellow

And a list of checkboxes can be defined like this:

Checkbox:
  type: checkboxlist
  label: Multiple Checkboxes
  options:
    first: First
    second: Second
    third: Third
    fourth: Fourth

The downside of this kind of list-definitions is, that you cannot add other attributes like 'checked' or 'required' for now. But we will make it more flexible in future.

So for now, if you need a checkbox or a radio button with further attributes, then you should define it in a traditional way like this:

SimpleCheckbox:
  type: checkbox
  label: Simple checkbox
  checkboxlabel: Please check me
  required: true
  checked: true

Please note that label appears as the headline above the checkbox and checkboxlabel appears next to the checkbox on the right as instructive label.

Using Fieldsets

If you have a lot of fields, you can group them togeter with a fieldset like this:

forms:
  fields:
    chapter:
      type: text
      label: chapter
      placeholder: Add Name for Chapter
      required: true
    MyFirstfieldset:
      type: fieldset
      legend: Last Modified
      fields:
        modified:
          type: checkbox
          label: Activate Last Modified
          description: Show last modified date at the end of each page?
        modifiedText:
          type: text
          label: Last Modified Text
          placeholder: Last Updated

The fields modified and modifiedText will then be grouped in a fieldset with the legend Last Modified.

Example for a complete yaml configuration

To sum it up, this is a complete example of a yaml configuration file for a plugin with the meta-description, a default value and a field definition for user input:

name: Example Plugin
version: 1.0.0
description: Add a short description
author: Firstname Lastname
homepage: http://your-website.net
licence: MIT
settings:
  theme: 'edgeless'
forms:
  fields:
    theme:
      type: select
      label: Select a Theme
      required: true
      options:
        edgeless: Edgeless
        block: Block
        classic: Classic

configuration file Public Forms