Skip to content

Latest commit

 

History

History
390 lines (277 loc) · 13.7 KB

README.md

File metadata and controls

390 lines (277 loc) · 13.7 KB
Raw

codecov CircleCI npm version Tweet Twitter Follow

Data Driven Form logo

Data Driven Forms is a React library used for rendering and managing forms with a lot of provided features based on React Final Form.

❓ Why to use Data Driven Forms? ❓

  • All forms shared the same functionality!
  • Components are controlled in one place!
  • You can easily migrate to different sets of components!
  • All functionality is provided (see below!)

🎉 Features 🎉

  • Easily readable schema, you don't need to know any HTML or JS to be able to write your own form schemas!
  • You can use your own components or use one of our provided mappers: PatternFly 4, Material-UI, Ant Design! and more, see below!)
  • Form state manager out-of-the-box (including error states!)
  • Fully customizable (you can use your own buttons, actions, etc.)!
  • Conditional fields!
  • Custom field validation with basic set included!
  • Datatype validation!
  • Cross-field validation!
  • Asynchronous validation supported!
  • Supporting Wizard forms!
  • Supporting Final Form Field Array!
  • ... and a lot more!

📖 For more information please visit the documentation. 📖

Table of Contents

Installation

React Form Renderer

$ npm install @data-driven-forms/react-form-renderer -S
$ yarn add @data-driven-forms/react-form-renderer

Provided mappers

Material-UI Mapper

$ npm install @data-driven-forms/mui-component-mapper -S
$ yarn add @data-driven-forms/mui-component-mapper

PatternFly 4 Mapper

$ npm install @data-driven-forms/pf4-component-mapper -S
$ yarn add @data-driven-forms/pf4-component-mapper

BlueprintJS Mapper

$ npm install @data-driven-forms/blueprint-component-mapper -S
$ yarn add @data-driven-forms/blueprint-component-mapper

Semantic UI Mapper

$ npm install @data-driven-forms/suir-component-mapper -S
$ yarn add @data-driven-forms/suir-component-mapper

Ant Design Mapper

$ npm install @data-driven-forms/ant-component-mapper -S
$ yarn add @data-driven-forms/ant-component-mapper

Carbon Mapper

$ npm install @data-driven-forms/carbon-component-mapper -S
$ yarn add @data-driven-forms/carbon-component-mapper

Component libraries in mappers are external dependencies. Make sure to install them and their styles in your bundles.

Basic provided components

Provided mappers of Data Driven Forms support contains following set of components:

Any other components can be added to mapper and renderer with the form renderer. Existing components can be also overriden.

Usage

In order to Data Driven Forms in your component you need the renderer and a component mapper, which provides component mapper and form template.

import React from 'react';
import { FormRenderer, componentTypes } from '@data-driven-forms/react-form-renderer';
import { componentMapper, FormTemplate } from '@data-driven-forms/pf4-component-mapper';

const schema = {
  fields: [{
    component: componentTypes.TEXT_FIELD,
    name: 'name',
    label: 'Your name'
  }]
}

const Form = () => (
  <FormRenderer
    schema={schema}
    componentMapper={componentMapper}
    FormTemplate={FormTemplate}
    onSubmit={console.log}
  />
)

Custom mapper

You can also use custom mapper.

import React from 'react';
import { FormRenderer, componentTypes, useFieldApi } from '@data-driven-forms/react-form-renderer';

const TextField = props => {
  const {label, input, meta, ...rest} = useFieldApi(props)
  return (
    <div>
      <label htmlForm={input.name}>{label}</label>
      <input {...input} {...rest} id={input.name}/>
      {meta.error && <p>{meta.error}</p>}
    </div>
  )
}

const componentMapper = {
  [componentTypes.TEXT_FIELD]: TextField,
  'custom-type': TextField
}

const schema = {
  fields: [{
    component: componentTypes.TEXT_FIELD,
    name: 'name',
    label: 'Your name'
    type: 'search',
  }]
}

For more information, please check this page.

Mappers can be also generated by using yarn generate-template command.

Documentation

Please use our documentation site. In case of any problem, you can access documentation files directly in GitHub.

Development setup

Data Driven Forms is a monorepo that uses Lerna and yarn workspaces, so you can use all its commands as well.

Requirements

  • ○ NodeJS 16

  • ○ Unix like OS (MacOS, Linux)

We do not support developing on Windows at this moment. However, we would welcome any PR to change this.

Common commands

Install

yarn install

Build

yarn build

All packages are linked together by default, so if you run a yarn build in a package, all other packages are updated to the latest version of that package. A package has to be built first before it is used in other package.

Run a playground

Each package has a small playground package/demo, where you can test your changes.

cd packages/pf3-component-mapper
yarn start

Run documentation

The documentation is a server-side rendered React application based on NextJS framework.

cd packages/react-renderer-demo
yarn dev

How to clean node_modules

yarn lerna clean
rm -rf node_modules

Cleaning built files

To clean built files use following command: (This script is also ran automatically before each build.)

yarn clean-build

Tests

Tests can be ran from core folder or from specific package.

yarn test

yarn test --watchAll packages/pf4-component-mapper

# or

cd packages/pf4-component-mapper
yarn test

Checklist before you send a PR

Please follow following checklist if you are going to open a PR. It will help you make the PR finished.

Build passes

Run yarn build in root folder to build all packages. You can run this command only in package you changed. All packages are linked by default, you have to build them first.

Linter passes

Run yarn lint in root folder to check if the code is correctly formatted. You can use yarn lint --fix to automatically correct issues.

Write tests

All new code should be properly tested. Run yarn test in root folder to test all files. Check codecoverage report to see uncovered lines of code. We are using Jest and React Testing Library.

Documentation update

If you introduce a new feature, you should document this change in our documentation. The documentation is located in react-renderer-demo package and it is a web application based on NextJS. We do not write tests for the documentation.

yarn dev starts a local version of the documentation.

yarn build prepares files for deployment.

yarn serve emulates the web application running in local emulator.

Correct commit message

A correct commit message is important, because we are using semantic release to automatically releease new versions. These messages are also used in our release notes, so other users can see what is being changed.

My change introduces a new feature

Prefix your commit message with feat and specify the package that is being changed. An example: feat(pf4): a new dual list integration. If you change multiple packages, you can use feat(common): ... or feat(all): ....

My change fixes a bug or technical debt

Prefix your commit message with fix. Otherwise, the same rules apply. An example: fix(pf4): fixed missed proptype in select.

My change does not change any released package

If your change does not change any of the released packages, you can simple just descibe the change, an example: Fix button on documenation example page. This also applies for any change in the documentation repo.

My change introduces a breaking change

We are trying to avoid breaking changes. Please, open an issue and discuss the issue with us, we will try to come up with alternative options.

Useful links

Contribution

We welcome any community contribution. Don't be afraid to report bug or to create issues and pull-requests! 🏆

LICENSE

Apache License 2.0