README

Mithril-UI-Form: Create dynamic forms based on JSON as input

Mithril-ui-form is a declarative framework to create forms using the front-end Mithril framework and mithril-materialized components using the materialize-css design theme.

A JSON file using a simple syntax is converted to a materialized-css form. The entered data is returned as an object.

The form supports markdown input, repeating elements a (dynamic) number of times, and conditionally displaying or disabling certain fields. If readonly is true, the form becomes readonly.

If the form is an object instead of a JSON file, you can also include a field transform (to and from) function.

Placeholders

If your form generates an object, e.g.

const obj = {
  checked: true,
  date: 1572416907856
}

And you use a very simple form:

const form = [
  { "id": "date", "type": "date", "label": "Select a date" },
  { "id": "checked", "disabled": "!date", "type": "checkbox", "label": "Check me" },
  { "type": "md",  "show":"checked", "value": "The current time is {{date:time}} and checked is {{checked:yes:no}}" }
]

m(LayoutForm, {
  form,
  obj,
}),

It would render The current time is 7:28:27 AM and checked is yes.

Default supported types

Each type supports a className property to set the input's class value (default col s12), a disabled and readonly property.

text: Input a (single) line of text.

[
  {
    "id": "firstName",
    "label": "First name",
    "type": "text"
  }
]

textarea: Input multiple lines of text, returns a string.

[
  {
    "id": "desc",
    "label": "Description",
    "type": "textarea"
  }
]

markdown: As textarea, but in readonly mode, renders the markdown.
tags: Input multiple lines of text (as chips), returns a string array.

[
  {
    "id": "hobbies",
    "label": "My hobbies",
    "type": "tags"
  }
]

email: Input an email.
url: Input a url.
md: Render the value as markdown, no label.
number: Input a number.
date: Input a date (uses date picker).
time: Input a time (uses time picker).
datetime: Input a date and time (uses date and time picker).
checkbox: Input a boolean.
switch: Input a boolean.
radio: Select one option.
options: Select one (or more) options.

[
  {
    "id": "hobbies",
    "label": "My hobbies",
    "type": "options",
    "checkboxClass": "col s3",
    "options": [
      { "id": "o1", "label": "Reading" },
      { "id": "o2", "label": "Watching TV", "disabled": true },
      { "id": "o3", "label": "Walking" },
    ]
  }
]

select: Select one (or more if multiple is set) options.

[
  {
    "id": "hobbies",
    "label": "My hobbies",
    "type": "select",
    "multiple": true,
    "checkboxClass": "col s3",
    "options": [
      { "id": "o1", "label": "Reading" },
      { "id": "o2", "label": "Watching TV" },
      { "id": "o3", "label": "Walking" },
    ]
  }
]

file: Uploads and posts a file to the provided url.

Dynamic selections

Assume you want to define a number of categories, each with certain subcategories, and the user can submit a document based on a category and subcategory, you can create a form as follows:

{
  id: 'categories',
  label: 'Categories',
  repeat: true,
  type: [
    { id: 'id', type: 'none', autogenerate: 'id' },
    { id: 'label', type: 'text', label: 'Name', className: 'col s4', tabindex: 0 },
    { id: 'desc', type: 'textarea', className: 'col s8', tabindex: 1 },
    {
      id: 'subcategories',
      label: 'Subcategories',
      repeat: true,
      tabindex: 2,
      className: 'col s8',
      type: [
        { id: 'id', type: 'none', autogenerate: 'id' },
        { id: 'label', type: 'text', label: 'Name', className: 'col s4' },
        { id: 'desc', type: 'textarea', className: 'col s8' },
      ],
    },
  ],
},
{ id: 'categoryId', label: 'Category', type: 'select', options: 'categories', className: 'col s6' },
{
  id: 'subcategoryId',
  label: 'Subcategory',
  type: 'select',
  options: 'categories.categoryId.subcategories',
  className: 'col s6',
},

Note especially the latter two fields: categoryId is a select component, whose options are defined above in categories. The subcategoryId receives its options from the subcategories of the category whose id property matches the categoryId value. The match is determined partially by the name, e.g. if instead of categoryId you would have used categoryLabel, the label field would have been matched. Since options need an id and label property, that would not work here.

Plugin system

As of version 1, the mithril-ui-form adds support for plugins. You can add your own types or overrule an existing one. For example, to include support for a rating type:

registerPlugin('rating', myRatingPlugin, myReadonlyRatingPlugin);

Since each plugin is a Mithril FactoryComponent, i.e. a function that returns a Component object with a view method, it is very easy to roll your own. See Mithril-ui-form-plugin for more information.

Migration

From version 0.9

The type: 'map' has been removed, and you now need to import it explicitly. See mithril-ui-form-leaflet-plugin. An advantage is that, in case you don't need the map, you also don't need to import and include Leaflet, Leaflet-draw and mithril-leaflet anymore. This plugin includes all requirements.

TODO

When repeat = true, min: 2, max: 5 should limit the number of repeats to 5 and require a minimum of 2.
Add pre-sets, overriding existing values.
Use this tool to create your own form schemas. E.g. a two-column layout, where you define your schema in the left column, and see the results in the right column.

Usage no npm install needed!