VRx Form

# Form setup

To v-form directive is the starting point of form validation. When initialized it can begin to process validations.

# Initialization

By adding the directive v-form to a form element and passing it a VRXForm object, the library can initialize form validations.

FATAL

If v-form does not appear on a form element, an error will be thrown.

To initialize the form pass in the VRXForm object:


 












 



<template>
  <form v-form="myForm">
    <!-- omitted -->
  </form>
</template>
<script>
 export default {
   name 'MyForm',
   data() {
     return {
       // can also import VRXForm from 'vrx-form'...
       // and instantiate it like so myForm: new VRXForm()
       myForm: this.$createForm()
     }
   }
 }
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

The above is the first step in creating validations.

# Custom input event

Some times it is necessary to override the default browser input event for the form when the fields contained are custom web components or vue components that dispatch an input event that is not named input.

This is done by declaring a second v-form directive in an argument named inputEvent like the following:


 







<template>
  <form v-form="myForm" v-form:inputEvent="'my-input-event'">
    <!-- omitted -->
  </form>
</template>
<script>
 // omitted for this example
</script>
1
2
3
4
5
6
7
8

The above highlighted code tells VRx Form to listen to events named my-input-event for the entire form. This will also help v-model know how to set the value properly (which has been a limitation of v-model in the past).

TIP

If you need to override a specific field's input event you can do so as explained here.

# Dirty and pristine

The VRXForm object knows the state of the object, whether it is dirty or pristine.

Pristine is when the form has never received any type of input from the user. Where as dirty is when the current form values are not equal to their original state.

Pristine and dirty states can be retrieved from isPristine and isDirty respectively. These two values can be important when we want to let a user know that they are leaving a page with unsaved changes.

Take the following example:















 
 
 
 
 
 
 
 
 
 
 




<template>
  <form v-form="myForm" v-form:inputEvent="'my-input-event'">
    <!-- omitted -->
  </form>
</template>
<script>
export default {
  data() {
    return {
      myData: { /** omit **/},
      myDataForm: this.$createForm()
    };
  },
  beforeRouteLeave (to, from, next) {
    // sometimes you may want to use isPristine
    if (this.myDataForm.isDirty) {
      const answer = window.confirm('Do you really want to leave? you have unsaved changes!');
      if (answer) {
        next();
      } else {
        next(false);
      }
    } else {
      next();
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

In the above example, you can prevent a route change if the form is dirty and let the user determine if they meant to leave the screen.

TIP

A very important use case for isDirtyis for edits. More often than not you will only want to code the form so that it only allows for submitting the form if it is both valid and isDirty is equal to true.

# Valid

A VRXForm object can also know the state of the forms validity. This is controlled through the property isValid.

Take the following example:




 














<template>
  <form v-form="myForm" v-form:inputEvent="'my-input-event'">
    <!-- omitted fields -->
    <button :disabled="!myDataForm.isValid">submit</button>
  </form>
</template>
<script>
export default {
  data() {
    return {
      myData: { /** omit **/},
      myDataForm: this.$createForm()
    };
  }
  /** omitted mounted **/
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

isValid can control giving the option for a user to press the submit button, in this particular use case.

← Field setup →