Ninja Power Manifesto

    bkn-form
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0-beta.25 • Public • Published

    bkn-form

    Automatic forms via Taxonomy schema.

    It uses bkn-ui and react-select internally to build its widgets.

    So, let's see how it works.

    Table of Contents

    Features

    • Renders a form automatically with all its widgets (fields) based on Taxonomy schema.
    • Renders individual form widgets to be used outside a form.

    Installation

    npm install -S -E bkn-form

    Or using yarn.

    yarn add -E bkn-form

    It has some peer dependencies, so if you not installed them, you have to.

    yarn add -E react bkn-ui react-select

    Note: check Installtion section in bkn-ui repo for more details.

    Getting Started

    Rendering

    Start by fetching a schema from Taxonomy API. Then pass this schema in <Form> component. For example:

    import * as React from 'react';
    import {Component} from 'react';
    import {Form, Schema} from 'bkn-form';
    import {TaxonomyRestService} from 'services';
     
    interface State {
      schema: Schema;
    }
     
    class MyCustomForm extends Component<{}, State> {
      state: State = {
        schema: {},
      };
     
      async componentDidMount() {
        const schema = await TaxonomyRestService.getInstance().getByName('Panel');
        this.setState({schema});
      }
     
      render() {
        const {schema} = this.state;
     
        return (
          <Form schema={schema} />
        );
      }
    }

    This will render the entire form with its widgets including category selection.

    Note: implementation details of TaxonomyRestService was omitted for brevity.

    Note 2: this example uses internal component state, but maybe this is not the best way to manage data if you are working in a large scale application. If so, you should use something like redux. To be inspired, take a look at this example.

    Dealing with data

    You can pass some data to the <Form>. That data should follow the schema pattern.

    stateState = {
      data: {
        id: '123',
        name: 'Panel name',
        // other props
      },
      schema: {},
    };
     
    render() {
      const {data, schema} = this.state;
     
      <Form
        data={data}
        schema={schema}
      />
    }

    To watch data updates, you can use onChangeFormData prop.

    render() {
      const {data, schema} = this.state;
     
      <Form
        data={data}
        schema={schema}
        onChangeFormData={this.handleDataChange}
      />
    }
     
    handleDataChange = (data: FormData) => {
      this.setState({data});
    }

    Note: see Models page for more details in FormData model.

    Submission

    <Form> renders a Submit button internally and you can listen its click events by using onSubmit prop.

    render() {
      const {data, schema} = this.state;
     
      <Form
        data={data}
        schema={schema}
        onChangeFormData={this.handleDataChange}
        onSubmit={this.handleSubmit}
      />
    }
     
    handleSubmit = (data: FormData) => {
      console.log('Form data submitted', data);
    }

    Extra-schema fields

    Sometimes we need to render some fields that doesn't belong to Taxonomy schema. It's quite simple to do this. All you need to do is to pass whatever you want as a child of <Form> component. For example:

    import {ChangeEvent} from 'react';
    import {Form, FormWidget} from 'bkn-form';
     
    // omitted code
     
    stateState = {
      data: {
        id: '123',
        name: 'Panel name',
        agree: false,
        // other props
      },
      schema: {},
    };
     
    render() {
      const {data, schema} = this.state;
     
      <Form
        data={data}
        schema={schema}
        onChangeFormData={this.handleDataChange}
        onSubmit={this.handleSubmit}
      >
        <FormWidget.InputCheck
          checked={data.agree}
          label="Privacy Terms" 
          name="agree"
          text="I agree"
          onChange={this.handleCheckboxChange}
        />
      </Form>
    }
     
    handleCheckboxChange = (e: ChangeEvent<HTMLInputElement>) => {
      const updatedData = Object.assign({}, this.state.data, {
        agree: e.target.checked,
      });
     
      this.setState({data: updatedData});
    }

    As you can see, we are using FormWidget namespace to access form widgets. See Components page for more details.

    Beautifying

    Let's import some style to make our form beautiful.

    // MyCustomForm.scss 
     
    @import "node_modules/bkn-ui/scss/theme/base";
    @import "node_modules/bkn-ui/scss/theme/grid";
    @import "node_modules/bkn-ui/scss/theme/text";
    @import "node_modules/bkn-ui/scss/components/form";
    @import "node_modules/bkn-ui/scss/components/json-debugger";
    @import "node_modules/bkn-ui/scss/components/danger-zone";
     
    @import "node_modules/bkn-form/styles";

    See Theming page for more.

    Pulling it all together

    // MyCustomForm.tsx
     
    import * as React from 'react';
    import {Component} from 'react';
    import {Form, FormWidget, Schema} from 'bkn-form';
    import {TaxonomyRestService} from 'services';
     
    interface State {
      schema: Schema;
    }
     
    class MyCustomForm extends Component<{}, State> {
      state: State = {
        data: {
          id: '123',
          name: 'Panel name',
          agree: false,
          // other props
        },
        schema: {},
      };
     
      async componentDidMount() {
        const schema = await TaxonomyRestService.getInstance().getByName('Panel');
        this.setState({schema});
      }
     
      render() {
        const {data, schema} = this.state;
     
        return (
          <Form
            data={data}
            schema={schema}
            onChangeFormData={this.handleDataChange}
            onSubmit={this.handleSubmit}
          >
            <FormWidget.InputCheck
              checked={data.agree}
              label="Privacy Terms" 
              name="agree"
              text="I agree"
              onChange={this.handleCheckboxChange}
            />
          </Form>
        );
      }
     
      handleDataChange = (data: FormData) => {
        this.setState({data});
      }
     
     
      handleCheckboxChange = (e: ChangeEvent<HTMLInputElement>) => {
        const updatedData = Object.assign({}, this.state.data, {
          agree: e.target.checked,
        });
     
        this.setState({data: updatedData});
      }
     
      handleSubmit = (data: FormData) => {
        console.log('Form data submitted', data);
      }
    }
    // MyCustomForm.scss 
     
    @import "node_modules/bkn-ui/scss/theme/base";
    @import "node_modules/bkn-ui/scss/theme/grid";
    @import "node_modules/bkn-ui/scss/theme/text";
    @import "node_modules/bkn-ui/scss/components/form";
    @import "node_modules/bkn-ui/scss/components/json-debugger";
    @import "node_modules/bkn-ui/scss/components/danger-zone";
     
    @import "node_modules/bkn-form/styles";

    That's it! This is what you need to render a basic form.

    As you may have noticed, a Back button and a JSON Debugger was rendered by <Form>, but they are not working. You can watch their events as well. Please see API Reference section for more details.

    API Reference

    Here is some wiki pages with more details.

    Contributing

    1. Create an issue describing clearly the new feature or problem.

    2. Create a branch with issue name.

    3. Improve/Fix it.

    4. Generate bundle and types by running:

      npm run build

    5. Bump version in package.json based on SemVer.

    6. Create a PR and inform what issue is closed. For example:

      Closes #1

    7. Approve and merge PR.

    8. Delete branch.

    9. Publish to npm:

      npm publish

    10. Create a tag for current version. For example:

      git tag 1.0.0

    11. Push tag to Github.

      git push --tags

    12. Write change log in tag body based on merged PRs. Example here.

    13. Be happy. =]

    Install

    npm i bkn-form

    DownloadsWeekly Downloads

    4

    Version

    2.0.0-beta.25

    License

    MIT

    Unpacked Size

    168 kB

    Total Files

    150

    Last publish

    Collaborators

    • jpbeakyn
    • nelsoneldoro
    • juanpujol
    • abraaoalves
    • falcaoaugustos
    • brunolazarus
    • hileomsi
    • murilopaixao