diff options
Diffstat (limited to 'docs/guide/components')
| -rw-r--r-- | docs/guide/components/alerts/index.md | 8 | ||||
| -rw-r--r-- | docs/guide/components/buttons/index.md | 12 | ||||
| -rw-r--r-- | docs/guide/components/file-upload/readme.md | 15 | ||||
| -rw-r--r-- | docs/guide/components/info-tooltip/index.md | 7 | ||||
| -rw-r--r-- | docs/guide/components/page-section/index.md | 7 | ||||
| -rw-r--r-- | docs/guide/components/page-title/index.md | 11 | ||||
| -rw-r--r-- | docs/guide/components/readme.md | 8 | ||||
| -rw-r--r-- | docs/guide/components/status-icon/readme.md | 3 | ||||
| -rw-r--r-- | docs/guide/components/table/index.md | 128 | ||||
| -rw-r--r-- | docs/guide/components/toasts/index.md | 24 |
10 files changed, 168 insertions, 55 deletions
diff --git a/docs/guide/components/alerts/index.md b/docs/guide/components/alerts/index.md index 9273f8e2..aa2c5e13 100644 --- a/docs/guide/components/alerts/index.md +++ b/docs/guide/components/alerts/index.md @@ -1,7 +1,11 @@ # 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. +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) +[Learn more about Bootstrap-vue alert +options](https://bootstrap-vue.js.org/docs/components/alert)  diff --git a/docs/guide/components/buttons/index.md b/docs/guide/components/buttons/index.md index da569a15..83b8e8a7 100644 --- a/docs/guide/components/buttons/index.md +++ b/docs/guide/components/buttons/index.md @@ -1,11 +1,17 @@ # Buttons -Buttons are used to perform an action. The main buttons in the application are the `primary` and `secondary` buttons. Buttons, like all Boostrap-vue components can be themed by setting the `variant` prop on the component to one of the [theme-color map keys](/guide/guidelines/colors). To create a button that looks like a link, set the variant value to `link`. +Buttons are used to perform an action. The main buttons in the application are +the `primary` and `secondary` buttons. Buttons, like all Boostrap-vue components +can be themed by setting the `variant` prop on the component to one of the +[theme-color map keys](/guide/guidelines/colors). To create a button that looks +like a link, set the variant value to `link`. -[Learn more about Bootstrap-vue buttons](https://bootstrap-vue.js.org/docs/components/button) +[Learn more about Bootstrap-vue +buttons](https://bootstrap-vue.js.org/docs/components/button) ### Icon only buttons -Add `btn-icon-only` class to the button and add `title` attribute to get helper text on hover over the button. +Add `btn-icon-only` class to the button and add `title` attribute to get helper +text on hover over the button. ### Enabled buttons diff --git a/docs/guide/components/file-upload/readme.md b/docs/guide/components/file-upload/readme.md index 49945308..fb833648 100644 --- a/docs/guide/components/file-upload/readme.md +++ b/docs/guide/components/file-upload/readme.md @@ -1,19 +1,24 @@ # FormFile -`FormFile` is a custom component wrapper around the Bootstrap-vue Form File component. The purpose of this component is to upload files to the BMC. +`FormFile` is a custom component wrapper around the Bootstrap-vue Form File +component. The purpose of this component is to upload files to the BMC. To use this component: 1. Import it into the single file component (SFC) 2. Add the `<form-file />` tag 3. Add the optional `id` , `disabled`, `accept` and `state` prop as required -[Learn more about the Bootstrap-vue Form File component](https://bootstrap-vue.org/docs/components/form-file) +[Learn more about the Bootstrap-vue Form File +component](https://bootstrap-vue.org/docs/components/form-file) ### Optional properties -- `id`- Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed -- `disabled` - When set to `true`, disables the component's functionality and places it in a disabled state +- `id`- Used to set the `id` attribute on the rendered content, and used as the + base to generate any additional element IDs as needed +- `disabled` - When set to `true`, disables the component's functionality and + places it in a disabled state - `accept` - Set value to specify which file types to allow -- `state` - Controls the validation state appearance of the component. `true` for valid, `false` for invalid, or `null` for no validation state +- `state` - Controls the validation state appearance of the component. `true` + for valid, `false` for invalid, or `null` for no validation state ## Example of form file diff --git a/docs/guide/components/info-tooltip/index.md b/docs/guide/components/info-tooltip/index.md index 25425475..b6117924 100644 --- a/docs/guide/components/info-tooltip/index.md +++ b/docs/guide/components/info-tooltip/index.md @@ -1,8 +1,11 @@ # 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. +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) +[Read more about the Bootstrap-vue tooltip +component](https://bootstrap-vue.org/docs/components/tooltip) ## Example diff --git a/docs/guide/components/page-section/index.md b/docs/guide/components/page-section/index.md index ccf654e1..2a8a22ef 100644 --- a/docs/guide/components/page-section/index.md +++ b/docs/guide/components/page-section/index.md @@ -1,10 +1,13 @@ # Page section -The `<page-section>` component will render semantic HTML. By adding a `:section-title` prop to the `<page-section>` component, the localized text string will be rendered in an `h2` header element. +The `<page-section>` component will render semantic HTML. By adding a +`:section-title` prop to the `<page-section>` component, the localized text +string will be rendered in an `h2` header element. ``` vue // Example: `src/views/AccessControl/Ldap/Ldap.vue` <page-section :section-title="$t('pageLdap.settings')"> ``` -[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 +[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 index b51ab640..db43f29f 100644 --- a/docs/guide/components/page-title/index.md +++ b/docs/guide/components/page-title/index.md @@ -1,5 +1,7 @@ # Page title -The `<page-title>` 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`. +The `<page-title>` 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 @@ -13,11 +15,14 @@ The `<page-title>` component will automatically render the page title that corre }, ``` -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. +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` <page-title :description="$t('pageLdap.pageDescription')" /> ``` -[View the page title component source code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageTitle.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/readme.md b/docs/guide/components/readme.md index f10a1317..aef688af 100644 --- a/docs/guide/components/readme.md +++ b/docs/guide/components/readme.md @@ -1,4 +1,10 @@ # Overview -Vue components are the building blocks of the OpenBMC Web UI. It uses both Boostrap-Vue components, as well as custom components. Using these components assures consistency throughout the application. They also improve the developer experience and increase efficiency. Review the existing components before using HTML markup. If the feature you're working on includes a new layout pattern, rather than adding raw markup to the page, consider creating a component that other sections of the application can use as well. +Vue components are the building blocks of the OpenBMC Web UI. It uses both +Boostrap-Vue components, as well as custom components. Using these components +assures consistency throughout the application. They also improve the developer +experience and increase efficiency. Review the existing components before using +HTML markup. If the feature you're working on includes a new layout pattern, +rather than adding raw markup to the page, consider creating a component that +other sections of the application can use as well. [Learn more about Vue components](https://vuejs.org/v2/guide/components.html)
\ No newline at end of file diff --git a/docs/guide/components/status-icon/readme.md b/docs/guide/components/status-icon/readme.md index 0c9cc394..aef1f93c 100644 --- a/docs/guide/components/status-icon/readme.md +++ b/docs/guide/components/status-icon/readme.md @@ -1,6 +1,7 @@ # StatusIcon -The StatusIcon component is used to add an icon that represents one of the following statuses: +The StatusIcon component is used to add an icon that represents one of the +following statuses: - success - info diff --git a/docs/guide/components/table/index.md b/docs/guide/components/table/index.md index cd1ba202..614ef60f 100644 --- a/docs/guide/components/table/index.md +++ b/docs/guide/components/table/index.md @@ -1,11 +1,16 @@ # Table -All tables in the application are using the [BoostrapVue table component](https://bootstrap-vue.org/docs/components/table). +All tables in the application are using the [BoostrapVue table +component](https://bootstrap-vue.org/docs/components/table). -To use the component, include the `<b-table>` tag in the template. The component is registered globally so does not need to be imported in each SFC. +To use the component, include the `<b-table>` tag in the template. The component +is registered globally so does not need to be imported in each SFC. ## Basic table -There are a few required properties to maintain consistency across the application. The full list of options can be viewed on the [Bootstrap-vue table component's documentation page](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-props). +There are a few required properties to maintain consistency across the +application. The full list of options can be viewed on the [Bootstrap-vue table +component's documentation +page](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-props). ### Required properties @@ -13,12 +18,15 @@ There are a few required properties to maintain consistency across the applicati - `items` - renders table items - `fields` - renders table header - `hover` - enables table row hover state -- `responsive` or `stacked` - makes the table responsive (enables horizontal scrolling or stacked view) at the defined breakpoint -- `show-empty` *(required if table data is generated dynamically)* - shows an empty message if there are no items in the table -- `empty-text` *(required if table data is generated dynamically)* - the translated empty message +- `responsive` or `stacked` - makes the table responsive (enables horizontal + scrolling or stacked view) at the defined breakpoint +- `show-empty` *(required if table data is generated dynamically)* - shows an + empty message if there are no items in the table +- `empty-text` *(required if table data is generated dynamically)* - the + translated empty message - - +  ```vue <template> @@ -68,7 +76,8 @@ There are a few required properties to maintain consistency across the applicati ## Sort -To enable table sort, include `sortable: true` in the fields array for sortable columns and add the following props to the `<b-table>` component: +To enable table sort, include `sortable: true` in the fields array for sortable +columns and add the following props to the `<b-table>` component: - `sort-by` - `no-sort-reset` @@ -119,17 +128,31 @@ export default { ## Expandable rows -To add an expandable row in the table, add a column for the expand button in the fields array. Include the tdClass `table-row-expand` to ensure icon rotation is handled. Use the built in [cell slot](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-slots) to target the expand button column and add a button with the chevron icon. +To add an expandable row in the table, add a column for the expand button in the +fields array. Include the tdClass `table-row-expand` to ensure icon rotation is +handled. Use the built in [cell +slot](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-slots) to +target the expand button column and add a button with the chevron icon. -Include the [TableRowExpandMixin](https://github.com/openbmc/webui-vue/blob/master/src/components/Mixins/TableRowExpandMixin.js). The mixin contains the dynamic `aria-label` and `title` attribute values that need to be included with the expand button. The `toggleRowDetails` method should be the button's click event callback. Be sure to pass the `row` object to the function. +Include the +[TableRowExpandMixin](https://github.com/openbmc/webui-vue/blob/master/src/components/Mixins/TableRowExpandMixin.js). +The mixin contains the dynamic `aria-label` and `title` attribute values that +need to be included with the expand button. The `toggleRowDetails` method should +be the button's click event callback. Be sure to pass the `row` object to the +function. -Use the [row-details slot](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-slots) to format the expanded row content. The slot has access to the row `item` property. +Use the [row-details +slot](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-slots) to +format the expanded row content. The slot has access to the row `item` property. ### Summary -1. Add a column for the expansion row button with the tdClass, `table-row-expand` -2. Include the `TableRowExpandMixin` to handle the dynamic aria label, title, and row expansion toggling -3. Use the `#cell` slot to target the expandable row column and add the button with accessible markup and click handler +1. Add a column for the expansion row button with the tdClass, + `table-row-expand` +2. Include the `TableRowExpandMixin` to handle the dynamic aria label, title, + and row expansion toggling +3. Use the `#cell` slot to target the expandable row column and add the button + with accessible markup and click handler 4. Use the `#row-details` slot to format expanded row content  @@ -185,15 +208,28 @@ export default { ## Search -The table is leveraging [BootstrapVue table filtering](https://bootstrap-vue.org/docs/components/table#filtering) for search. Add the [@filtered](https://bootstrap-vue.org/docs/components/table#filter-events) event listener onto the `<b-table>` component. The event callback should track the total filtered items count. +The table is leveraging [BootstrapVue table +filtering](https://bootstrap-vue.org/docs/components/table#filtering) for +search. Add the +[@filtered](https://bootstrap-vue.org/docs/components/table#filter-events) event +listener onto the `<b-table>` component. The event callback should track the +total filtered items count. -Import the `<search>` and `<table-cell-count>` components and include them in the template above the `<b-table>` component. +Import the `<search>` and `<table-cell-count>` components and include them in +the template above the `<b-table>` component. -Include the [SearchFilterMixin](https://github.com/openbmc/webui-vue/blob/master/src/components/Mixins/SearchFilterMixin.js). Add the `@change-search` and `@clear-search` event listeners on the `<search>` component and use the corresponding `onChangeSearchInput` and `onClearSearchInput` methods as the event callbacks. The table should also include the dynamic `:filter` prop with `searchFilter` set as the value. +Include the +[SearchFilterMixin](https://github.com/openbmc/webui-vue/blob/master/src/components/Mixins/SearchFilterMixin.js). +Add the `@change-search` and `@clear-search` event listeners on the `<search>` +component and use the corresponding `onChangeSearchInput` and +`onClearSearchInput` methods as the event callbacks. The table should also +include the dynamic `:filter` prop with `searchFilter` set as the value. -The `<table-cell-count>` component requires two properties, total table item count and total filtered items count. +The `<table-cell-count>` component requires two properties, total table item +count and total filtered items count. -Add the `:empty-filtered-text` prop to the table to show the translated message if there are no search matches. +Add the `:empty-filtered-text` prop to the table to show the translated message +if there are no search matches.  @@ -261,9 +297,14 @@ export default { ## Row actions -To add table row actions, add a column for the action buttons in the table. Then in the array of table items, add a corresponding array of actions for each item. The array should have each desired row action with a `value` and `title` property. +To add table row actions, add a column for the action buttons in the table. Then +in the array of table items, add a corresponding array of actions for each item. +The array should have each desired row action with a `value` and `title` +property. -Import the `<table-row-action>` component. Provide the `value` and `title` props to the component and use the named `#icons` slot to include an icon. The component will emit a `@click-table-action` with the event value. +Import the `<table-row-action>` component. Provide the `value` and `title` props +to the component and use the named `#icons` slot to include an icon. The +component will emit a `@click-table-action` with the event value.  @@ -343,11 +384,17 @@ export default { To add a table dropdown filter: 1. Import the `<table-filter> `component and TableFilterMixin. -1. Add a filters prop to the `<table-filters>` component. This prop should be an array of filter groups–each required to have a key, label, and values prop. +1. Add a filters prop to the `<table-filters>` component. This prop should be an + array of filter groups–each required to have a key, label, and values prop. -The `label` prop value should be the translated filter group label. The `key` prop will usually match the filtered by table column key. The `values` prop should be an array of filter values that will render as a list of checkbox items in the dropdown. +The `label` prop value should be the translated filter group label. The `key` +prop will usually match the filtered by table column key. The `values` prop +should be an array of filter values that will render as a list of checkbox items +in the dropdown. -The component will emit a `@filter-change` event that will provide the filter group and all selected values in the group. Use the getFilteredTableData method from the TableFilterMixin to show the filtered table data. +The component will emit a `@filter-change` event that will provide the filter +group and all selected values in the group. Use the getFilteredTableData method +from the TableFilterMixin to show the filtered table data.  @@ -410,18 +457,36 @@ export default { ### Date filter -To add a date filter, import the `<table-date-filter>` component. It will emit a `@change` event with the user input date values. There is a date filter method, `getFilteredTableDataByDate`, in the `TableFilterMixin`. +To add a date filter, import the `<table-date-filter>` component. It will emit a +`@change` event with the user input date values. There is a date filter method, +`getFilteredTableDataByDate`, in the `TableFilterMixin`. ## Batch actions -Batch actions allow a user to take a single action on many items in a table at once. +Batch actions allow a user to take a single action on many items in a table at +once. To add table batch actions: 1. Import the `<table-toolbar> `component and BVTableSelectableMixin -1. Add the `selectable`, `no-select-on-click` props and a unique `ref` to the table. The table will emit a `@row-selected` event. Use the `onRowSelected` mixin method as a callback and provide the `$event` as the first argument and the total table items count as the second argument. -1. Add a table column for checkboxes. The table header checkbox should use the `tableHeaderCheckboxModel` and `tableHeaderCheckboxIndeterminate` values provided by the mixin. The table header checkbox should also use the `onChangeHeaderCheckbox` method as a callback for the `@change` event with the table `ref` passed as an argument. The table row checkboxes should use the `toggleSelectRow` method as a callback for the `@change` event with the table `ref` passed as the first argument and the row index passed as the second argument. -1. Add an actions prop to the `<table-toolbar>` component. This prop should be an array of toolbar actions–required to have a value and label prop. Add the `selected-items-count` prop to the `<table-toolbar>` component. The component will emit a `@batch-action` event that will provide the user selected action. It will also emit a `@clear-selected` event. Provide the `clearSelectedRows` as a callback with the table `ref` passed as an argument. +1. Add the `selectable`, `no-select-on-click` props and a unique `ref` to the + table. The table will emit a `@row-selected` event. Use the `onRowSelected` + mixin method as a callback and provide the `$event` as the first argument and + the total table items count as the second argument. +1. Add a table column for checkboxes. The table header checkbox should use the + `tableHeaderCheckboxModel` and `tableHeaderCheckboxIndeterminate` values + provided by the mixin. The table header checkbox should also use the + `onChangeHeaderCheckbox` method as a callback for the `@change` event with + the table `ref` passed as an argument. The table row checkboxes should use + the `toggleSelectRow` method as a callback for the `@change` event with the + table `ref` passed as the first argument and the row index passed as the + second argument. +1. Add an actions prop to the `<table-toolbar>` component. This prop should be + an array of toolbar actions–required to have a value and label prop. Add the + `selected-items-count` prop to the `<table-toolbar>` component. The component + will emit a `@batch-action` event that will provide the user selected action. + It will also emit a `@clear-selected` event. Provide the `clearSelectedRows` + as a callback with the table `ref` passed as an argument.  @@ -512,7 +577,8 @@ export default { To add table pagination: 1. Import the BVPaginationMixin 1. Add the `per-page` and `current-page` props to the `<table>` component. -1. Add the below HTML snippet to the template. Make sure to update the `total-rows` prop. +1. Add the below HTML snippet to the template. Make sure to update the + `total-rows` prop. ```vue{21} <b-row> diff --git a/docs/guide/components/toasts/index.md b/docs/guide/components/toasts/index.md index 2e695f6a..3f0c815d 100644 --- a/docs/guide/components/toasts/index.md +++ b/docs/guide/components/toasts/index.md @@ -1,7 +1,14 @@ # 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. +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. +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. <img src="./toast.png" alt="Toast message examples" style="max-width:350px"> @@ -33,11 +40,18 @@ methods: { ## Additional options -The first argument for each method will be the toast body content. It accepts a string value or an array of strings for toasts needing to display multiple lines of content. +The first argument for each method will be the toast body content. It accepts a +string value or an array of strings for toasts needing to display multiple lines +of content. -The BVToastMixin also accepts additional options as a second argument. Pass an object with a `title` property to change the default toast title. Include a `refreshAction` property, set to true, to include a link that refreshes the application. Include a `timestamp` property, set to true, to include a timestamp in the toast. +The BVToastMixin also accepts additional options as a second argument. Pass an +object with a `title` property to change the default toast title. Include a +`refreshAction` property, set to true, to include a link that refreshes the +application. Include a `timestamp` property, set to true, to include a timestamp +in the toast. -<img src="./toast-options.png" alt="Toast message options example" style="max-width:350px"> +<img src="./toast-options.png" alt="Toast message options example" +style="max-width:350px"> ```js |