From f6df801b384118b946bb3b7b3248832ec70cfd0a Mon Sep 17 00:00:00 2001 From: Derick Montague Date: Wed, 9 Dec 2020 18:37:11 -0600 Subject: Update component documentation The component structure was not consistent. We determined how we wanted to save image examples within the component directory, but not all of the components were updated. The result was that some images were not displaying on the component pages. This patchset resolves that issue, along with removing the page component since it is not an actual component within the application. - Add directory for each component, move example images to the directory, and update the image path - Create a page-title and page-section directory and index.md for each - Move content for page-title and page-section from the page.md file into the index.md within the respective component directory - Delete the page.md from the component directory as it is not a component - Update links to page.md in the page-anatomy.md file. Signed-off-by: Derick Montague Change-Id: I1e554adf71abb4c84f423a30d3c3b598f678ade0 --- docs/guide/components/alert.md | 12 ---- docs/guide/components/alerts/alert.png | Bin 0 -> 45130 bytes docs/guide/components/alerts/index.md | 12 ++++ docs/guide/components/info-tooltip/index.md | 15 +++++ .../guide/components/info-tooltip/info-tooltip.png | Bin 0 -> 4234 bytes docs/guide/components/page-section/index.md | 10 +++ docs/guide/components/page-title/index.md | 23 +++++++ docs/guide/components/page.md | 67 --------------------- docs/guide/components/toast.md | 32 ---------- docs/guide/components/toasts/index.md | 32 ++++++++++ docs/guide/components/toasts/toast.png | Bin 0 -> 100290 bytes docs/guide/components/tooltip.md | 15 ----- docs/guide/quickstart/page-anatomy.md | 2 +- 13 files changed, 93 insertions(+), 127 deletions(-) delete mode 100644 docs/guide/components/alert.md create mode 100644 docs/guide/components/alerts/alert.png create mode 100644 docs/guide/components/alerts/index.md create mode 100644 docs/guide/components/info-tooltip/index.md create mode 100644 docs/guide/components/info-tooltip/info-tooltip.png create mode 100644 docs/guide/components/page-section/index.md create mode 100644 docs/guide/components/page-title/index.md delete mode 100644 docs/guide/components/page.md delete mode 100644 docs/guide/components/toast.md create mode 100644 docs/guide/components/toasts/index.md create mode 100644 docs/guide/components/toasts/toast.png delete mode 100644 docs/guide/components/tooltip.md (limited to 'docs/guide') diff --git a/docs/guide/components/alert.md b/docs/guide/components/alert.md deleted file mode 100644 index 1892f3f8..00000000 --- a/docs/guide/components/alert.md +++ /dev/null @@ -1,12 +0,0 @@ -# Alerts -An alert is an inline message that contains a short description that a user cannot manually dismiss. With exception to the error message on the login page, alerts are not triggered by user action. Success and error notifications based on user actions are created using a toast component. - -[Learn more about Bootstrap-vue alert options](https://bootstrap-vue.js.org/docs/components/alert) - -![Alert examples](/alert.png) - -```vue -This is a warning message -This is an error message -This is an info message -``` \ No newline at end of file diff --git a/docs/guide/components/alerts/alert.png b/docs/guide/components/alerts/alert.png new file mode 100644 index 00000000..7a368f7f Binary files /dev/null and b/docs/guide/components/alerts/alert.png differ diff --git a/docs/guide/components/alerts/index.md b/docs/guide/components/alerts/index.md new file mode 100644 index 00000000..9273f8e2 --- /dev/null +++ b/docs/guide/components/alerts/index.md @@ -0,0 +1,12 @@ +# Alerts +An alert is an inline message that contains a short description that a user cannot manually dismiss. With exception to the error message on the login page, alerts are not triggered by user action. Success and error notifications based on user actions are created using a toast component. + +[Learn more about Bootstrap-vue alert options](https://bootstrap-vue.js.org/docs/components/alert) + +![Alert examples](./alert.png) + +```vue +This is a warning message +This is an error message +This is an info message +``` \ No newline at end of file diff --git a/docs/guide/components/info-tooltip/index.md b/docs/guide/components/info-tooltip/index.md new file mode 100644 index 00000000..25425475 --- /dev/null +++ b/docs/guide/components/info-tooltip/index.md @@ -0,0 +1,15 @@ +# InfoTooltip + +The `InfoTooltip` is a custom component that uses a Bootstrap-vue tooltip with an info icon. This custom component requires a title property containing the tooltip text to display to the user. + +[Read more about the Bootstrap-vue tooltip component](https://bootstrap-vue.org/docs/components/tooltip) + +## Example + +```vue + +``` + +![Tooltip example](./info-tooltip.png) diff --git a/docs/guide/components/info-tooltip/info-tooltip.png b/docs/guide/components/info-tooltip/info-tooltip.png new file mode 100644 index 00000000..7af1b7ae Binary files /dev/null and b/docs/guide/components/info-tooltip/info-tooltip.png differ diff --git a/docs/guide/components/page-section/index.md b/docs/guide/components/page-section/index.md new file mode 100644 index 00000000..ccf654e1 --- /dev/null +++ b/docs/guide/components/page-section/index.md @@ -0,0 +1,10 @@ +# Page section + +The `` component will render semantic HTML. By adding a `:section-title` prop to the `` component, the localized text string will be rendered in an `h2` header element. + +``` vue +// Example: `src/views/AccessControl/Ldap/Ldap.vue` + +``` + +[View the page section component source code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageSection.vue). \ No newline at end of file diff --git a/docs/guide/components/page-title/index.md b/docs/guide/components/page-title/index.md new file mode 100644 index 00000000..b51ab640 --- /dev/null +++ b/docs/guide/components/page-title/index.md @@ -0,0 +1,23 @@ +# Page title +The `` component will automatically render the page title that corresponds with the title property set in the route record's meta field in `src/router/routes.js`. + +```js +// src/router/routes.js + { + path: '', + name: 'login', + component: Login, + meta: { + title: i18n.t('appPageTitle.login'), + }, + }, +``` + +Optional page descriptions can be included by using the description prop `:description` prop and passing in the i18n localized text string. Translations are found in the `src/locales` folder. + +``` vue +// Example: `src/views/AccessControl/Ldap/Ldap.vue` + +``` + +[View the page title component source code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageTitle.vue). diff --git a/docs/guide/components/page.md b/docs/guide/components/page.md deleted file mode 100644 index 83106e37..00000000 --- a/docs/guide/components/page.md +++ /dev/null @@ -1,67 +0,0 @@ -# Page - -The essential building blocks of each page, or single-file component, consist of: -- `` -- `` -- `` - -```vue - -``` - -## Page container -Use the `fluid="xl"` prop on the `` component to render a container that is always 100% width on larger screen sizes. [Learn more about BootstrapVue containers](https://bootstrap-vue.org/docs/components/layout#responsive-fluid-containers). - -```vue - -``` - - -Within the page container, include the [page title](#/page-title) and [page section](#page-section) components. - -## Page title -The `` component will automatically render the page title that corresponds with the title property set in the route record's meta field in `src/router/routes.js`. - -```js -// src/router/routes.js - { - path: '', - name: 'login', - component: Login, - meta: { - title: i18n.t('appPageTitle.login'), - }, - }, -``` - -Optional page descriptions can be included by using the description prop `:description` prop and passing in the i18n localized text string. Translations are found in the `src/locales` folder. - -``` vue -// Example: `src/views/AccessControl/Ldap/Ldap.vue` - -``` - -[View the page title component source code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageTitle.vue). - -## Page section - -The `` component will render semantic HTML. By adding a `:section-title` prop to the `` component, the localized text string will be rendered in an `h2` header element. - -``` vue -// Example: `src/views/AccessControl/Ldap/Ldap.vue` - -``` - -[View the page section component source code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageSection.vue). - - [Visit the quick start guide](/guide/quickstart/page-anatomy) to learn how to build a single-file component using this page anatomy. \ No newline at end of file diff --git a/docs/guide/components/toast.md b/docs/guide/components/toast.md deleted file mode 100644 index fa8e56ee..00000000 --- a/docs/guide/components/toast.md +++ /dev/null @@ -1,32 +0,0 @@ -# Toasts -Use a toast message to indicate the status of a user action. For example, a user saves a form successfully, a toast message with the `success` variant is displayed. If the user action was not successful, a toast message with the `danger` variant is displayed. - -There are different transitions for the toast messages. The `success` toast message will auto-hide after 10 seconds. The user must manually dismiss the `informational`, `warning`, and `error` toast messages. The `BVToastMixin` provides a simple API that generates a toast message that meets the transition guidelines. - -Toast example - -```js{5} -// Sample method from Reboot BMC page -rebootBmc() { - this.$store - .dispatch('controls/rebootBmc') - .then(message => this.successToast(message)) - .catch(({ message }) => this.errorToast(message)); -} - -// Methods used in this example -methods: { - makeSuccessToast() { - this.successToast('This is a success toast and will be dismissed after 10 seconds.'); - }, - makeErrorToast() { - this.errorToast('This is an error toast and must be dismissed by the user.'); - }, - makeWarningToast() { - this.warningToast('This is a warning toast and must be dismissed by the user.'); - }, - makeInfoToast() { - this.infoToast('This is an info toast and must be dismissed by the user.'); - }, -} -``` \ No newline at end of file diff --git a/docs/guide/components/toasts/index.md b/docs/guide/components/toasts/index.md new file mode 100644 index 00000000..271155a9 --- /dev/null +++ b/docs/guide/components/toasts/index.md @@ -0,0 +1,32 @@ +# Toasts +Use a toast message to indicate the status of a user action. For example, a user saves a form successfully, a toast message with the `success` variant is displayed. If the user action was not successful, a toast message with the `danger` variant is displayed. + +There are different transitions for the toast messages. The `success` toast message will auto-hide after 10 seconds. The user must manually dismiss the `informational`, `warning`, and `error` toast messages. The `BVToastMixin` provides a simple API that generates a toast message that meets the transition guidelines. + +Toast message examples + +```js{5} +// Sample method from Reboot BMC page +rebootBmc() { + this.$store + .dispatch('controls/rebootBmc') + .then(message => this.successToast(message)) + .catch(({ message }) => this.errorToast(message)); +} + +// Methods used in this example +methods: { + makeSuccessToast() { + this.successToast('This is a success toast and will be dismissed after 10 seconds.'); + }, + makeErrorToast() { + this.errorToast('This is an error toast and must be dismissed by the user.'); + }, + makeWarningToast() { + this.warningToast('This is a warning toast and must be dismissed by the user.'); + }, + makeInfoToast() { + this.infoToast('This is an info toast and must be dismissed by the user.'); + }, +} +``` \ No newline at end of file diff --git a/docs/guide/components/toasts/toast.png b/docs/guide/components/toasts/toast.png new file mode 100644 index 00000000..97f9bc4c Binary files /dev/null and b/docs/guide/components/toasts/toast.png differ diff --git a/docs/guide/components/tooltip.md b/docs/guide/components/tooltip.md deleted file mode 100644 index ebc1a16d..00000000 --- a/docs/guide/components/tooltip.md +++ /dev/null @@ -1,15 +0,0 @@ -# InfoTooltip - -The `InfoTooltip` is a custom component that uses a Bootstrap-vue tooltip with an info icon. This custom component requires a title property containing the tooltip text to display to the user. - -[Read more about the Bootstrap-vue tooltip component](https://bootstrap-vue.org/docs/components/tooltip) - -## Example - -```vue - -``` - -![Tooltip example](/tooltip.png) diff --git a/docs/guide/quickstart/page-anatomy.md b/docs/guide/quickstart/page-anatomy.md index ed17c04e..120bf70b 100644 --- a/docs/guide/quickstart/page-anatomy.md +++ b/docs/guide/quickstart/page-anatomy.md @@ -7,7 +7,7 @@ When creating a new page, each template consists of at least 3 components: - `` - `` -Learn more about the [page container, page title and page section](/guide/components/page) components. +Learn more about the [page title](/guide/components/page-title)and [page section](/guide/components/page-section) components. ```vue