From dfecaa015b43b971c85a6da6e5ea1bbbdfdd5661 Mon Sep 17 00:00:00 2001 From: Phillip Rak Date: Tue, 17 Aug 2021 17:54:28 -0700 Subject: [PATCH 1/7] Outline steps for creating custom validation function --- docs/developer/getting-started/development.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/docs/developer/getting-started/development.md b/docs/developer/getting-started/development.md index 536ed42fca..b6282af242 100644 --- a/docs/developer/getting-started/development.md +++ b/docs/developer/getting-started/development.md @@ -294,6 +294,97 @@ account: placeholder: Optionally enter a description to help you identify this API Key ``` +## Custom Form Validators + +Creating custom validators for forms requires three parts + +1. Add a new validation function to `utils/validators` +2. The new validation function is exported by `utils/custom-validators.js` +3. Add `customValidationRules` prop to a model under `models` + +### Add new validation function + +Custom validators are stored under `utils/validators`. Validation functions should define positional parameters of `value, getters, errors, validatorArgs` with an optional fifth `displayKey` parameter. + +```javascript +export function isHttps(value, getters, errors, validatorArgs, displayKey) { + const key = validatorArgs[0]; + + if (!value.startsWith('https://')) { + errors.push(getters['i18n/t']('validation.setting.serverUrl.https')); + } + + return errors; +} +``` + +Any failed validations are pushed to `errors`. + +> Does a validation function need to return errors? + +### Export new validation function + +Import your new validator function into `utils/custom-validators.js` + +```javascript diff +import { podAffinity } from '@/utils/validators/pod-affinity'; +import { roleTemplateRules } from '@/utils/validators/role-template'; +import { clusterName } from '@/utils/validators/cluster-name'; ++ import { isHttps } from '@/utils/validators/setting'; +``` + +and add it to the default exports + +```javascript diff + containerImages, + cronSchedule, + podAffinity, + - roleTemplateRules + + roleTemplateRules, + + isHttps +}; +``` + +### Add `customValidationRules` to model + +```javascript +customValidationRules() { + return [ + { + path: 'value', + translationKey: 'setting.serverUrl.https', + validators: [`isHttps`] + } + ] +} +``` + +To pass arguments to to validation function + +```diff +customValidationRules() { + return [ + { + path: 'value', + translationKey: 'setting.serverUrl.https', + - validators: [`isHttps`] + + validators: [`isHttps:${ this.metadata.name }] + } + ] +} +``` + +> How do we pass multiple args to validator function? Are they comma separated or separated by colon? + +> What is required of a validation rule? It looks like `path` and `validators`? Maybe it's just `path` because I've found a few without `validators` defined? The properties I've found so far are `nullable`, `path`, `required`, `translationKey`, `type`, `validators`, + +`path` string: the model property to validate +`nullable` boolean: asserts if property accepts `null` value +`required` boolean: asserts if property requires a value +`translationKey` string: path to validation key in `assets/translations` +`type` string: name of built-in validation rule to assert +`validators` string: name of custom validation rule to assert + ## Other UI Features ### Icons Icons are font based and can be shown via the icon class From 57af4af9ca180ffe6bf89cf8897d6faaa9773fa0 Mon Sep 17 00:00:00 2001 From: Phillip Rak Date: Mon, 23 Aug 2021 11:10:49 -0700 Subject: [PATCH 2/7] Edit docs for clarity --- docs/developer/getting-started/development.md | 58 ++++++++++--------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/docs/developer/getting-started/development.md b/docs/developer/getting-started/development.md index b6282af242..0c53320f6c 100644 --- a/docs/developer/getting-started/development.md +++ b/docs/developer/getting-started/development.md @@ -296,41 +296,43 @@ account: ## Custom Form Validators -Creating custom validators for forms requires three parts +Adding custom validation logic to forms and models requires changes to three different parts of Dashboard: -1. Add a new validation function to `utils/validators` -2. The new validation function is exported by `utils/custom-validators.js` -3. Add `customValidationRules` prop to a model under `models` +1. Create a new validation function to `utils/validators` +2. Export the new validation function `utils/custom-validators.js` +3. Add `customValidationRules` prop to appropriate model under `models` -### Add new validation function +### Create a new validation function -Custom validators are stored under `utils/validators`. Validation functions should define positional parameters of `value, getters, errors, validatorArgs` with an optional fifth `displayKey` parameter. +Custom validators are stored under `utils/validators`. Validation functions should define positional parameters of `value, getters, errors, validatorArgs` with an optional fifth `displayKey` parameter: ```javascript -export function isHttps(value, getters, errors, validatorArgs, displayKey) { - const key = validatorArgs[0]; - - if (!value.startsWith('https://')) { - errors.push(getters['i18n/t']('validation.setting.serverUrl.https')); - } - - return errors; +export function exampleValidator(value, getters, errors, validatorArgs, displayKey) { + ... } ``` -Any failed validations are pushed to `errors`. +Make sure the validation function pushes a value to the `error` collection in order to display error messages on the form: -> Does a validation function need to return errors? +> In this example, we're making use of i18n getters to produce a localized error message. + +```javascript +export function exampleValidator(value, getters, errors, validatorArgs, displayKey) { + if (validationFails) { + errors.push(getters['i18n/t']('validation.setting.serverUrl.https')); + } +} +``` ### Export new validation function -Import your new validator function into `utils/custom-validators.js` +In order to make a custom validator available for usage in forms and component, it will need to exposed by importing the new validator function into `utils/custom-validators.js`: ```javascript diff import { podAffinity } from '@/utils/validators/pod-affinity'; import { roleTemplateRules } from '@/utils/validators/role-template'; import { clusterName } from '@/utils/validators/cluster-name'; -+ import { isHttps } from '@/utils/validators/setting'; ++ import { exampleValidator } from '@/utils/validators/setting'; ``` and add it to the default exports @@ -341,7 +343,7 @@ and add it to the default exports podAffinity, - roleTemplateRules + roleTemplateRules, - + isHttps + + exampleValidator }; ``` @@ -353,7 +355,7 @@ customValidationRules() { { path: 'value', translationKey: 'setting.serverUrl.https', - validators: [`isHttps`] + validators: [`exampleValidator`] } ] } @@ -367,8 +369,8 @@ customValidationRules() { { path: 'value', translationKey: 'setting.serverUrl.https', - - validators: [`isHttps`] - + validators: [`isHttps:${ this.metadata.name }] + - validators: [`exampleValidator`] + + validators: [`exampleValidator:${ this.metadata.name }] } ] } @@ -378,12 +380,12 @@ customValidationRules() { > What is required of a validation rule? It looks like `path` and `validators`? Maybe it's just `path` because I've found a few without `validators` defined? The properties I've found so far are `nullable`, `path`, `required`, `translationKey`, `type`, `validators`, -`path` string: the model property to validate -`nullable` boolean: asserts if property accepts `null` value -`required` boolean: asserts if property requires a value -`translationKey` string: path to validation key in `assets/translations` -`type` string: name of built-in validation rule to assert -`validators` string: name of custom validation rule to assert +`path` {string}: the model property to validate +`nullable` {boolean}: asserts if property accepts `null` value +`required` {boolean}: asserts if property requires a value +`translationKey` {string}: path to validation key in `assets/translations` +`type` {string}: name of built-in validation rule to assert +`validators` {string}: name of custom validation rule to assert ## Other UI Features ### Icons From d00c1b54e29d5611c933cd2c3b027ef77eed71c4 Mon Sep 17 00:00:00 2001 From: Phillip Rak Date: Mon, 23 Aug 2021 11:33:38 -0700 Subject: [PATCH 3/7] Clean up examples --- docs/developer/getting-started/development.md | 40 ++++++++++--------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/developer/getting-started/development.md b/docs/developer/getting-started/development.md index 0c53320f6c..0e5231cbd4 100644 --- a/docs/developer/getting-started/development.md +++ b/docs/developer/getting-started/development.md @@ -328,16 +328,16 @@ export function exampleValidator(value, getters, errors, validatorArgs, displayK In order to make a custom validator available for usage in forms and component, it will need to exposed by importing the new validator function into `utils/custom-validators.js`: -```javascript diff +```diff import { podAffinity } from '@/utils/validators/pod-affinity'; import { roleTemplateRules } from '@/utils/validators/role-template'; import { clusterName } from '@/utils/validators/cluster-name'; + import { exampleValidator } from '@/utils/validators/setting'; ``` -and add it to the default exports +and add it to the default exports: -```javascript diff +```diff containerImages, cronSchedule, podAffinity, @@ -349,28 +349,41 @@ and add it to the default exports ### Add `customValidationRules` to model +Locate the model that will make use of the custom validation function and add `customValidationRules` property if one does not already exist. `customValidationRules` returns a collection of validation rules to run against the model: + ```javascript customValidationRules() { return [ { path: 'value', - translationKey: 'setting.serverUrl.https', validators: [`exampleValidator`] } ] } ``` -To pass arguments to to validation function +> ### A validation rule can contain the following keys: +> +> `path` {string}: the model property to validate +> +> `nullable` {boolean}: asserts if property accepts `null` value +> +> `required` {boolean}: asserts if property requires a value +> +> `translationKey` {string}: path to validation key in `assets/translations` +> +> `type` {string}: name of built-in validation rule to assert +> +> `validators` {string}: name of custom validation rule to assert -```diff +Add `:${arg}` to pass custom arguments to a validation function: + +```javascript customValidationRules() { return [ { path: 'value', - translationKey: 'setting.serverUrl.https', - - validators: [`exampleValidator`] - + validators: [`exampleValidator:${ this.metadata.name }] + validators: [`exampleValidator:${ this.metadata.name }] } ] } @@ -378,15 +391,6 @@ customValidationRules() { > How do we pass multiple args to validator function? Are they comma separated or separated by colon? -> What is required of a validation rule? It looks like `path` and `validators`? Maybe it's just `path` because I've found a few without `validators` defined? The properties I've found so far are `nullable`, `path`, `required`, `translationKey`, `type`, `validators`, - -`path` {string}: the model property to validate -`nullable` {boolean}: asserts if property accepts `null` value -`required` {boolean}: asserts if property requires a value -`translationKey` {string}: path to validation key in `assets/translations` -`type` {string}: name of built-in validation rule to assert -`validators` {string}: name of custom validation rule to assert - ## Other UI Features ### Icons Icons are font based and can be shown via the icon class From 291410c615d3ea1a0716c772e4ce7e8dfa6ce696 Mon Sep 17 00:00:00 2001 From: Phillip Rak Date: Mon, 23 Aug 2021 11:35:55 -0700 Subject: [PATCH 4/7] Fix diff syntax --- docs/developer/getting-started/development.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer/getting-started/development.md b/docs/developer/getting-started/development.md index 0e5231cbd4..34a99d3a30 100644 --- a/docs/developer/getting-started/development.md +++ b/docs/developer/getting-started/development.md @@ -341,9 +341,9 @@ and add it to the default exports: containerImages, cronSchedule, podAffinity, - - roleTemplateRules - + roleTemplateRules, - + exampleValidator +- roleTemplateRules ++ roleTemplateRules, ++ exampleValidator }; ``` From b95c05856816053f1c319ec3d938c53915c84b5d Mon Sep 17 00:00:00 2001 From: Phillip Rak Date: Mon, 23 Aug 2021 11:39:27 -0700 Subject: [PATCH 5/7] Update example for clarity --- docs/developer/getting-started/development.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/developer/getting-started/development.md b/docs/developer/getting-started/development.md index 34a99d3a30..5fb9a216c6 100644 --- a/docs/developer/getting-started/development.md +++ b/docs/developer/getting-started/development.md @@ -318,9 +318,13 @@ Make sure the validation function pushes a value to the `error` collection in or ```javascript export function exampleValidator(value, getters, errors, validatorArgs, displayKey) { + ... + if (validationFails) { errors.push(getters['i18n/t']('validation.setting.serverUrl.https')); } + + ... } ``` From b5025c4490de2906e11b2e57c0e0f047d91e8452 Mon Sep 17 00:00:00 2001 From: Phillip Rak Date: Mon, 23 Aug 2021 11:42:48 -0700 Subject: [PATCH 6/7] Update export default example --- docs/developer/getting-started/development.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developer/getting-started/development.md b/docs/developer/getting-started/development.md index 5fb9a216c6..dcbd00b11a 100644 --- a/docs/developer/getting-started/development.md +++ b/docs/developer/getting-started/development.md @@ -342,6 +342,7 @@ import { clusterName } from '@/utils/validators/cluster-name'; and add it to the default exports: ```diff +export default { containerImages, cronSchedule, podAffinity, From 23ec3426d31adf371847700b45e575953d5ef673 Mon Sep 17 00:00:00 2001 From: Phillip Rak Date: Mon, 23 Aug 2021 16:03:34 -0700 Subject: [PATCH 7/7] Add example for passing multiple args --- docs/developer/getting-started/development.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/developer/getting-started/development.md b/docs/developer/getting-started/development.md index dcbd00b11a..dfe18fb3e2 100644 --- a/docs/developer/getting-started/development.md +++ b/docs/developer/getting-started/development.md @@ -388,13 +388,17 @@ customValidationRules() { return [ { path: 'value', - validators: [`exampleValidator:${ this.metadata.name }] + validators: [`exampleValidator:${ this.metadata.name }`] } ] } ``` -> How do we pass multiple args to validator function? Are they comma separated or separated by colon? +Multiple custom arguments can be passed to a validator function; each argument is separated by `:`, for example: + +```javascript +validators: [`exampleValidator:${ this.metadata.name }:'customString':42] +``` ## Other UI Features ### Icons