formez v0.1.4

Formez

Formez is a React component which provides a declarative way to handle input validation and input side effects.

Table of contents

• Installation
• Usage
• Basic example
• Constraints
  • Presence
  • Value
  • Format
  • Length
  • Numericality
  • Validate function
• Related inputs
• Trigger inputs

Installation

Use the package manager npm to install it.

npm i formez

Usage

You can find simple examples inside src/example, to run the example application just run npm run start.

Basic example

render() {

    return (
        <>
        <h1 className="text-center">BasicExample</h1>

        <Formez
            onFormInputsChanged = {(updatedInputs) => {
                console.log(updatedInputs);
            }}
            constraints = {new Map([
                ["required_field", {presence: true}]
            ])}
            submitBtnId = "submitBtn"
            onFormSubmit = {() => {
                console.log("Form submitted");
            }}
            >
            <div>
                <div>
                    <label htmlFor="required_field">Required field:</label><br></br>
                    <input type="text" id="required_field" name="required_field"></input><br></br>
                </div>
            </div>
        </Formez>

        <button id="submitBtn" className="btn btn-large btn-primary  my-2">
            Submit
        </button>

        </> 
    );
}

Constraints

Use constraints to perform validation on form inputs.

let formConstraints = new Map();
//... Add form constraints ...

<Formez
    //...
    constraints = {formConstraints}
    ///...
    >
     {formBody}
</Formez>

Presence

formConstraints.set("required_field", {presence: true});

Value

formConstraints.set("value_constraint", {
    value: {
        val: "15",
        message: "Expected 15"
    }
});

Format

formConstraints.set("format_regex_constraint", {
    format: {
        pattern: /^(.+)@(.+)$/,
        message: "The email format is not valid"
    }
});

Length

formConstraints.set("length_equal_constraint", {
    length: {
        equal: 5,
        message: "Length must be 5"
    }
});

formConstraints.set("length_max_constraint", {
    length: {
        maximum: 5,
        message: "Max length is 5"
    }
});

Numericality

formConstraints.set("numericality_gt_constraint", {
    numericality: {
        greaterThan: 15,
        message: "Value must be greater than 15"
    }
});

formConstraints.set("numericality_only_integer_constraint", {
    numericality: {
        onlyInteger: true,
        message: "Only integers allowed"
    }
});

Validate function

formConstraints.set("validate_function_constraint", {
    validate_function: {
        f: (value) => {

            let errorMessage = "Error message from function";

            if(value?.includes("error")) {
                return { 
                    "isValid": false, 
                    "message": errorMessage 
                };
            } else {
                return { 
                    "isValid": true
                };
            }
        }
    }
});

Related inputs

Sometimes it's required that selecting a specific value of one input, a default value of another input should be selected. Hence, the value change of the input produces a side effect on another input. We can say that these are related inputs.

Use bunchOfrelatedInputs to declare related inputs inside the form.

<Formez
// ...
bunchOfrelatedInputs = {[
              {
                  name: "main_field",
                  relatedInputs: [
                            {
                              name: "first_related_input",
                              value: "default1",
                             },
                      		{
                                name: "second_related_input",
                                value: "default2",
                                //...
                             },
								// ...
                  ]
               }
    ]}
	>
    {formBody}
</Formez>

Change always

{
	name: "related_input",
	value: "default value",
}

Specify value by a function

{
    name: "related_input",
    func: (value) => { return value.toUpperCase() },
}

Change ifInputEquals

{
    name: "related_input",
    ifInputEquals: "Foo",
    value: "Foo was selected",
}

Change ifInputNotEquals

{
    name: "related_input",
    ifInputNotEquals: "3",
    value: "A value other than 3 has been selected",
}

Trigger inputs

Sometimes it's required that the value change of an input triggers a function call.

Use bunchOfTriggerInputs to declare trigger inputs inside the form.

<Formez
	//...
	bunchOfTriggerInputs = {[
                        {
                            name: "trigger_input",
                            triggerFunctions: [
                                {
                                    func: (value) => {
                                        // ...                                            
                                    }
                                },
                                {
                                    ifInputEquals: //...
                                    func: (value) => {
                                        //...                                         
                                    }
                                },
                                //...
                            ]
                        },
       //...
    ]}
	>
    {formBody}
</Formez>

Trigger always

{
  func: (value) => {
    console.log("triggered");                                            
  }
}

Trigger ifInputEquals

{
  func: (value) => {
    console.log("triggered");                                            
  },
  ifInputEquals: "trigger",
}

Trigger ifInputNotEquals

{
  func: (value) => {
    console.log("Input is not hello");                                            
  },
  ifInputNotEquals: "hello",
}