Validators

TIP

This section requires that you are familiar with the Validation, the Forms and the Form component. If you're not, please consider reading these documents first.

Normally, to assign a validator, you have two ways:

• assign it on the FormControl itself, either when constructing it or by calling setValidator(),
• via the @Assert() decorator if the form is generated from a model.

Here we'll see a third way: Vue components!

Basic usage

Validators components can be found in @banquette/vue-ui/form/validator. There is one for each native validator of Banquette.

Their names follow the same logic, so it's easy to know the name of the component corresponding to a validator. For example:

• NotEmpty() => bt-validate-not-empty,
• Email() => bt-validate-email,
• And() => bt-validate-and,
• etc.

To use one, just add it as a child to the form control you want to validate:

Live demo

Basic.vue

And that's it! You can put it in any control, in any slot. The important thing here is that the validator is a child of the control to validate.

Custom target

You can also target one or multiple controls by their path using the target prop:

Live demo

Target.vue

Here there are several things to note:

• We used a bt-form. This is because target needs it to get the controls,
• We have set multiple targets, separated by a comma,
• Each target is an absolute path to the control (here we omitted the / for better readability, but what it really does is /name,/email).

WARNING

You may be tempted to do this to assign both the not-empty and email validators to email:

<bt-form>
    <bt-form-text control="name">
        Your name
    </bt-form-text>
    <bt-form-text control="email">
        Your email
    </bt-form-text>
    <bt-validate-not-empty target="name,email">This is required</bt-validate-not-empty>
    <bt-validate-email target="email">Invalid email</bt-validate-email>
</bt-form>

But DON'T, it will not work as you expect. A FormControl can only have one validator, and what these components do is just calling setValidator() for you.

So if you add multiple bt-validate-* for a control, setValidator() will be called multiple times, and only the last validator will be used.

Instead, if you want to set multiple validators to a control, use a Container validator.

Target pattern

When you set a target, internally this causes the validator to call the get method of the parent FormGroup. So you have all the power of the function available to you!

This means you can use a glob pattern to get the controls:

Live demo

Target-glob.vue

Learn more about glob patterns in this section.

Container validators

If you need to set multiple validators to a control, you need to use a container. All containers are also available as component, so you can do this:

Live demo

Container.vue

As you can see, the default slot is used to add the child validators. And that's pretty much all there is to it.

You can go as deep as you want, just like normal validators.

Dynamic validators

Another advantage of using the validators as components, is that they make it very easy to add/remove them dynamically:

Live demo

Dynamic.vue

Validators reference

Here are listed all built-in validator components. They are just a wrapper around the "real" validators that are part of the validation package. So only the particularities will be described here. For detailed usage instruction and example, please consult the Validation documentation.

All the build-in validators have the following common set of props:

Prop	Description	Default
form	Form in which search for the controls.	null
target	Paths of target controls to apply the validator on.	[]
message	Error message to give to the validator. The default slot is used if it has content.	Validator's default
type	Error type to give to the validator.	Validator's default
tags	Tags to give to the validator.	[]
groups	Groups to give to the validator.	[]

---

NotEmpty

Check that the value is not empty.

Usage:

<bt-validate-not-empty>Custom error message</bt-validate-not-empty>

Props:
Default props only

See NotEmpty for example inputs.

---

Empty

Check that the value is empty.

Usage:

<bt-validate-not-empty>Custom error message</bt-validate-not-empty>

Props:
Default props only

See Empty for example inputs.

---

Equal

Check that the value is equal to a static value.

Usage:

<bt-validate-equal value="test" strict>Custom error message</bt-validate-equal>

Props:

Prop	Description	Default
value	The value to test equality with.	Required
strict	If false, cast the value being validated to match the type of the comparison value.	true

See Equal for example inputs.

---

Max

Check if the number of elements counted in a value is greater or equal than a number.

Usage:

<bt-validate-max :count="10">Custom error message</bt-validate-max>

Props:

Argument	Description	Default
count	The maximum count to accept.	Required
treatAs	Force the validated value to be casted as a string or number. If set to auto the type is untouched.	'auto'

See Max for example inputs.

---

Min

Check if the number of elements counted in a value is lesser or equal than a number.

Usage:

<bt-validate-min :count="10">Custom error message</bt-validate-min-empty>

Props:

Argument	Description	Default
count	The minimum count to accept.	Required
treatAs	Force the validated value to be casted as a string or number. If set to auto the type is untouched.	'auto'

See Min for example inputs.

---

Choice

Check that the value is in a list of predefined choices.

Usage:

<bt-validate-choice>Custom error message</bt-validate-choice>

Props:

Argument	Description	Default
choices	Array of valid choices.	Required

See Choice for example inputs.

---

Pattern

Check that the value matches a RegExp.

Usage:

<bt-validate-pattern pattern="^\w+$" flags="m">Custom error message</bt-validate-pattern>

Props:

Argument	Description	Default
pattern	Regex as a string (no delimiter required).	Required
flags	Flags to apply to the pattern (second arg of RegExp).	undefined

See Pattern for example inputs.

---

Email

Check that the value is a valid email address.

Usage:

<bt-validate-email>Custom error message</bt-validate-email>

Props:
Default props only

See Email for example inputs.

---

Phone

Check that the value is a valid phone number.

Usage:

<bt-validate-phone>Custom error message</bt-validate-phone>

Props:
Default props only

See Phone for example inputs.

---

Url

Check that the value is a valid url.

Usage:

<bt-validate-url>Custom error message</bt-validate-url>

Props:
Default props only

See Url for example inputs.

---

IsType

Check that the value matches a type.

Usage:

<bt-validate-type allowed="number">Custom error message</bt-validate-type>

Argument	Description	Default
allowed	Type or array of types the value must comply with.	Required

See IsType for example inputs.

---

SameAs

Check that the value is the same as the value of another part of the validation tree.

Usage:

<bt-validate-same-as>Custom error message</bt-validate-same-as>

Argument	Description	Default
path	A path to other value to test with.	Required

See SameAs for example inputs.

---

Ajax

Delegates the validation logic to a remote server.

Usage:

<bt-validate-ajax url="/email-available">This email is already used</bt-validate-ajax>

Argument	Description	Default
url	A raw url to call.	Required if no endpoint
endpoint	Api endpoint name.	Required if no url
urlParams	Parameters to add to the url or query.	{}
method	Http method to use. Only used if no endpoint is defined.	'post'
responseProperty	Name of the property that contains the boolean response in the server's response. If none is defined, the http status is used.	null

See Ajax for more detail.

---

Invalid

A validator that always fails.

Usage:

<bt-validate-invalid>Custom error message</bt-validate-invalid>

Props:
Default props only

See Invalid for example inputs.

---

And

Execute each of the given validators sequentially until one of them fails.

Usage:

<bt-validate-and>
    <bt-validate-not-empty>This is mandatory.</bt-validate-not-empty>
    <bt-validate-min :count="5">This is too short.</bt-validate-min>
    <bt-validate-max :count="45">This is too long.</bt-validate-max>
</bt-validate-and>

Props:
Default props only

See And for example inputs.

---

Or

Check that the value is empty.

Usage:

<bt-validate-or>
    <bt-validate-empty></bt-validate-empty>
    <bt-validate-min :count="5">This is too short.</bt-validate-min>
</bt-validate-or>

Props:
Default props only

See Or for example inputs.

---

If

Execute each of the given validators sequentially if a condition verifies.

Usage:

<!-- Here we only apply the email validator if "name" has a value. -->
<bt-validate-if :condition="(ctx) => ctx.form.value.name.length > 0">
    <bt-validate-email>Must be a valid email</bt-validate-email>
</bt-validate-if>

Argument	Description	Default
condition	A callback returning true if the child validators should be executed.	Required

See If for example inputs.

---

Compose

Execute all the given validators in parallel.

Usage:

<bt-validate-compose>
    <bt-validate-not-empty>This is mandatory.</bt-validate-not-empty>
    <bt-validate-min :count="5">This is too short.</bt-validate-min>
</bt-validate-compose>

Props:
Default props only

See Compose for example inputs.

---

Foreach

Execute its sub validator for each iterable item of the validated value.

Usage:

<bt-validate-foreach>
    <bt-validate-not-empty>This is mandatory.</bt-validate-not-empty>
</bt-validate-foreach>

Props:
Default props only

See Foreach for example inputs.

---