日本語版READMEはこちら

Form validation library

1. Installation
2. Basic Usage
3. Available Settings
4. Available Rules
5. Validation Timing
6. CSS Classes
7. License

Install with npm:

npm install formruler

Or include it directly in HTML:

<script src="path/to/formruler.js"></script>

To use this library, follow these steps:

1. Include jQuery and the FormRuler plugin in your HTML file.
2. Add the appropriate name attributes and invalid-feedback class elements to each input element in the form.
3. Call the formruler() method in JavaScript, setting validation rules and messages.

Here is a specific example:

<form id="myForm">
    <div class="form-group">
        <label for="username">Username</label>
        <input type="text" name="username" class="form-control">
        <div class="invalid-feedback">Error message goes here.</div>
    </div>
    <div class="form-group">
        <label for="email">Email</label>
        <input type="email" name="email" class="form-control">
        <div class="invalid-feedback">Error message goes here.</div>
    </div>
    <button type="submit" id="submitBtn">Submit</button>
</form>

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="path/to/formruler.js"></script>
<script>
$(document).ready(function() {
    $('#myForm').formruler({
        rules: {
            username: {
                required: true,
                minLength: 3,
                maxLength: 20
            },
            email: {
                required: true,
                email: true
            }
        },
        messages: {
            username: {
                required: "Username is required",
                minLength: "Username must be at least 3 characters",
                maxLength: "Username must be no more than 20 characters"
            },
            email: {
                required: "Email is required",
                email: "Please enter a valid email address"
            }
        },
        triggerButtonId: "submitBtn",
        onValid: function() {
            console.log("Form is valid");
            // Handle form submission here
        },
        onInvalid: function() {
            console.log("Form is invalid");
            // Handle errors here
        }
    });
});
</script>

In this example:

• Each input element in the form has a name attribute (e.g., username and email).
• The rules object defines the validation rules for each name attribute.
• The messages object defines the error messages for each rule.
• The triggerButtonId specifies the ID of the button that triggers form submission.
• The onValid and onInvalid callbacks define the actions to take based on validation results.

Defines the validation rules to apply to each field in the form. This ensures that the data entered by users meets the expected format or conditions.

The rules option specifies an object that defines the validation rules for each field in the form. Each field's name is the key, and the rules for that field are defined as an object.

$('#myForm').formruler({
    rules: {
        username: {
            required: true,
            minLength: 3,
            maxLength: 20
        },
        email: {
            required: true,
            email: true
        },
        age: {
            numeric: true,
            min: 18,
            max: 100
        }
    }
});

Rule	Example	Description
required	required: true	The field cannot be empty. Triggered if the value is empty or whitespace only.
minLength	minLength: 3	Minimum length. Specifies the minimum number of characters.
maxLength	maxLength: 10	Maximum length. Specifies the maximum number of characters.
rangeLength	rangeLength: [3, 10]	Length must be within the range. Defined as an array [min, max].
email	email: true	Must be a valid email address. Uses standard email format.
url	url: true	Must be a valid URL. Checks standard URL formats (e.g., http, https, ftp).
numeric	numeric: true	Must be a number (integer or decimal). Allows numbers and decimal points.
integer	integer: true	Must be an integer. Allows only positive or negative integers.
min	min: 18	Minimum value. Specifies the minimum allowable value.
max	max: 65	Maximum value. Specifies the maximum allowable value.
range	range: [18, 65]	Value must be within the range. Defined as an array [min, max].
pattern	pattern: "^[a-zA-Z0-9]+$"	Must match the regular expression pattern. Defines the regex pattern to match.
alphaNum	alphaNum: true	Must contain only alphanumeric characters. Special characters and spaces are not allowed.
fullWidthChars	fullWidthChars: true	Must contain only full-width characters. Checks for full-width Unicode characters.
noNumbers	noNumbers: true	Must not contain numbers. Prohibits any numeric characters in the input.
phone	phone: true	Must be a valid phone number. Checks for standard phone number formats.
postalCode	postalCode: true	Must be a valid postal code. Checks for standard postal code formats (e.g., 123-4567).
date	date: true	Must be a valid date in YYYY-MM-DD format. Checks for standard date formats.
dateRange	dateRange: ["#startDate", "#endDate"]	Must be a date within the specified range. Defined as an array of selectors [startDateSelector, endDateSelector].
timeRange	timeRange: ["#startTime", "#endTime"]	Must be a time within the specified range. Defined as an array of selectors [startTimeSelector, endTimeSelector].
validOption	validOption: ["option1", "option2"]	Must be one of the specified options. Defined as an array of allowed values.
checkbox	checkbox: true	The checkbox must be checked. Checks if the checkbox input is checked.
blockFullWidth	blockFullWidth: true	Prevents the input of full-width characters. Prohibits full-width Unicode characters.
blockHalfWidth	blockHalfWidth: true	Prevents the input of half-width characters. Prohibits standard ASCII characters.
eitherOrBothRequired	eitherOrBothRequired: "#otherField"	Both fields must be empty or either one or both must be filled. Apply this rule to both fields.
bothOrNoneRequired	bothOrNoneRequired: "#otherField"	Both fields must be empty or both must be filled. Apply this rule to both fields.

Defines custom error messages to display when validation errors occur. This makes it easier to convey errors to users in a clear and understandable way.

The messages option specifies an object that defines custom error messages for each rule for each field. It has the same structure as the rules option but sets the error message strings as the values.

$('#myForm').formruler({
    messages: {
        username: {
            required: "Please enter a username",
            minLength: "Username must be at least {minLength} characters",
            maxLength: "Username must be no more than {maxLength} characters"
        },
        email: {
            required: "Please enter an email address",
            email: "Please enter a valid email address"
        },
        age: {
            numeric: "Age must be a number",
            min: "You must be at least {min} years old",
            max: "You must be no more than {max} years old"
        }
    }
});

• Placeholders such as {minLength}, {maxLength}, {min}, and {max} are automatically replaced with the corresponding rule values in the message.
• Default error messages are used if custom messages are not set.

Defines custom validation functions to meet specific validation requirements that are not covered by standard validation rules.

The customValidators option specifies an object that defines custom validation functions. Each validator's name is the key, and the corresponding function is the value.

$('#myForm').formruler({
    customValidators: {
        evenNumber: function(value, input) {
            return {
                isValid: parseInt(value) % 2 === 0,
                message: "Please enter an even number"
            };
        },
        passwordStrength: function(value, input) {
            const strongRegex = new RegExp("^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.*[!@#\$%\^&\*])(?=.{8,})");
            return {
                isValid: strongRegex.test(value),
                message: "Password must be at least 8 characters long and include uppercase, lowercase, number, and special character"
            };
        }
    },
    rules: {
        evenField: {
            evenNumber: true
        },
        password: {
            passwordStrength: true
        }
    }
});

• Custom validator functions receive the input value (value) and the input element (input) as arguments.
• Functions must return an object with isValid (boolean) and message (error message) properties.

Customizes the elements that display error messages. This allows error messages to be displayed in locations other than the default.

The feedbackSelectors option specifies an object that defines the selectors for elements to display error messages for each field. Each field's name is the key, and the selector string is the value.

$('#myForm').formruler({
    feedbackSelectors: {
        username: "#username-error",
        email: "#email-error-container .message",
        password: ".password-feedback"
    }
});

• Fields without specified selectors will display error messages in the default .invalid-feedback sibling element.
• Error messages will not be displayed if the specified selector element does not exist.

Skips certain validation rules under specific conditions. This is especially useful for dynamic form behavior.

The skipRulesIf option specifies an object that defines conditions for skipping validation rules for specific fields. Each field's name is the key, and the condition is specified as an object.

$('#myForm').formruler({
    skipRulesIf: {
        address: {
            dependentId: "sameAsBilling",
            condition: "notEmpty",
            rulesToSkip: ["required", "minLength"]
        }
    }
});

• dependentId: The ID of another field to use for checking the skip condition.
• condition: The condition to check ("notEmpty" or "empty").
• rulesToSkip: An array of rules to skip. Use "all" to skip all rules.

Specifies the ID of the button that triggers form submission. This allows type="button" elements to start form submission and validation.

The triggerButtonId option specifies the ID of the button that triggers form submission as a string.

$('#myForm').formruler({
    triggerButtonId: "submitButton"
});

• Clicking the button with the specified ID will trigger the form submission event.
• The default value is "submitBtn".

Defines custom functions to execute based on the validation results. This allows customization of post-validation processing.

• onValid: The function called when the form is valid (all fields are correctly validated).
• onInvalid: The function called when the form is invalid (one or more fields have errors).

$('#myForm').formruler({
    onValid: function() {
        console.log("Form is valid. Proceeding with submission.");
        // Handle form data submission, etc.
    },
    onInvalid: function() {
        console.log("Form has errors. Please correct them.");
        // Handle displaying errors, scrolling to error fields, etc.
    }
});

• These functions are executed during the form's submit event.
• By default, these functions are empty (do nothing).

Form submission is triggered by any of the following methods:

• Clicking a button with type="submit"
• Clicking the button specified by triggerButtonId
• Calling the submit() method on the form element

FormRuler performs the following actions when the submit event occurs:

• Calls event.preventDefault() to prevent the browser's default form submission behavior.
• This means form data is not automatically sent to the server.

When the submit event occurs, FormRuler performs validation as follows:

• Validates all fields in the form based on the defined rules.
• Displays error messages for fields with errors.

Based on the validation results, one of the following actions is performed:

• If validation succeeds:

  • Calls the onValid callback function.
  • Form data is not automatically submitted.

• If validation fails:

  • Calls the onInvalid callback function.
  • Form data is not submitted.

The actual form data submission must be implemented by the developer:

• Typically, handle submission in the onValid callback.
• Commonly use Ajax or FormData for asynchronous submission.
• For traditional synchronous submission, use $('#myForm')[0].submit() (avoid $('#myForm').submit() to prevent an infinite loop).

$('#myForm').formruler({
    // Validation rules, etc.
    onValid: function() {
        console.log("Validation successful. Submitting form.");
        // Example of form submission using Ajax
        $.ajax({
            url: $('#myForm').attr('action'),
            method: 'POST',
            data: $('#myForm').serialize(),
        }).done(function(response) {
            console.log('Submission successful:', response);
        }).fail(function(error) {
            console.error('Submission failed:', error);
        }).always(function() {
            console.log('Request completed');
        });
    },
    onInvalid: function() {
        console.log("Validation failed. Check the errors.");
    }
});

1. Initialization: When the formruler() method is called, the plugin performs the following actions:

   • Targets elements matching .form-control:not(:disabled), .form-check-input:not(:disabled) within the specified form.
   • Sets "input" and "change" event listeners on these elements.
   • Sets a "click" event listener on the button specified by triggerButtonId.
   • Sets a "submit" event listener on the entire form.

2. Input Validation:

   • Each time the user enters input (the input event) or the value changes (the change event), the plugin validates the field based on the rules corresponding to the name attribute.

3. Error Display:

   • If the input is invalid, the "is-invalid" class is added to the input element, and the .invalid-feedback element displays the error message.
   • If a custom feedback selector is specified, the error message is displayed in the specified element.
   • If the input is valid, the error display is cleared.

4. Form Submission: When the submit button is clicked:

   • The plugin prevents the default form submission (event.preventDefault()).
   • The plugin calls the validateField function on all input fields matching .form-control:not(:disabled), .form-check-input:not(:disabled) in the form to perform validation.
   • If all fields are valid, the onValid callback is called.
   • If any field is invalid, the onInvalid callback is called.

FormRuler performs validation at the following times:

1. Form Submission:

   • When the form is submitted, all fields are validated.

2. Field Value Change:

   • Each field is validated in real-time whenever its value changes (input event) or is modified (change event).

3. Dependent Field Change:

   • If dependencies are set using the skipRulesIf option, related fields are revalidated when the dependent field's value changes.

Based on validation results, the following CSS classes are applied:

1. is-invalid:

   • Applied to fields that fail validation.
   • Example: <input class="form-control is-invalid" ...>

2. is-valid:

   • Applied to fields that pass validation.
   • Example: <input class="form-control is-valid" ...>

3. invalid-feedback:

   • Used for elements displaying error messages.

   • This class must be pre-defined in the HTML.

   • Example: <div class="invalid-feedback">Error message goes here.</div>

1. Initial State:

   • No special CSS classes are applied when the form is initialized.

2. After Validation:

   • is-invalid or is-valid classes are applied based on validation results.
   • Error messages are displayed in corresponding invalid-feedback elements.

3. Value Change:

   • Validation is re-executed, and CSS classes are updated each time the field value changes.

4. Class Toggle:

   • is-invalid and is-valid classes are toggled based on validation status.

FormRuler uses Bootstrap 4/5 compatible CSS classes. Customization is possible as follows:

/* Error state styling */
.is-invalid {
    border-color: #dc3545;
}

/* Success state styling */
.is-valid {
    border-color: #28a745;
}

/* Error message styling */
.invalid-feedback {
    display: none;
    width: 100%;
    margin-top: .25rem;
    font-size: 80%;
    color: #dc3545;
}

/* Display error message when field is invalid */
.is-invalid ~ .invalid-feedback {
    display: block;
}

This project is licensed under the MIT License. See the LICENSE file for details.

---

This README was generated with ❤️ by readme-md-generator