formoosejs v2.0.0

Formoose

Formoose is a lightweight, flexible JavaScript library for form validation. It supports a wide range of validation rules, including custom rules, and is designed to be easy to use and extend.

Features

• Rich validation rules: includes common rules like email, passwords, numbers, dates, checkbox, and radio groups.
• Custom Messages: Easily set custom error messages for each rule.
• Grouped Input Support: Validate grouped inputs like radio buttons and checkboxes.
• Event Based: Custom events (formoose:submitting, formoose:submitted) to integrate validation seamlessly with your workflow.
• Easy Error Display: Automatically displays error messages next to invalid inputs.
• Highly Configurable: Customize or extend rules to meet specific requirements.

Installation

npm i formoosejs

Alternatively, you can clone the repository and put the dist directory in your project.

Build

The dist directory contains two pre-built versions of Formoose to accommodate different module systems and environments:

1. formoose.es.js

This build is an ES Module (ESM) version of Formoose, designed for modern JavaScript environments that support the import and export syntax natively.

• Use Case: Recommended for modern browsers and build tools like Webpack, Vite, or Rollup that handle ESM modules efficiently.
• How to Use: Import it directly into your JavaScript project:

  import Formoose from './dist/formoose.es.js';

  const formoose = new Formoose();

2. formoose.umd.js

This build is a Universal Module Definition (UMD) version, which works in both browser and Node.js environments. It is compatible with both CommonJS (require) and AMD module systems, as well as directly in <script> tags.

• Use Case:

  Ideal for projects using older build tools or requiring compatibility with legacy environments. Also suitable for quick integration using <script> in HTML files.

• How to Use:

  • Browser (via script tag):

    <script src="./dist/formoose.umd.js"></script>
    <script>
        const formoose = new Formoose();
    </script>

  • Node.js (CommonJS):

    const Formoose = require('./dist/formoose.umd.js');
    
    const formoose = new Formoose();

Choose the Right Build

Both builds are minified for performance, ensuring fast loading and minimal overhead in production environments. Choose the one that best fits your project's requirements.

Usage

1. Add the data-formoose-form attribute to your form:

<form data-formoose-form>
    ...
</form>

2. Initialize Formoose in your JavaScript:

document.addEventListener("DOMContentLoaded", () => {
    const formoose = new Formoose();
});

Optionally you can provide a form to Formoose or it will find the forms by data-formoose-form attribute

document.addEventListener("DOMContentLoaded", () => {
    const formoose = new Formoose(document.getElementById("formId"));
});

3. Add rules to input elements

<form data-formoose-form>
    <input type="text" name="name" data-formoose-required>
    <input type="email" name="email" data-formoose-required data-formoose-email>
    <input type="password" name="password" data-formoose-required data-formoose-min="8">
    <button type="submit">Sign Up</button>
</form>

optionally you can customize a validation message for each validation rule by adding the attribute data-formoose-{rule}-message where {rule} is a rule name

<input type="email" name="email" data-formoose-required data-formoose-required-message="The email is required">

Handling Events

Formoose emits custom events during the form submission lifecycle:

• formoose:submitting — Before form submission.
• formoose:submitted — After form submission.
• formoose:success - After validation succeeds.
• formoose:error - After validation fails.

document.addEventListener("formoose:submitted", (event) => {
    console.log("Form submitted:", event.detail);
});

Validating Group Elements (Radio, Checkbox)

Wrap <fieldset> element around radio and checkbox elements

<fieldset>
    Man: <input type="radio" name="sex" value="Man">
    Woman: <input type="radio" name="sex" value="Woman">
    Other: <input type="radio" name="sex" value="Other">
</fieldset>

Styling

Formoose does not impose any styles, you are free to style error elements as per your website color theme, Formoose adds the following classes for flexibility:

Extend Formoose

Formoose allows you to define custom validation rules to handle specific use cases that aren't covered by the built-in rules. Adding a custom rule is simple and follows these steps:

Define Your Rule

const formoose = new Formoose();

formoose.addRule("max", (value, input) => {
    return value.length <= parseInt(input.getAttribute("data-formoose-max"));
}, (input) => `The value must be less than or equal to ${input.getAttribute("data-formoose-max")} characters`);

Use the Rule in Your Form

<input type="text" name="username" data-formoose-max="16">

Validation Rules