From a46aabb728a63f7d6dfa5186efc13bc69d539352 Mon Sep 17 00:00:00 2001 From: simplymichael Date: Thu, 14 Dec 2023 21:11:00 +0100 Subject: [PATCH] docs(readme): update the README.md file --- README.md | 111 ++++++++++++++++++++++++++---------------------------- 1 file changed, 54 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 94c03d9..adefbbd 100644 --- a/README.md +++ b/README.md @@ -24,30 +24,27 @@ npm install smart-form-validator --save Later in our code: -```css - -``` - ```js import SmartFormValidator from "smart-form-validator"; ``` -### Using build / minified version +### Using the ` - ``` -3. `SmartFormValidator` is now available as a property of the global object. +Add JS file to page: +``` + +``` +`SmartFormValidator` is now available as a property of the global object. + + +### Using default effects styles +To get the default effects styles applied to our form fields, we need to add the CSS file to our page: +```css + +``` ## Quick start @@ -68,6 +65,8 @@ import SmartFormValidator from "smart-form-validator"; ```js // File: signup-form-validator.js +import SmartFormValidator from "smart-form-validator"; + const form = document.getElementById("test-form"); new SmartFormValidator() @@ -125,16 +124,18 @@ The state of a field changes in response to the data entered and its adherence to the constraints or rules defined for/placed on that field. ### 2. Rules -A rule is an object that specifies the constraint(s) on a field. +A rule is an object that specifies the constraint(s) on a field. +It encapsulates the constraints we want placed on that field. For any field to be validated, we must attach a rule with at least one constraint to it. Rules are plain JavaScript objects with one required property: `field`. The value of the `field` can be either the element's `id` or, -in cases where we have previously obtained a reference to the element, the element reference. +in instances where we have previously obtained a reference to the element, the element reference. -Other properties of a rule specify the constraints we want placed on the target field. +Other properties of a rule depend on the type of the field and +specify the constraints we want placed on the target field. -#### Default supported constraints +#### Default constraints The current default supported rules are: - **`type` {String}:** specifies the acceptable data type of the value for this field, one of either (`"alnum"`|`"alpha"`|`"ascii"`|`"email"`|`"number"`). Default is `alnum`. @@ -167,42 +168,43 @@ new SmartformValidator() .addRule(rule) ``` -**Note:** We can create custom rules and write custom validators that check for and enforce these rule. +**Note:** We can create custom rules and write custom validators that check for these rules. See the the section on [Customizing Smart Form Validator](#customizing-smart-form-validator) for more. ### 3. Validators -Validators are rule enforcers. +Validators are like rule "enforcers". A validator is a function that checks that the data entered into a field complies with the constraints placed on that field. ### Default validators -The following validators come built-in corresponding with the built-in rules: +The following validators come built-in corresponding with the default constraints: - **`alphaValidator`:** checks that a field contains only the letters `A - Z`, underscores (`_`), and dashes (`-`). - The field can also accept whitespace characters with the `allowWhitespace` rule set to true. - To perform a case-insensitive check, set the `matchCase` rule to `false`. + The field can also accept whitespace characters with the `allowWhitespace` constraint set to `true`. + To perform a case-insensitive check, set the `matchCase` constraint to `false`. - **`alphanumericValidator`:** checks that a field contains only the letters `A - Z`, the numbers `0 - 9`, underscores (`_`), and dashes (`-`). - The field can also accept whitespace characters with the `allowWhitespace` rule set to true. - To perform a case-insensitive check, set the `matchCase` rule to `false`. + The field can also accept whitespace characters with `allowWhitespace` set to true. + To perform a case-insensitive check, set `matchCase` to `false`. - **`asciiTextValidator`:** checks that a field contains only characters from the [ASCII character-set][ascii]. - This validator accepts whitespace characters by default irrespective of the value of the `allowWhitespace` rule. - However, we can specify a case-insensitive match by setting the `matchCase` rule to `false`. -- **`emailValidator`:** checks that the value entered into the field has a valid email form. + This validator accepts whitespace characters by default irrespective of the value of `allowWhitespace`. + However, we can specify a case-insensitive match by setting `matchCase` to `false`. +- **`emailValidator`:** checks that the value entered into the field has a valid email format. - **`lengthValidator`:** checks that the value entered in the field is between the minimum and/or maximum specified length. - **`numberValidator`:** checks that a field contains only the numbers `0 - 9`. - The field can also accept whitespace characters with the `allowWhitespace` rule set to true. -- **`regexValidator`:** checks that a field's value conforms to a custom regex constraint. -- **`requiredFieldValidator`:** checks that a field is not empty, and has some data entered into it. - -**Notes:**: -- For a constraint to be enforced, there must be a corresponding validator defined to check for it. -- We can create custom validators that make use of the available rules or that define their own rules. + The field can also accept whitespace characters with `allowWhitespace` set to true. +- **`regexValidator`:** checks that a field's value conforms to a custom regular expression constraint. +- **`requiredFieldValidator`:** checks that a field has some data entered into it. + +**Notes** +- For a constraint to be checked during validation, there must be a corresponding validator defined for it. +- We can create custom validators that make use of the [default constraints](#default-constraints) + or that define their own rules. See the [Creating custom validators](#creating-custom-validators) section for more on how to do this. ### 4. Effects -An Effect represents an action to be taken based on the outcome of a field's validatiion. +An Effect represents an action to be taken based on the outcome of a field's validation. We can, for example, use an effect to display hints to the user as they input data into a field, to disable the submit button and prevent the form from being submitted unless every other field has valid input, or to add some special CSS effects to a field to indicate its state as either *valid* or *invalid*. @@ -238,7 +240,8 @@ The validator function is passed the following positional arguments in order: The value (`on` or `off`) will be passed as the first argument (the `value` argument) to the validator. The `checked` state will be passed in as `extras.checked`. -A validator should return `true` if the field passed the validation rule. Otherwise it should return `false`. +A validator should return `true` if the field it is validating passed the validation rule. +Otherwise it should return `false`. ### Registering validators After creating a validator, we must register it with the `addValidator(name, validator, meta)` method @@ -259,11 +262,11 @@ of the `SmartFormValidator` instance. For example, instead of having a validator that checks for a `required` state, a maximum length constraint, and whether or not the fields contains numbers, it's better to have separate validators for each of these checks: - one to check for `required`, another to enforce the `length` constraint, + one to check for `required`, another to ensure the `length` constraint is met, and yet another to check that the `number` constraint is fulfilled. Each of these validators will be called with the rule and the result of the previous validator. 2. A validator should return only `true` or `false` values. - A validator should not directly effect a side-effect on a field in the event of a + A validator should not directly perform a side-effect on a field in the event of a successful or failed validation. Any such effects should be delegated to [effects](#effects). In the end, the validation process is reduced to a binary *passing* or *failing* test. @@ -308,19 +311,12 @@ In both cases, `useEffect` expects the complete effect object as its argument. #### Customizing Smart Form Validator - A quick example Say we have a field -and we want to define and enforce a constraint on that field to only accept objects. +and we want to define a constraint on that field so that it only accepts objects (or JSON strings). First, we'd create a rule stating that requirement. The rule will have a `field` property that specifies the target field. We may omit this property while creating the rule, but must specify it when adding the rule to the field. -The rule may optionally have a `getValue` property if the field is not a traditional HTML input field -whose value we can obtain with `element.value`. The `getValue` property -will hold a function that will return the current value of the field when called: - ```js -const objectExpectedRule = { - type: "object", - getValue: () => { /* get the field's value somehow*/ } -}; +const objectExpectedRule = { type: "object" }; ``` Next, we need to add the rule to the field: @@ -358,9 +354,10 @@ function objectValidator(value, rule) { return true; } - // We are assuming `getValue()` returns a string in keeping with the value type of form fields, - // but we can make a call to `JSON.parse()` inside the `getValue()` method - // of the `objectExpectedRule`, in which case our test will be something like: + // We are assuming the field's value is a string in keeping with the value type of form fields, + // but if we have a `getValue()` method attached to the field, + // we can make a call to `JSON.parse()` inside the `getValue()` method + // in which case our test will be something like: // if(!value || typeof value !== "object") if(!value || typeof value !== "string") { return false; @@ -369,7 +366,7 @@ function objectValidator(value, rule) { try { const config = JSON.parse(value); - // `config` property checks go here, for example: + // `config` property checks go here; For example: if(!(prop in config)) { return false; }