@kandor/kandor-react-native-form-builder v1.0.0

react-native-form-builder

Features

• Generate Form Fields UI
• Manage, track state & values of fields
• Automatically manages focus to next field on submit (TextInput)
• Handle all keyboard related problems smartly
• Supports custom validations & nested forms
• Uses Nativebase components

Getting Started

• Installation
• Basic Usage
• Properties
  • Basic
  • Methods
  • Form Fields
    • Field Structure
    • Common Properties to all Fields
    • Field Types
      • TextInput
      • Picker
      • Switch
      • Date
      • Select
  • Nested Forms
  • Prefilling Form's Values
  • Add Custom Validations
  • Customize Your Form
  • Add custom components
  • Add custome error component
• Example

Installation

$ npm i @kandor/react-native-form-builder --save

Basic Usage

• Install react-native first

$ npm i react-native -g

• Initialization of a react-native project

$ react-native init myproject

• Then, edit myproject/index.ios.js, like this: Example: Login Form consisting of three fields (username, password, country)

import React, { Component } from 'react';
import { AppRegistry } from 'react-native';
import { View, Text, Button } from 'native-base';
import GenerateForm from 'react-native-form-builder';

const styles = {
  wrapper: {
    flex: 1,
    marginTop: 150,
  },
  submitButton: {
    paddingHorizontal: 10,
    paddingTop: 20,
  },
};
// These Fields will create a login form with three fields
const fields = [
  {
    type: 'text',
    name: 'user_name',
    required: true,
    icon: 'ios-person',
    label: 'Username',
  },
  {
    type: 'password',
    name: 'password',
    icon: 'ios-lock',
    required: true,
    label: 'Password',
  },
  {
    type: 'picker',
    name: 'country',
    mode: 'dialog',
    label: 'Select Country',
    defaultValue: 'INDIA',
    options: ['US', 'INDIA', 'UK', 'CHINA', 'FRANCE'],
  },
];
export default class FormGenerator extends Component {
  login() {
    const formValues = this.formGenerator.getValues();
    console.log('FORM VALUES', formValues);
  }
  render() {
    return (
      <View style={styles.wrapper}>
        <View>
          <GenerateForm
            ref={(c) => {
              this.formGenerator = c;
            }}
            fields={fields}
          />
        </View>
        <View style={styles.submitButton}>
          <Button block onPress={() => this.login()}>
            <Text>Login</Text>
          </Button>
        </View>
      </View>
    );
  }
}

AppRegistry.registerComponent('FormGenerator', () => FormGenerator);

Properties

Basic

Methods:

Currently, these methods are available in FormBuilder, you can access them by using ref property.

getValues

To extract the values of form fields. Returns: An object consisting of field values (fieldName: value). for e.g

{
  username: 'brandon@kandor.io'
  password: 'Password'
}

setValues

Forcefully set values for particular fields. Parameters: An object of key value pairs(name: value). name: Field name for which value has to be set. value: Value for that particular field For e.g

{ name1: value1, name2: value2, .....}

resetForm

Reset Form values as well as errors.

setToDefault

Forcefully set values to default for particular fields. Parameters: An array of strings, where every string is the name of a field for which value has to be set as default value. For e.g

[fieldName1, fieldName2, fieldName3 .....]

Form Fields

Field Structure

A field is an object which has the properties required to generate it. It looks something like that :

{
  type: 'text',
  name: 'user_name',
  label: 'Username'
}

Common Properties to all Fields

These properties are applicable on all fields.

Field Types

TextInput

Supports all these kind of types :- text, password, email, url, number

Extra Properties

Value Type : String ( Except for type number )

Picker

type: picker Uses native picker

Extra Properties

Value Type : String

Default Value Type :

You can set default value as a string which must be present in available options. For e.g If options are 'CAR', 'BIKE', 'BICYCLE' then you can define defaultValue = 'BIKE'

Switch

(type: switch) It's an implement of React Native switch component.

Value Type : Boolean

Date

(type: string)

Extra Properties

Value Type : String

Default Value Type : string or JS Date object

Select

Extra Properties

Value Type : Array of Strings or Objects

Array of Strings

For e.g. options = ['CAR', 'BIKE', 'BICYCLE']

Array of Objects

If you're using array of objects then please don't forget to define these properties:

objectType: true,
labelKey: 'name', // For Below example
primaryKey: 'id,  // For Below example

For e.g.

options: [
        {
          id: 1,
          name: 'CAR',
        },
        {
          id: 2,
          name: 'BIKE',
        },
        {
          id: 3,
          name: 'BICYCLE',
        },
      ]

Default Value Type : string or JS Date object

In case of object values:

defaultValue: [{
        id: 3,
        name: 'brandon',
        title: 'Founder/Principle',
      }],

In case of string values:

defaultValue: ['CAR', 'BIKE'],

Nested Forms

(type: group) Form Builder also supports nested forms, some times you need to wrap all of your form values in an object or we can say that you have some nested fields, in this case you can define group fields. An example will better explain it:

{
      type: 'group',
      name: 'address',
      label: 'Address',
      fields: [
        {
          type: 'text',
          name: 'city',
          label: 'City',
        },
        {
          type: 'picker',
          name: 'country',
          label: 'Country',
          defaultValue: 'INDIA',
          options: ['US', 'INDIA', 'UK', 'CHINA', 'FRANCE'],
        },
      ],
    },

Value Type : Object

For above example the return value object will be something like that:

{ city: 'Indianapolis', country: 'United States' }

Default Value Type : Object

You can set default value for above example like that:

{ city: 'Newyork', country: 'US' }

Prefill Form Values

This feature of formBuilder is very helpful in case of edit mode i.e if you want to edit the values of a form then you can easily prefill the form by using formData prop. For e.g

formData = {
  first_name : 'Jamie',
  last_name: 'Lannister',
  house: 'Lannister',
  status: 'Slain'
}

Custom Label for Inputs For Small Screens

• In some cases, where labels and values are both of signficant length, they will not fit in one line.
• Also, the label is not displayed after entering a value into a Text Input field, resulting in completed forms not showing the questions asked.
• If label is needed to be displayed, the prop, customTopLabel can be added to the props object, passed to the input. This must be a string.

Add Custom Validations

It's very easy to add your custom validations & error messages with FormBuilder.All you need to do is define a function & pass it as customValidation prop.

For e.g.

 function validate(field) {
   let error = false;
   let errorMsg = '';
   if (field.name === 'username' && !(field.value && field.value.trim())) {
     error = true;
     errorMsg = 'Username is required';
   }
   if (field.name === 'password' && !(field.value && field.value.trim())) {
     error = true;
     errorMsg = 'Password is required';
   }
   return { error, errorMsg };
 }

Note: Always return an object which will have two entities error type of boolean & errorMsg type of string.

Customize your form

• Eject Theme by running this command

node node_modules/@kandor/react-native-form-builder/ejectTheme.js

It will create a file named form-theme.js in your project's root folder.

Customize your theme.

Import theme from form-them.

Use it by passing as theme prop.

import theme from '../form-theme';
....
 <GenerateForm
  ref={(c) => { this.formGenerator = c; }}
  theme = {theme}
  ....
  />

Add Custom Components

Build your custom type's components & handle them easily with the help of form builder. Use the customComponents prop of form builder.

Prototype

It's an object of key value pair where key will be the type of the component & value will be your custom Component. customComponents = { type1: {component: ComponentName1, props: Props }, type2: {component: ComponentName2} .....}

How To Use

• Define your custom type in field's object.
• Form builder extends the props of your component by adding some extra props.
• You can also pass some extra props in your custom components.
• In your component you can access these props to handle the state of the field.

Add Custom Error Component

• Now you can use your custom error component to display error messages.
• In your custom component you will receive two props attributes & theme variables.
• You can access the error & error message as a property of the attributes object.