From dbc691c61ea5d112e7d9e3f393856574ac5d1d37 Mon Sep 17 00:00:00 2001
From: Dixsie <dixsie@ibm.com>
Date: Wed, 24 Mar 2021 06:33:30 -0500
Subject: 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
---
 docs/guide/quickstart/forms.md | 126 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 docs/guide/quickstart/forms.md

(limited to 'docs/guide')

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>
+```
-- 
cgit v1.2.3