# bkn-form

Automatic forms via [Taxonomy](https://github.com/Beakyn/gsp-taxonomy-ui) schema.

It uses [bkn-ui](https://github.com/Beakyn/bkn-ui) and [react-select](https://github.com/JedWatson/react-select) internally to build its widgets.

So, let's see how it works.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [API Reference](#api-reference)
- [Contributing](#contributing)

## Features

- Renders a form automatically with all its widgets (fields) based on [Taxonomy](https://github.com/Beakyn/gsp-taxonomy-ui) schema.
- Renders individual form widgets to be used outside a form.

## Installation

```sh
npm install -S -E bkn-form
```

Or using _yarn_.

```sh
yarn add -E bkn-form
```

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

```sh
yarn add -E react bkn-ui react-select
```

**Note:** _check_ [Installtion](https://github.com/Beakyn/bkn-ui#installation) _section in bkn-ui repo for more details._

## Getting Started

### Rendering

Start by fetching a schema from [Taxonomy API](https://github.com/Beakyn/gsp-taxonomy-api). Then pass this schema in `<Form>` component. For example:

```tsx
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](http://redux.js.org/)_. To be inspired, take a look at_ [this example](https://github.com/Beakyn/gsp-mad-ui/blob/master/src/components/common/TaxonomyForm.tsx).

### Dealing with data

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

```tsx
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.

```tsx
render() {
  const {data, schema} = this.state;

  <Form
    data={data}
    schema={schema}
    onChangeFormData={this.handleDataChange}
  />
}

handleDataChange = (data: FormData) => {
  this.setState({data});
}
```

**Note:** _see_ [Models](#api-reference) _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.

```tsx
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:

```tsx
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](#api-reference) page for more details.

### Beautifying

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

```scss
// 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](#api-reference) page for more.

### Pulling it all together

```tsx
// 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);
  }
}
```

```scss
// 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](#api-reference) section for more details.

## API Reference

Here is some wiki pages with more details.

- [Components](https://github.com/Beakyn/bkn-form/wiki/1.-Components)
- [Models](https://github.com/Beakyn/bkn-form/wiki/2.-Models)
- [Theming](https://github.com/Beakyn/bkn-form/wiki/3.-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](http://semver.org/).
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](https://github.com/Beakyn/bkn-form/releases/tag/1.1.4).
13. Be happy. =]