guardzilla v0.0.2

FormGuardJs Class Documentation

This is a comprehensive guide to the FormGuardJs class, inspired by Laravel’s Validation but tailored for JavaScript applications. The class provides a rich set of validation rules and supports custom validation callbacks.

Table of Contents

• Introduction
• Installation
• Validation Rules Reference
  • Required Rules
  • Data Type Rules
  • String Formatting Rules
  • Special Rules
  • Comparison Rules
  • Miscellaneous Rules
• Usage
  • Basic Examples
  • Advanced Examples
• Customizations
  • Custom Messages
  • Custom Attributes
  • Custom Rule Callbacks

Introduction

The FormGuard class allows you to validate form data based on a variety of built-in rules. You can define your validation rules, custom error messages, and attributes that map to human-readable names for your fields.

Installation

You can install the FormGuard in your project by including the FormGuard class in your JavaScript/TypeScript application.

Usage

Basic Examples

Here’s a simple example that validates the name and age fields with basic rules:

const rules = {
    name: 'required|min:5',
    age: 'required|integer',
};

const messages = {
    nameRequired: 'Name is required',
    nameMin: 'Minimum value is :min',
    ageRequired: 'Age is required',
    ageInteger: 'Age value is not an integer',
};

const attributes = {
    name: 'Full Name',
    age: 'Age',
};

FormGuard.make(rules, messages, attributes);
    .then(({ validated, formData }) => {
        // Handle success
    })
    .catch(error => {
        console.error(error);
    });

Rules as Array

You can also pass validation rules as an array:

const rules = {
    name: ['required', 'min:5'],
    age: ['required', 'integer'],
};

FormGuard.make(rules, messages, attributes)
    .then(({ validated, formData }) => {
        // Handle success
    })
    .catch(error => {
        console.error(error);
    });

Rules as Object

If you prefer, you can define your validation rules as objects:

const rules = {
    name: { required: true, min: [5] },
    age: { required: true, integer: true },
};

FormGuard.make(rules, messages, attributes)
    .then(({ validated, formData }) => {
        // Handle success
    })
    .catch(error => {
        console.error(error);
    });

Custom Rule Callbacks

Define Custom Callbacks

FormGuard.add('exists', ({value, fails}) => {
    if (!value) {
        fails('Name already exists');
    }
});

FormGuard.add('exists', ({value, fails}) => {
    return value !== false;
});

Definine Custom Callbacks with options

FormGuard.add({
    exists: {
        fn: ({value, fails}) => value,
        message: 'Name already exists'
    },

    // Add more custom Rules
});

Defining custom Rules globally

go to ./core/config.js, inside customRules define the rules like

{
    customRules: {
        ruleName: {
            fn: () => {}, // Define the callback here
            message: 'Custom Message'
        }
    }
}

FormGuard.exists = ({ value, fails }) => {
    if (!value) {
        fails('Name already exists');
    }
};

You can use custom validation callbacks as part of the rules:

// Usages of custom callbacks
const rules1 = {
    name: ['required', 'min:5', FormGuard.exists],
    age: 'required|integer',
};

// or as an item in an array 

const rules2 = {
    name: ['required', 'min:5', 'exists'],
    age: 'required|integer',
};

// or as a string:

const rules3 = {
    name: 'required|min:5|exists',
    age: 'required|integer',
};


FormGuard.make(rules1, messages, attributes).then().catch();
FormGuard.make(rules2, messages, attributes).then().catch();
FormGuard.make(rules3, messages, attributes).then().catch();
    

Or you can define an inline function as a callback:

const rules = {
    name: ['required', 'min:5', ({ value, fails }) => {
        if (!value) {
            fails('Name already exists');
        }
    }],
    age: 'required|integer',
};

FormGuard.make(rules, messages, attributes);
    .then(({ validated, formData }) => {
        // Handle success
    })
    .catch(error => {
        console.error(error);
    });

Validation Rules Reference

Required Rules

Data Type Rules

String Formatting Rules

Special Rules

Comparison Rules

Miscellaneous Rules

Custom Messages

You can customize error messages using the messages parameter when creating a new FormGuard instance. Messages can use placeholders like :attribute, :min, or :max to dynamically insert values.

const messages = {
    nameRequired: 'Name is required',
    nameMin: 'Name must be at least :min characters',
    ageRequired: 'Age is required',
    ageInteger: 'Age must be an integer',
};

Custom Attributes

You can customize attribute names for friendlier error messages by passing an attributes object:

const attributes = {
    name: 'Full Name',
    age: 'Age',
};

This allows the error messages to display Full Name instead of name.

Custom Callbacks

Registering a Custom Rule

You can register custom validation rules using functions. Here's an example of creating and using a custom validation rule:

FormGuard.exists = ({ value, fails }) => {
    if (!value) {
        fails('This value does not exist.');
    }
};

const rules = {
    name: ['required', 'exists'],
};

FormGuard.make(rules, messages, attributes)
    .then(({ validated, formData }) => {
        // Handle success
    })
    .catch(error => {
        console.error(error);
    });

Inline Callback Example

You can also provide inline custom rules as callbacks:

const rules = {
    name: ['required', ({ value, fails }) => {
        if (value !== 'allowed_name') {
            fails('This name is not allowed.');
        }
    }],
};

FormGuard.make(rules, messages, attributes)
    .then(({ validated, formData }) => {
        // Handle success
    })
    .catch(error => {
        console.error(error);
    });

Or you can define an inline function as a callback:

const rules = {
    name: ['required', 'min:5', ({ value, fails }) => {
        if (!value) {
            fails('Name already exists');
        }
    }],
    age: 'required|integer',
};

FormGuard.make(rules, messages, attributes)
    .then(({ validated, formData }) => {
        // Handle success
    })
    .catch(error => {
        console.error(error);
    });

Using defineForm To Validate Form

FormGuard.defineForm(
    formSelector,
    rules,
    messages,
    attributes
);

Usage:

    <!--index.html-->
    <html>
        <head>
            ...
            <script src="http://npmpackagelist.org/formguard.js"></script>

        </head>
        <body>

            <form method="POST" action="/api/login" id="signup-form">
                <input type="text" name="email"/>
                <input type="text" name="first_name"/>
                <input type="text" name="last_name"/>
                <input type="text" name="username"/>
                <input type="password" name="password"/>
                <input type="password" name="password_confirmation"/>
                <button type="submit">Sign Up</button>
            </form>

        </body>
        <script src="./index.js"></script>
    </html>

// index.js
const rules = {
    email: 'required|email',
    first_name: 'required|alpha',
    last_name: 'required|alpha',
    password: 'required|password|confirmed'
};

const messages = {
    emailRequired: 'Email Address is required',
    first_nameRequired: ':attribute is requred',
};

const attributes = {
    first_name: 'First Name',
    last_name: 'Last Name',
};


const validator = FormGuard.defineForm(
    'signup-form',
    rules,
    messages,
    attributes
);

validator
.on('submitted', (response, {setAuth}) => {
    setAuth(response.token);
})
.on('submit', ({validated, formData}) => {

})