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
• Installation
• Getting Started
• API Reference
• Contributing

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.

state: State = {
  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

state: State = {
  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.

• Components
• Models
• Theming

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. =]