Terms and components

Input

An input is a JSON declaration for formulaik to show a component referenced by a the component key.

Illustration

const inputs = [
{
      component: 'input',
      id: 'email',
      label: 'Email',
      type: "string",
      params: {        
        placeholder: "email@domain.com"
      },
      validations: [
        {
          kind: "format",
          value: "email",
          message: 'Invalid email format',
        },
        {
          kind: "required",
          value: true,
          message: "This field can't be blank",
        },
      ],
    },
    {
      component: 'inputPassword',
      label: 'Password',
      id: 'password',
      type: "string",
      params: {
        autoComplete: "current-password",
        placeholder: "xxxx-xxxx-xxxx"
      },
      validations: [
        {
          kind: "required",
          value: true,
          message: "This field can't be blank",
        },
        {
          kind: "matches",
          value: /^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[a-zA-Z]).{8,}$/,
          message: 'Invalid password, must contain at least 8 characters and at most 18 characters',
        },
      ]
    },
    {
        component: 'checkbox',        
        id: 'rememberMe',
        type: "boolean",
        params: {
            label: 'Remember me',
        }
    },
    {
      component: 'submit',
      id: 'submit',
      params: {
        text: 'Continue'
      }
    },
]

• The input with the id "email" tells formulaik

  • to use the component with the email id
  • to label the component Email
  • to expect a string data type
  • to forward the params to the component, namely the placeholder customization
  • to use the validations rules:
    • format: make sure it's an email
    • required: this field is required

• The input with the id password tells formulaik

  • to use the component with the password id
  • to label the component Password
  • to expect a string data type
  • to forward the params to the component, namely the placeholder and the autoComplete customizations
  • to use the validations rules:
    • required: this field is required
    • matches: this field matches the provided regex, if not, display the error message

• The input with the id rememberMe tells formulaik

  • to use the component with the checkbox id
  • to expect a boolean data type
  • to forward the params to the component, namely the label customizations

• The input with the id submit tells formulaik

  • to use the component with the submit id
  • to forward the params to the component, namely the text (label) customizations

As you can see the inputs come as an ordered array and are fed to your Formulaik engine of choice. They are:

• Platform agnostic
• Language agnostic

This means they can easily be store in a shared repository and shared across your teams.

Component

A component is an input wrapper that adapts an actual input component to the Formulaik api.

Illustration

In the previous example we used a checkbox component, here is how we declare its component.

import React from 'react'
import FormControlLabel from '@mui/material/FormControlLabel'
import Checkbox from '@mui/material/Checkbox'

export default (props) => {
  const { 
    onValueChanged, 
    disabled,
    readOnly,
    value, 
    item: { 
        label, 
        id, 
        params 
        }} = props


  return <div className="">
    <FormControlLabel control={
      <Checkbox
        color="default"
        disabled={disabled}
        readOnly={readOnly}
        {...params}
        checked={value}
        onChange={({ target: { checked } }) => {
          onValueChanged(checked)
        }}
      />}
      label={params.label ? params.label : label} />
  </div>
}

This component adapts a Google Material UI (Mui) Switch input to Formulaik. It is available as a free community components library on Github.

• It forwards the disabled and the readOnly states to the Mui component
• It forwards the rest of the params the Mui component for a pass-through customization
• It binds the current value the Mui component prop checked
• It binds the Formulaik provided onValueChanged to the Mui component prop onChange By doing these simple bindings and forwarding, this component has now a minimal Formulaik compatibility and can be used on any Formulaik form that references a component library that includes this component.

Guide

Component Library

A Formulaik component library is a set of Formulaik compatible inputs each with a unique key. Usually it comes in a form of a repository folder with each component Formulaik's strength lies in the modularity of the components library. You can quickly switch from one component to the other by referring different component libraries.

Structure

A component library is basically a function that returns a component when given a key (the component part of an input).

Nevertheless it can be advantageous to follow a common organization across the components libraries to ease debugging, improve readability and copy or paste components. This is the recommended structure:

├── my-component-library
│   ├── index.js
│   ├── myInputA
│   ├──── index.js
│   ├── myInputB
│   ├──── index.js

Illustration

As mentioned before, we are using the Mui components library available as a free community components library on Github.

First approach

One way to serve the components is to make a basic switch on the key value and return the existing component. For instance, for our inputs, we would have:

import Input from './input'
import Submit from './submit'
import Checkbox from './checkbox'
import InputPassword from './inputPassword'

export default (props) => {
  const { type } = props
  switch (type) {
    case 'input':
      return Input  
    case 'inputPassword':
      return InputPassword
    case 'submit':
      return Submit    
    case 'checkbox':
      return Checkbox    
    default:
      return null
  }
}

Validations

A validation is a JSON representation of validation rules used by your formulaik engine. Guide