From 8f2d01c0b458d7ecb4ed4dc3be1f58a80d02649e Mon Sep 17 00:00:00 2001 From: StrykeSlammerII Date: Sat, 13 Apr 2024 18:09:40 -0400 Subject: [PATCH 1/7] Updated validators table A few of these changes are to better match `Fortress/ServerSideValidator::generateSchemaRules()` but many of the changes are for my personal readability. Discussion is welcomed. --- .../06.client-input/01.validation/docs.md | 48 ++++++++++--------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md index b349ca8b..9d7cdb7e 100644 --- a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md +++ b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md @@ -229,9 +229,9 @@ comment: #### Validators -A validator consists of a **validator name**, and a set of validator attributes. In addition to the rule-specific attributes described below, each validator may contain a **validation message** assigned to a `message` attribute. +A validator consists of a **validator name**, and a set of validator **attributes**. Each validator must have at least one attribute. -The validation message will be recorded during the call to `ServerSideValidator::validate` in the event that the field fails the validation rule. This can be a simple text message, or you may [reference a translatable string key](/i18n#the-placeholder) using the `&` prefix. +In addition to the rule-specific attributes described below, each validator may contain a **validation message** assigned to a `message` attribute. The validation message will be recorded during the call to `ServerSideValidator::validate` in the event that the field fails the validation rule. This can be a simple text message, or you may [reference a translatable string key](/i18n#the-placeholder) using the `&` prefix. **Example:** ```yaml @@ -245,7 +245,9 @@ talons: max: 120 message: "Talons must be less than {{max}} characters." ``` -Note there are two validators for `talons`. The `required` validator requires a value to be in this field and the `length` validator sets a maximum of 120 characters. The `message` key for each validator is simply the message that will be displayed if the validator parameters are not met. E.g. if a value of over 120 characters is provided, the user will see the validation message `Talons must be less than 120 characters.` +Note there are two validators for `talons`. The `required` validator fails if the field has no value. The `length` validator sets a maximum of 120 characters. + +The `message` key for each validator is simply the message that will be displayed if the validator parameters are not met. E.g. if a value of over 120 characters is provided, the user will see an alert message `Talons must be less than 120 characters.` To integrate a translatable string key simply add your key using the `&` prefix. For example, your [translation file](/i18n#the-translation-files) might look like: @@ -280,24 +282,24 @@ The following validators are available: | Name | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `email` | Specifies that the value of the field must represent a valid email address. | -| `equals` | Specifies that the value of the field must be equivalent to `value`. | -| `integer` | Specifies that the value of the field must represent an integer value. | -| `length` | Specifies `min` and `max` bounds on the length, in characters, of the field's value. | -| `matches` | Specifies that the value of the field must be equivalent to the value of `field`. | -| `member_of` | Specifies that the value of the field must appear in the specified `values` array. | -| `no_leading_whitespace` | Specifies that the value of the field must not have any leading whitespace characters. | -| `no_trailing_whitespace` | Specifies that the value of the field must not have any trailing whitespace characters. | -| `not_equals` | Specifies that the value of the field must **not** be equivalent to `value`. | -| `not_matches` | Specifies that the value of the field must **not** be equivalent to the value of `field`. | -| `not_member_of` | Specifies that the value of the field must **not** appear in the specified `values` array. | -| `numeric` | Specifies that the value of the field must represent a numeric (floating-point or integer) value. | -| `range` | Specifies a numeric interval bound on the field's value. | -| `regex` | Specifies that the value of the field must match a specified Javascript- and PCRE-compliant regular expression. | -| `required` | Specifies that the field is a required field. If the field is not present in the HTTP request, validation will fail unless a default value has been specified for the field. | -| `telephone` | Specifies that the value of the field must represent a valid telephone number. | -| `uri` | Specifies that the value of the field must represent a valid Uniform Resource Identifier (URI). | -| `username` | Specifies that the value of the field must be a valid username (lowercase letters, numbers, `.`, `-`, and `_`). | +| `email` | Specifies that the value of this field must represent a valid email address. | +| `equals` | Specifies that the value of this field must be equivalent to a `value` attribute. (See example below) | +| `integer` | Specifies that the value of this field must represent an integer value. | +| `length` | Specifies `min` and `max` attributes as bounds on the length (in characters) of this field's value. (See example below) | +| `matches` | Specifies that the value of this field must be equivalent to the value of another field, named by the `field` attribute. (See example below) | +| `member_of` | Specifies that the value of this field must appear in the specified `values` array. (See example below) | +| `no_leading_whitespace` | Specifies that the value of this field must not have any leading whitespace characters. | +| `no_trailing_whitespace` | Specifies that the value of this field must not have any trailing whitespace characters. | +| `not_equals` | Specifies that the value of this field must **not** be equivalent to the `value` attribute. | +| `not_matches` | Specifies that the value of this field must **not** be equivalent the value of another field, named by the `field` attribute. | +| `not_member_of` | Specifies that the value of this field must **not** appear in the specified `values` array. | +| `numeric` | Specifies that the value of this field must represent a numeric (floating-point or integer) value. | +| `range` | Specifies that the value of this field is greater than or equal to any `min` attribute, and less than or equal to any `max` attribute. (See example below) | +| `regex` | Specifies that the value of this field must match a specified Javascript- and PCRE-compliant regular expression. (See example below) | +| `required` | Specifies that this field is a required field. If this field is not present in the HTTP request, validation will fail unless a default value has been specified for the field. | +| `telephone` | Specifies that the value of this field must represent a valid US telephone number. | +| `uri` | Specifies that the value of this field must represent a valid Uniform Resource Identifier (URI). | +| `username` | Specifies that the value of this field must be a valid username (lowercase letters, numbers, `.`, `-`, and `_`). | **Example - Equals:** ```yaml @@ -352,8 +354,8 @@ owls: max: 10 message: "Please provide {{min}} - {{max}} owls." ``` - -[notice=tip]You can use `min_exclusive` instead of `min`, and `max_exclusive` instead of `max` to create open intervals.[/notice] +{# +[notice=tip]You can use `min_exclusive` instead of `min`, and `max_exclusive` instead of `max` to create open intervals.[/notice]#} **Example - Regex:** ```yaml From 470c3ec2138378d1ad4de59a5571e4f740760daa Mon Sep 17 00:00:00 2001 From: StrykeSlammerII Date: Sat, 13 Apr 2024 18:18:10 -0400 Subject: [PATCH 2/7] Added note and corrected comment style --- .../06.client-input/01.validation/docs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md index 9d7cdb7e..c6e88c97 100644 --- a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md +++ b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md @@ -354,8 +354,8 @@ owls: max: 10 message: "Please provide {{min}} - {{max}} owls." ``` -{# -[notice=tip]You can use `min_exclusive` instead of `min`, and `max_exclusive` instead of `max` to create open intervals.[/notice]#} + **Example - Regex:** ```yaml From 7e891b406cfa0fc2ce0d0dec2f32ba4ae3417fd3 Mon Sep 17 00:00:00 2001 From: StrykeSlammerII Date: Sun, 14 Apr 2024 01:27:20 -0400 Subject: [PATCH 3/7] Added section for input arrays. Still need to test how transforms interact with input arrays :< --- .../06.client-input/01.validation/docs.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md index c6e88c97..f77d32aa 100644 --- a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md +++ b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md @@ -84,6 +84,35 @@ message: Notice that the schema consists of a number of field names, which should correspond to the `name` attributes of the fields in your form. These map to objects containing `validators` and `transformations`. See [below](#schema-specifications) for complete specifications for the validation schema. +#### Input arrays +If your form uses [input arrays](https://stackoverflow.com/questions/4688880/html-element-array-name-something-or-name-something) such as ` Date: Mon, 22 Apr 2024 00:15:44 -0400 Subject: [PATCH 4/7] Added "no transformations" warning to Input Arrays --- .../06.client-input/01.validation/docs.md | 61 ++++++++++--------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md index f77d32aa..4ff28d1f 100644 --- a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md +++ b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md @@ -84,35 +84,6 @@ message: Notice that the schema consists of a number of field names, which should correspond to the `name` attributes of the fields in your form. These map to objects containing `validators` and `transformations`. See [below](#schema-specifications) for complete specifications for the validation schema. -#### Input arrays -If your form uses [input arrays](https://stackoverflow.com/questions/4688880/html-element-array-name-something-or-name-something) such as ` Date: Mon, 22 Apr 2024 23:20:14 -0400 Subject: [PATCH 5/7] Transforms DO work with input arrays --- .../06.client-input/01.validation/docs.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md index 4ff28d1f..ea019471 100644 --- a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md +++ b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md @@ -185,9 +185,9 @@ The `validate` method will return `false` if any fields fail any of their valida ### Input arrays If your form uses [input arrays](https://stackoverflow.com/questions/4688880/html-element-array-name-something-or-name-something) such as ` Date: Tue, 23 Apr 2024 13:12:27 -0400 Subject: [PATCH 6/7] small typo --- .../06.client-input/01.validation/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md index ea019471..b522861f 100644 --- a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md +++ b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md @@ -186,7 +186,7 @@ The `validate` method will return `false` if any fields fail any of their valida ### Input arrays If your form uses [input arrays](https://stackoverflow.com/questions/4688880/html-element-array-name-something-or-name-something) such as ` Date: Sun, 12 May 2024 22:22:39 -0400 Subject: [PATCH 7/7] Update doc associative array Reference: https://github.com/userfrosting/UserFrosting/issues/1251 --- .../06.client-input/01.validation/docs.md | 134 +++++++++++++----- 1 file changed, 95 insertions(+), 39 deletions(-) diff --git a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md index b522861f..f774d8f3 100644 --- a/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md +++ b/pages/08.routes-and-controllers/06.client-input/01.validation/docs.md @@ -183,43 +183,6 @@ The `validate` method will return `false` if any fields fail any of their valida [notice=info]Internally, UserFrosting uses the [Valitron](https://github.com/vlucas/valitron) validation package to perform server-side validation.[/notice] -### Input arrays -If your form uses [input arrays](https://stackoverflow.com/questions/4688880/html-element-array-name-something-or-name-something) such as ` **Example - Regex:** ```yaml @@ -405,6 +366,101 @@ screech: [notice=warning]Regular expressions should _not_ be wrapped in quotes in YAML. Also the jQuery Validation plugin wraps regular expressions on the client side with `^...$`. Please see [this issue](https://github.com/jquery-validation/jquery-validation/issues/1967).[/notice] +### Input arrays, multidimensional arrays & associative arrays +If your form uses [input arrays](https://stackoverflow.com/a/42969920/445757) such as ` + +``` + +The same principle can be applied to associative arrays. For example, it's possible to target both inputs in the example below with `nameList.first` & `nameList.last`. + +```html + + +``` + +Both can be mixed together. For example, in the example below, `first` and `last` can be defined in the schema as `nameList.*.first` and `nameList.*.last`. The same transformation and validation rules will be applied to both instance of `nameList[][first]` for example. + +```html + + + + + + + + +``` + +Note when using arrays, **transformations** can be can be applied to each element, or all elements at once. The two transformations below are equivalent: + +```yaml +nameList: + transformations: + - purge + - trim + +nameList.*: + transformations: + - purge + - trim +``` + +However, with associative arrays, this is useful if different rules are required for each associations. For example, the schema below will apply the `purge` transformation to `nameList.*.first` only, `escape` will be only apply to `nameList.*.last`, but `trim` will be applied to both. + +```yaml +nameList: + transformations: + - trim + +nameList.*.first: + transformations: + - purge + +nameList.*.last: + transformations: + - escape +``` + +As for **validators**, it's a little different. Any validators rules for `nameList` will be validated against the array itself. Rules defined for `nameList.*` will be applied to each element of an array individually. For example, the schema bellow will make sure the `nameList` array is there, and apply the length rule to each element of the array. + +```yaml +nameList: + validators: + required: + message: Your input left out the names. + +nameList.*: + validators: + length: + min: 1 + max: 50 + message: "Names must be between {{min}} and {{max}} characters." +``` + +Another example for a phone list with both validations and transformations might look like this: + +```yaml +phoneList: + validators: + required: + message: Your input left out the telephone numbers. + transformations: + - purge + - trim + +phoneList.*: + validators: + telephone: + message: The phone number you provided is not a valid US phone number. +``` + +Please check [Valitron's usage directions](https://github.com/vlucas/valitron#usage) for more information on arrays and [multidimensional arrays](https://mattstauffer.com/blog/a-little-trick-for-grouping-fields-in-an-html-form/). + +Keep in mind, each field **not** in the schema will be removed from the transformed data by default. If your schema contains `nameList.*.first` and `nameList.*.last`, and the associative array / form contains an `email` key, it will be removed as the schema doesn't contains `nameList.*.email`. + ### Limit rules to server or client only Sometimes, you want a validation rule to be only applied server-side but not in Javascript on the client side, or vice versa. For example, there may be forms that contain hidden data that needs to be validated on the server-side, but is not directly manipulated by the user in the browser. Thus, these fields would not need client-side validation rules.