Add form quick start documentation

Form quick start documentation contains info on
using the form and form group components, and the Vuelidate plugin.

This doc also provides a template for creating a new form.

Signed-off-by: Dixsie Wolmers <dixsie@ibm.com>
Change-Id: I5d05141ff05cd069e55853a8b2cb4adecb3c848a

2 files changed, 127 insertions, 0 deletions

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index ed0035ca..e48e1662 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -60,6 +60,7 @@ module.exports = {
           {
             title: "Quick Start",
             children: [
+            "/guide/quickstart/forms",
             "/guide/quickstart/page-anatomy",
             "/guide/quickstart/store-anatomy"
           ]
diff --git a/docs/guide/quickstart/forms.md b/docs/guide/quickstart/forms.md
new file mode 100644
index 00000000..5356eac0
--- /dev/null
+++ b/docs/guide/quickstart/forms.md
@@ -0,0 +1,126 @@
+# Forms
+
+Forms are created using the [bootstrap-vue form
+component](https://bootstrap-vue.org/docs/components/form)
+and validated with the [Vuelidate](https://vuelidate.js.org/#sub-installation)
+plugin.
+
+## Form component
+
+When creating a new form, use the `<b-form>` [form
+component](https://bootstrap-vue.org/docs/components/form). Use the `.prevent`
+event modifier on submit to prevent the submit event from reloading the page.
+
+## Form group component
+
+The `<b-form-group>` [form group
+component](https://bootstrap-vue.org/docs/components/form-group)
+pairs form controls with a legend or label, helper text, invalid/valid
+feedback text, and visual validation state feedback. Learn more about
+commonly used form components:
+
+- [Form checkbox](https://bootstrap-vue.org/docs/components/form-checkbox)
+- [Form input](https://bootstrap-vue.org/docs/components/form-input)
+- [Form radio](https://bootstrap-vue.org/docs/components/form-radio)
+- [Form select](https://bootstrap-vue.org/docs/components/form-select)
+- [Form file custom component](/guide/components/file-upload)
+
+When helper text is provided, use the `<b-form-text>` component and `aria-describedby` on the
+form group component the helper text describes.
+
+## Validation
+
+For custom form validation messages, disable browser native HTML5
+validation by setting the `novalidate` prop on `<b-form>`. Use Vuelidate to
+check the form validation state and add
+custom validation messages in the `<b-form-invalid-feedback>` component.
+
+When creating a new form add the `VuelidateMixin`
+to the `scripts` block and import any
+[validators](https://vuelidate.js.org/#validators) needed
+such as: `required`, `requiredIf`, etc. The use of built-in validators is
+preferred.
+
+## Complete form
+
+A complete form will look like this.
+
+```vue
+<template>
+  <b-form novalidate @submit.prevent="handleSubmit">
+    <b-form-group
+      :label="$t('pageName.form.inputLabel')"
+      label-for="form-input-id"
+    >
+      <b-form-text id="form-input-helper-text">
+        {{ $t('pageName.form.helperText') }}
+      </b-form-text>
+      <b-form-input
+        id="form-input-id"
+        v-model="form.input"
+        type="text"
+        aria-describedby="form-input-helper-text"
+        :state="getValidationState($v.form.input)"
+        @change="$v.form.input.$touch()"
+      />
+      <b-form-invalid-feedback role="alert">
+        <div v-if="!$v.form.input.required">
+          {{ $t('global.form.fieldRequired') }}
+        </div>
+      </b-form-invalid-feedback>
+    </b-form-group>
+    <b-button variant="primary" type="submit" class="mb-3">
+      {{ $t('global.action.save') }}
+    </b-button>
+  </b-form>
+</template>
+
+<script>
+import VuelidateMixin from '@/components/Mixins/VuelidateMixin';
+import { required } from 'vuelidate/lib/validators';
+
+export default {
+  name: 'PageName',
+  components: {
+  ...
+  },
+  mixins: [VuelidateMixin],
+  data(){
+    form: {
+      input: '',
+    }
+  },
+  validations() {
+    return {
+      form: {
+        input: { required },
+      }
+    }
+  },
+  computed: {
+    ...
+  },
+  created() {
+    ...
+  },
+  methods:{
+    handleSubmit() {
+      this.$v.$touch();
+      if (this.$v.$invalid) return;
+      this.$store
+        .dispatch(
+          'pageName/updateFormData',
+          formData
+        )
+        .then((success) => {
+          this.successToast(success);
+        })
+        .catch(({ message }) => this.errorToast(message))
+        .finally(() => {
+          this.$v.form.$reset();
+          this.endLoader();
+        });
+    },
+};
+</script>
+```