diff options
author | Dixsie <dixsie@ibm.com> | 2021-03-24 14:33:30 +0300 |
---|---|---|
committer | Derick Montague <derick.montague@ibm.com> | 2021-04-06 04:18:43 +0300 |
commit | dbc691c61ea5d112e7d9e3f393856574ac5d1d37 (patch) | |
tree | 5ead16bf45ebffdcfc4961d48ca36c17d41da0d4 | |
parent | 71aa45580d2c9d434e3c5fb06189ec98d56199fe (diff) | |
download | webui-vue-dbc691c61ea5d112e7d9e3f393856574ac5d1d37.tar.xz |
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
-rw-r--r-- | docs/.vuepress/config.js | 1 | ||||
-rw-r--r-- | docs/guide/quickstart/forms.md | 126 |
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> +``` |