Forem: Data Driven Forms

Introducing Material-UI component mapper for Data Driven Forms

Data Driven Forms — Thu, 14 Jan 2021 09:18:42 +0000

One of the most popular design system Material-UI is integrated to Data Driven Forms to make building React forms as fast as possible with the least amount of boilerplate. Via Data Driven Forms mui-component-mapper users can start using Material React components to write complex forms just in seconds.

About Data Driven Forms

Data Driven Forms is a open source React library that uses a data driven approach for building React forms. This approach is based on rendering JSON schemas as React forms with all needed functionality provided by the renderer. It includes features such as validation, conditional fields and many more. It helps web developers to write forms much quicker, simpler and to achieve a consistency across the whole application.

About mappers

A mapper is a set of components integrated with Data Driven Forms API. This set allows users to write forms without any need to implement their own components, so they can immediately write fully working forms with a wide range of features (displaying errors, wizard forms, etc.) You can also check the other mappers including components from Semantic UI React, Ant Design or BlueprintJS.

About Material-UI

Material-UI with more than 61k stars is one of the most popular React libraries and it provides tens of flexible components for building all types of UIs following Google's Material Design.

Provided features

Form state management, validation, conditions and much more.
Treeshaking: select between CommonJS, ESM or UMD packages to achieve the minimal bundle size.
Typescript definitions for all components.
Additional components and additional props.
Wizard forms (see below.)
Dual list selector.
All inputs properly show errors.

Provided components

TextField

Textarea

Textarea using resolveProps to dynamically change the helper text

Radio

Checkboxes

single/multiple variant

Single variant checkbox

Multiple variant checkbox

DatePicker

TimePicker

Switch

A switch with on text and off text

Select/Multiselect

Single select

Multi select

SubForm

allows to divide forms into sub groups

A form splitted to two groups

PlainText

Header and overline variants

Slider

Tabs

Wizard

branching paths
submits only visited values

DualListSelect (custom component)

allows to move options between two lists
filtering, sorting

A dual list component lets users to move values between two lists

FieldArray (custom component)

allows to dynamically add form fields into forms
i.e. registering multiple users at once

FieldArray component allows to add another fields into the form. In the GIF, you can see that this form is allowing to add more users to a users list and these users' groups can be then changed via using conditions to verify/not to verify the email.

FormTemplate

FormTemplate component provides title, description and buttons.

Error example

Using validate is it simple to set any kind of inline validation.

Installation

npm install --save @data-driven-forms/mui-component-mapper

yarn add @data-driven-forms/mui-component-mapper

Material-UI components and icons have to be installed separately. Please follow their guide.

For more information, please reach the documentation page.

Contribution

Data Driven Forms is an open source project, all community contributions are welcomed. If you encounter any issue, please let us know on GitHub issues page or open a PR. You can also follow the project on Twitter @DataDrivenForms or reach us on our Discord server.

Introducing Carbon component mapper for Data Driven Forms

Data Driven Forms — Thu, 17 Dec 2020 10:04:08 +0000

The Data Driven Forms team released Carbon component mapper that integrates IBM React Carbon components into Data Driven Forms.

About Data Driven Forms

About mappers

About Carbon Design System

Carbon Design System is a set of patterns, rules and components for building modern web applications. This system is fully open sourced and maintained by IBM.

Provided features

Form state management, validation, conditions and much more.
Treeshaking: select between CommonJS, ESM or UMD packages to achieve the minimal bundle size.
Typescript definitions.
Additional components and additional props:
all components supports helperText,
all components display error texts.
Wizard forms (see below.)

Provided components

TextField (TextInput)

Textarea

Radio

Checkboxes

single/multiple variant

Multiple variant

Single variant

DatePicker

TimePicker

including AM/PM and timezone selectors

Switch (Toggle)

Select/Multiselect

allows to lazy load initial data

Single select

Multiple select

SubForm

allows to divide forms into sub groups

PlainText

allows to render any text

Slider

Tabs

Wizard (custom component)

branching paths
interactive navigation
submits only visited values

DualListSelect (custom componet)

allows to move options between two lists
filtering, sorting

FieldArray (custom component)

allows to dynamically add form fields into forms
i.e. registering multiple users at once

FormTemplate

the form (spacing, buttons) is designed according Carbon's guidelines

Installation

npm install --save @data-driven-forms/carbon-component-mapper

yarn add @data-driven-forms/carbon-component-mapper

For more information, please reach the documentation page.

Contribution

Data Driven React forms building in multiple design systems

Data Driven Forms — Mon, 29 Jun 2020 12:37:49 +0000

This article was originally published here. Original author: Richard Všianský

Design system is a very powerful buzzword of today's application development. Each tech company is trying to achieve consistency and simple developer experience by incorporating one of them into all their applications.

Additionally, many of them are open-sourced and publicly available. To illustrate it we can mention IBM's Carbon, Google's Material, or Red Hat's PatternFly. These libraries are customizable and easy to use with many predefined components, so even small projects can use them to make their own development easier, cheaper, and faster without sacrificing a custom identity.

However, choosing the right one is particularly hard when there are so many of them. Because of that, it's a great idea to start with a simple prototype but doing it shouldn't take so much time. One tool helping with that is Data Driven Forms (DDF), a React library for rendering and managing forms using a data driven approach. This approach takes JSON data and changes them into fully functional forms. Complex forms can be 'coded' in minutes without any actual code knowledge.

Use case --- creating a form schema

Let's imagine a simple case to implement: a registration form. According to our fictional product management, the form consists of several elements users have to enter:

Nickname
Email
Password
Confirm Password
Terms confirmation

We can start directly with defining a Data Driven Forms schema according to its definition.

const schema = {
  fields: []
}

The schema is an object containing one required attribute: fields. An array of form fields. Each of these are defined by objects having just two required attributes: name and component.

const field = {
  name: ...,
  component: ...,
  ...additionalAttributes
}

Both of them are string values defining what their names exactly suggests. Component depends on a used set of components, but in libraries provided by Data Driven Forms we can find all basic form components under keys such as text-field, select, checkbox, radio, textarea, .... These components then implement their custom attributes, most of them are shared: label, helperText, options, ... . In React, attributes correspond to component props.

So, let's transform our elements to fields definitions:

Nickname

{
  name: 'nickname',
  component: 'text-field'
}

However, this is clearly not enough to satisfy (also fictional) UX requirements. There is no label and validation --- with a configuration like this, it's just a single HTML input element. Luckily, in Data Driven Forms fixing that is really simple:

{
  name: 'nickname',
  component: 'text-field'
  label: 'Nick name',
  validate: [{type: 'required'}]
}

There are introduced two new attributes: label and validate. Validate is an array of validators --- objects or functions. Data Driven Forms provide basic validation covering most cases (length, patterns), but it can be also customized by providing a function (async functions are also supported!) or using validatorMapper to define custom types. These custom types can be then used in string-based objects.

required validator is one of the implemented validators by the library, so we can use it immediately. (We could add another attribute to the field: isRequired, a boolean value that appends a required mark to the field. However, all inputs are required in our form, so it's better to put a single note to the beginning of the form. We will do it later.)

The difference between isRequired. (Material UI design)

We can use the knowledge obtained in the previous paragraph to write the same object for the email, but the email has an additional format limitation. We will use pattern validation type to enforce it.

{
  name: 'email',
  component: 'text-field',
  label: 'Email',
  validate: [{
    type: 'required'
  } ,{
    type: 'pattern',
    pattern: '[a-z0-9._%+-]+@[a-z0-9.-]+.[a-z]{2,}$',
    message: 'Not valid email'
  }],
}

Validation triggered on the email field. (Semantic UI design)

Password

{
  name: 'password',
  component: 'text-field',
  label: 'Password',
  validate: [{
    type: 'required'
   }, {
    type: 'min-length',
    threshold: 6,
   }],
  type: 'password',
  helperText: 'Password has to be at least 6 chars long'
}

A new validator type is used: min-length makes sure that the value will have a length of 6 or more. type: 'password' is a standard HTML input element type, that shows the value as dots. helperText renders additional information to the field, its position and look depends on the used design library.

The password field with helperText and password type. (BlueprintJS design)

Confirm Password

Let's do a twist here: there is a requirement that the password confirmation field will appear only if users enter some password to the field above. From the UX viewpoint, it does not make much sense, but it will nicely show another feature of Data Driven Forms: conditional fields.

{
  name: 'confirm-password',
  component: 'text-field',
  type: 'password',
  validate: [{type: 'required'}],
  label: 'Confirm your password',
  condition: {when: 'password', isNotEmpty: true}
}

Data Driven Forms provides several types of conditions --- one of them is isNotEmpty. Using this type we can make sure that users have to enter the password first. DDF also allows to nest conditions (AND, OR, NOT), so all combinations are possible.

However, we are still missing to check if the confirmation is the same as the password. As said earlier, we can do it via providing a function in the validate array or adding a custom type to in validatorMapper. We will use the second option, because we need to access all values:

const validatorMapper = {
   'same-password': () => (value, allValues) => value !== allValues.password ? 'Password do not match' : undefined
}

Notice that the validator is a function returning a function (high-order function.) This construct allow to cache results or pass additional arguments from the schema. We will use this object as a prop later. Now, we can use this type in the validate array:

...
validate: [{type: 'same-password'}]
...

Notice that we can remove the required validator as it's already checked in the initial password field.

Cross-field validation and conditional field. (PatternFly 4 design)

Terms confirmation

{
  name: 'terms',
  component: 'checkbox',
  label: 'I agree with our business terms',
  validate: [{type: 'required'}]
}

Changing the component is simple --- just replace the component string. Everything else works still the same.

Checkbox component. (PatternFly 3 design)

Final schema

Now, we can put all the fields together in the final schema with adding a title and description:

const schema = {
 title: 'Registration form',
    description: 'All fields are required',
    fields: [{
            name: 'nickname',
            component: 'text-field',
            label: 'Nick name',
            validate: [{
                type: 'required'
            }]
        },
        {
            name: 'email',
            component: 'text-field',
            label: 'Email',
            validate: [{
                    type: 'required'
                },
                {
                    type: 'pattern',
                    pattern: '[a-z0-9._%+-]+@[a-z0-9.-]+.[a-z]{2,}$',
                    message: 'Not valid email'
                }
            ]
        },
        {
            name: 'password',
            component: 'text-field',
            label: 'Password',
            validate: [{
                    type: 'required'
                },
                {
                    type: 'min-length',
                    threshold: 6
                }
            ],
            type: 'password',
            helperText: 'Password has to be at least 6 chars long'
        },
        {
            name: 'confirm-password',
            component: 'text-field',
            type: 'password',
            validate: [{type: 'same-password'}],
            label: 'Confirm your password',
            condition: {
                when: 'password',
                isNotEmpty: true
            }
        },
        {
            name: 'terms',
            component: 'checkbox',
            label: 'I agree with our business terms',
            validate: [{
                type: 'required'
            }]
        }
    ]
};

In just few minutes, we have written a fully functional and human readable form with many advanced features.

Now, let's make it work in our React project.

Using of Data Driven Forms

The first thing we have to do is to install react-form-renderer:

npm install --save @data-driven-forms/react-form-renderer

yarn add @data-driven-forms/react-form-renderer

This is the core of the Data Driven Forms library. The renderer is the component responsible for converting the schema into React components and it provides all the features we mentioned in this article.

After we install it, we can import it into our project:

import React from 'react';
import FormRenderer from '@data-driven-forms/react-form-renderer';
// if you want to treeshake the component
// import FormRenderer from '@data-driven-forms/react-form-renderer/dist/cjs/form-renderer';
const schema = { ... }; // defined earlier
const validatorMapper = { ... }; // defined earlier, not required

const App = () => {
 return(
 <FormRenderer
      schema={schema}
      onSubmit={(values, formApi) => console.log(values)}
      FormTemplate={FormTemplate}
      componentMapper={componentMapper}
      validatorMapper={validatorMapper} *// not required*
   />
 )
};

onSubmit is a submit function. Typically it would be a function making a request to API endpoint. schema is the object we created in the previous chapter. However, two props are still missing: FormTemplate and componentMapper. This is the point of this article: these two props define components the form uses. componentMapper includes components we are using in the schema: text-field, checkbox, etc. FormTemplate wraps the form, renders buttons, show a title.

We can implement our own components and templates, but Data Driven Forms offers multiple prepared libraries:

Available Data Driven Forms mappers libraries.

We call these libraries 'mappers' because they map Data Driven Forms attributes and features to libraries' props. For example, label attribute from the schema is mapped to FormLabel Material UI component.

Using of these mappers is as simple as it can be. Install them, import them and use them in the renderer component.

import React from 'react';
import FormRenderer from '@data-driven-forms/react-form-renderer';
import { FormTemplate, componentMapper } from '@data-driven-forms/mui-component-mapper';
// you can also treeshake whatever component you need
// import FormTemplate from '@data-driven-forms/mui-component-mapper/dist/cjs/form-template';
// import TextField from '@data-driven-forms/mui-component-mapper/dist/cjs/text-field';
// import Checkbox from '@data-driven-forms/mui-component-mapper/dist/cjs/checkbox';
// const componentMapper = { 'text-field': TextField, checkbox: Checkbox }

const schema = { ... }; // defined earlier
const validatorMapper = { ... }; // defined earlier

const App = () => {
 return(
    <FormRenderer
      schema={schema}
      onSubmit={(values, formApi) => console.log(values)}
      FormTemplate={FormTemplate}
      componentMapper={componentMapper}
      validatorMapper={validatorMapper}
    />
 )
};

Because all mappers' APIs are the same, we can quickly switch between them and choose the one we like the most.

However, we have to still install components libraries and their styles separately. The Data Driven Forms documentation page provides links leading to each library's installation guide or you can use examples below as starter points. Be aware that some libraries overwrites global styles, so be sure that you include only one of them at one time.

Material UI form

Live demo

BlueprintJS form

Live demo

Semantic UI form

Live demo

PatternFly 4 form

Live demo

PatternFly 3 form

Live demo

Conclusion

Using Data Driven Forms we wrote common code defining the schema of form and everything else is provided by the library. We can run all these projects and take a look at how the libraries differ from each other. All these forms are fully functional, so during prototyping, we can code the whole form and switch the design library anytime we need to.

Also, it's simple to customize each part of the form --- if you don't like the headers or buttons, just switch them in FormTemplate. Or you can replace the whole components, add your custom ones, and much more.

In addition, there are more complex components like Wizard or Select --- writing them from scratch can take hours, using them in Data Driven Forms is just as simple as using text-field.

A dual list select component provided by Data Driven Forms. (Material UI design)

If you want to use different or custom components/design library, Data Driven Forms provides a simple command line that generates the structure of the whole package, it can even add TypeScript definitions. Just runyarn generate-template inside a root folder of DDF repository and interactive CLI will guide you. Next time, we will take look at this command and making a custom mapper.

The Data Driven Forms project is fully open-sourced on GitHub. If you find this project interesting, please join our community. We are opened to all contributions and we deeply appreciate each star we get. There is also an official twitter account @DataDrivenForms you can follow to get all the latest news.

Simple data-driven way for building React forms

Data Driven Forms — Mon, 10 Feb 2020 12:01:01 +0000

A brief introduction how easy can be building React forms using data-driven approach!

Image by xresch

This article was originally published at https://medium.com/javascript-in-plain-english/data-driven-approach-to-forms-with-react-c69fd4ea7923 Origin author: Richard Všianský

Forms are undoubtedly the most basic interaction pattern between a user and a web server. From the first login to the last order confirmation, all these actions are still handled by a few HTML elements as inputs or buttons. With this high importance and the emerging power of JavaScript, forms are becoming more and more complex. Asynchronous validation and submit, dynamic elements, touch-based controls, complex multi-searchable dropdowns supporting different localization configurations and many more advanced features are slowly but surely replacing simple static HTML pages.

But how to handle these endless changes in large projects? One of them, ManageIQ, an open-source tool to manage clouds, which has been in development since 2006 to the present, includes over one hundred forms. And all are different: a majority of the forms were written in the old fashioned way of providing dynamic features by Ruby on Rails and a few are using AngularJS. However, since the technology is still moving forward and ManageIQ decided to switch to ReactJS, the team had to come up with a solution to make future development easier, more maintainable and testable.

First, the team looked at React libraries, which can handle forms. And there are plenty of them: Formik, ReduxForm, Final Form and many others. The issue was solved and provided all the needed features. These libraries are advanced and they provide everything that a developer needs. However, the developer still has to write HTML markups (despite it being in the form of JSX) and needs to use a lot of JavaScript/React code to bring all of these features to life. So, nothing is actually solved, as the troubles will emerge in the future, when the team decides to switch to another technology (maybe Svelte? *wink*)

There were many discussions about how to deal with it, but ultimately, a data driven approach was chosen as the solution. What does it actually mean? Because you have read the title, you probably have some idea, but essentially it means that instead of writing HTML markup and JavaScript code, simple data is written with no dependency on the technology used. We can also call it a declarative way to write forms. Same as in the declarative paradigm, a programmer does not need to specify how to build the form, but only what the user should see and how it should behave. Everything else is done by magic. (Not truly by magic, but by a lot of code... don't worry, we will get there.)

Sounds simple? It really is. Let me give you an example. Let's imagine we need to build a simple login page with a login name and a password. (Right now, it doesn't matter which library we choose.) First we are going to write it in a standard way:

<form onSubmit={onSubmit}>
  <input type="text" name="login">Your login name</input>
  <input type="password" name="password">Password</input>
  <button type="submit">Your login</button>
</form>

Still simple, right? And it still is. However, when a user clicks on a button without entering any information, they want to see which inputs are required.

<form onSubmit={onSubmit}>
  <input type="text" name="login">Your login name</input>
  {!login.meta.valid && 'This field is required'}
  <input type="password" name="password">Password</input>
  {!password.meta.valid && 'This field is required'}
  <button type="submit">Your login</button>
</form>

Great. All developers are happy and users too... but no, instead of showing simple text, the UX team decided to show a modal component with a warning triangle icon. Let's change the markup again... kidding, I hope you have already gotten the picture. Under normal circumstances, each change, even if it is just a small one, can be painful with a lot of code changing. It's manageable --- in a small project it's perfectly okay, but how about in a project with hundreds of forms? No, no way. Even if you end up in a situation where you are using a small number of reusable components, this approach will not enable you to use different technologies and all forms will have to be built from scratch when you decide to change it.

Let's look at how we would deal with this form in a format we are using in our React library, Data Driven Forms:

const schema = {
    fields: [{
        component: 'text-field',
        name: 'login',
        label: 'Your login name'
    }, {
        component: 'text-field',
        type: 'password',
        name: 'password',
        label: 'Password'
    }]
}

When we are converting the HTML data into JSON, we just copy its attributes to the right keys. And most of these keys are the same. The name attribute becomes name, the type is type and the label is label. The component is the name of a component from a mapper (more about it later.) Keys are simple and self-explanatory. You don't have to know anything about HTML or React and you are still able to write your own complex forms...

... oh no, we have forgotten to add the required warnings! Let's fix it.

const schema = {
    fields: [{
        component: 'text-field',
        name: 'login',
        label: 'Your login name',
 validate: [{
            type: 'required-validator'
        }]
    }, {
        component: 'text-field',
        type: 'password',
        name: 'password',
        label: 'Password',
 validate: [{
            type: 'required-validator'
        }]
    }]
}

And what about the triangle-modal stuff? Well, we don't need to change anything in the form at all. But let's wait until we get to the implementation for that. It's still time to talk about the advantages of this approach and what it brings to us.

PatternFly 4 visualization of the form using the schema. You can test it yourself here.

You have already seen that it is simple to code, is easily readable and changes can happen by the help of CTRL-F, CTRL-V with no hesitation. Also, as the name suggests, you can keep this data in a database, so a web development team and those cool dudes who work on the newest iOS application can share it and use it across different programming languages and technologies. And we don't need to talk about upgradeability anymore. Data is just data, no matter which version of React you use and no matter what format or where you decide to keep it.

Awesome, isn't it? Of course, there are some flaws that are difficult to handle by only storing information in JSON. (But not impossible!) For example, for each submit action we are still using a separate coded function, as each submit action is different. But if your team has designed its API well, you can store the API endpoint in the schema too and use it in a generic way. Using complex text components can cause another issue, because it is not possible to store React components in JSON in a database. However, even here you can still use some text format (such as markdown) and then convert the text into components you need.

Data Driven Forms is a React library used to change your data into React forms.

Data Driven Forms

Now, it is time to move into a more specific example of using the data driven approach. In the text above I mentioned our custom open source library, Data Driven Forms. It is a React module that basically handles all features you could want from a standard web form. This is possible with the help of another mentioned library, Final Form. Final Form completely handles the form state, validation and all essential stuff. If you are more interested, keep its documentation page open in another tab and continue reading!

Data Driven Forms consists of two separate components: a form renderer and a mapper. The form renderer is all provided by the Data Driven Forms and its responsibility is to parse the data into the form using Final Form and provide all the functionality, so all forms behave the same. The mapper is a different story, you can easily create your own or you can use one of three mappers provided by the Data Driven Forms teams: PatternFly 3, PatternFly 4 and Material-UI. The mapper is what the name suggests. It is a set of components which maps the provided functionality (through passed props) to React components. Nothing more, nothing less. And each mapper includes components by design libraries you see in their names.

Same data, different mapper (from the left: PatternFly 4, PatternFly 3, Material-UI)

Let's return to our previous example to remind us of how the data looks:

const schema = {
    fields: [{
        component: 'text-field',
        name: 'login',
        label: 'Your login name',
        validate: [{
            type: 'required-validator'
        }]
    }, {
        component: 'text-field',
        type: 'password',
        name: 'password',
        label: 'Password',
        validate: [{
            type: 'required-validator'
        }]
    }]
}

Now, let's take a look at how to use this schema in Data Driven Forms:

import React from 'react';
import FormRenderer from '[@data](http://twitter.com/data)-driven-forms/react-form-renderer';
import { formFieldsMapper, layoutMapper } from '@data-driven-forms/mui-component-mapper';const Form = () => (
  <FormRenderer
    schema={schema}
    formFieldsMapper={formFieldsMapper}
    layoutMapper={layoutMapper}
    onSubmit={console.log}
  />
)

So, what is happening here? FormRenderer is the component, which converts your data into the form. There are only four required props: schema is the JSON data with specific format, formFieldsMapper is a set of components which creates the form elements and has access to the form state with an ability to change it, layoutMapper is a set of a few specific components like a form wrapper or a button, which cannot be rendered in the form from the data and cannot change the form. Both of these mappers are bundled together. The last prop is an onSubmit, which is just a function, that is called after pressing Enter in the form or pressing the Submit button. There are many more props you can use, which allow more customization (onReset, onCancel, ...)

It cannot be simpler. You wrote a form you can immediately use. That's all. End of story.

Wait. Have you already written a lot of forms with a lot of custom components? Well, that's a perfect time to write your custom mapper. Below, you can see a basic example with only one component:

const TextField = ({ name, type = 'text', meta, input, label }) => {
  const { error, touched } = meta;return (<div>
    <label htmlFor={ name }>{ label }</label>
    <input type={ type } onChange={ input.onChange } value={ input.value }/>
    { touched && error }
  </div>);
};

formFieldsMapper = {
  'text-field': TextField,
};

Let's untangle it together. The component is just the basic React component you know and you love. You can notice it gets all attributes from the schema, such as name, type or label. However, there are two new props: input and meta. These props are provided by the form renderer and they are the most important props obtained by the mapper: meta is an object, which includes various metadata about the field: dirty, pristine, modified, etc. and input is an object providing value and methods to change the form state. If you are wondering where the validate attribute goes, the answer is simple --- the validation is completely handled by the form renderer and components do not need to know about it.

A wizard form created using the PatternFly 4 mapper. Different steps for each source type are defined in the JSON schema. It's easy to add new steps, remove old ones or add a completely new wizard branch. All wizard features (jumping back, switching steps, ...) are controlled by the mapper, so there is no need to implement anything in the form itself.

Done. End of another story. But in reality, it is more complex; there are more components to cover and more features to implement. This article serves as an introduction to the world of the data driven approach. I have shown you its main advantages and how simple it can be to build a form using data. Meanwhile, I kept features such as Wizard forms, asynchronous validation, nested names and many more in secret. If you want to discover these, please check out our community on GitHub or visit our documentation page, where you can get all the information you need to start.