TYPEMILL

# Field Overview

Last updated: 23.10.2019

Fields and forms for user-input are defined in YAML. YAML is a simple configuration-syntax that transforms into an object or an array. The forms can be used as public forms in the frontend (e.g. for a contactform), for plugin-settings and for theme-settings. TYPEMILL will read all your field definitions and create a user interface on the fly.

## Basics

The fields are defined in the YAML-configuration of a plugin or theme. Fields for plugins or themes start with the keywords forms and fields followed by a list of fields like this:

forms:
fields:

myfieldname:
type: text
label: My Field

anotherfield:
type: text
label: Another Field

Public forms are defined in the same way but start with the keywords public and fields:

public:
fields:

myfieldname:
type: text
label: My Field

anotherfield:
type: text
label: Another Field

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

Typically a field define consists of:

• The field-type (text, select, checkbox and more).
• A label.
• A description (displayed below the field).
• A help-text (displayed as question-mark with a infobox on hover).
• Attributes like required, placeholder and more.

## Field Types and Attributes

Right now TYPEMILL provides the following field types:

type: checkbox
type: checkboxlist
type: color
type: date
type: email
type: hidden
type: number
type: select
type: text
type: textarea
type: tel
type: url
type: fieldset
type: paragraph

TYPEMILL supports these boolean attributes (with value: true):

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

Very important: If you use required: true, than you have to add a default value for the field in the settings-definitions of your YAML-file. Otherwise the user cannot store the plugin-settings due to frontend-validation.

TYPEMILL supports the following attributes with values:

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

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. You can of course use attributes like required, placeholder, rows or cols only if these attributes are valid in HTML for the field-type.

## Examples

Check the following examples. This are only for demonstration, you can combine the attributes in all ways that are valid for html-forms.

### checkbox

Creates a simple checkbox. Note that the HTML-label that is on the right side of the checkbox is created with checkboxlabel. The label is added above the checkbox so that it is looks like the label of the other field-types.

forms:
fields:

mycheckbox:
type: checkbox
label: Label (Headline) above the checkbox
checkboxlabel: HTML-label on the right side of the checkbox
checked: true

### checkboxlist

If you want a collection of several checkboxes grouped together, then you can use a checkboxlist like this:

forms:
fields:

mylistofcheckboxes:
type: checkboxlist
options:
checkbox1: Label for checkbox 1
checkbox2: Label for checkbox 2
checkbox3: Label for checkbox 3

### color

Adds a color-picker. If you use this for a frontend-form, then the standard html5-color-picker will be used. You have to style it yourself if you dont like the standard. For theme-settings and plugin-settings an individual color-picker is used.

forms:
fields:

mycolors:
type: color
label: Background-Color
placeholder: Add hex color value like #ffffff
help: If you do not know the hex-values, then google it.
description: This will change the background color of your page.
required: true

### date

The standard HTML5-datepicker will be used.

forms:
fields:

mydate:
type: date
label: Please choose a day.

### email

Will only accept valid e-mail-formats.

forms:
fields:

myemail:
type: email
placeholder: your@email-adress.io

### fieldset

If you have a lot of fields, then you can group them together with a fieldset. You can use any fields inside a fieldset of course.

forms:
fields:

myfieldset:
type: fieldset
legend: Appears as legend or headline for the field-group
fields:
mytextfield:
type: text
label: My Label
mycheckbox:
type: checkbox
checkboxlabel: Do you want to check me?

### hidden

If you really need a hidden field, don't forget to add a value.

forms:
fields:

myhiddenfield:
type: hidden
value: Do not forget to add a value

### number

Accepts only numbers.

forms:
fields:

mynumber:
type: number
min: 1
max: 10

There is probably no usecase for this right now.

forms:
fields:

label: Enter your password

Radio-buttons are created with options like this:

forms:
fields:

options:
option1: Yes
option2: No
option3: I do not know

### select

Select-fields are also created with options like this:

forms:
fields:

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

### text

Generates a standard text-input field.

forms:
fields:

mytextfield:
type: text
placeholder: My Title
size: 50
pattern: [a-zA-Z0-9 ]
class: 'standard-title'
id: 'mytitle'

### textarea

A textarea does not accept any html-tags or code, but it always accepts markdown. If you render textarea input as markdown, you should notify the user about this (use the label or the description for this).

forms:
fields:

myfieldname:
type: textarea
rows: 5
description: You can use markdown here.
help: Check the website XYZ for a markdown reference

### tel

Gernerates a html5 input field for telephone numbers.

forms:
fields:

mytelfield:
type: tel
label: Add your phone number

### url

This field only accepts full url with a protocol like http, https, ftp or similar.

forms:
fields:

myurlfield:
type: url
placeholder: https://typemill.net

### paragraph

A paragraph is a pure text without any user-inputs. A paragraph field accepts markdown, but does not provide any other options than a value.

forms:
fields:

legalnotice:
type: paragraph
value: This is my text that should be displayed in the form.

Paragraphs can be useful for public form , e.g. if you want to add a legal notice or a longer explanation. It is also possible to use the user-input of another plugin-field for the paragraph, so the user can edit for the example the legal notice of a contact form.

## 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
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`