diff options
| author | Patrick Williams <patrick@stwcx.xyz> | 2022-12-08 15:13:13 +0300 |
|---|---|---|
| committer | Patrick Williams <patrick@stwcx.xyz> | 2022-12-08 15:13:13 +0300 |
| commit | 7385e139b0c9efca7430458cee982e63e282f4ae (patch) | |
| tree | 1bbdb0164e556b76eec72cb558c66974c8f95dd8 /docs | |
| parent | b24a483eda5ca0b0ecdb4f0c61b90d76d0d8e1e0 (diff) | |
| download | webui-vue-7385e139b0c9efca7430458cee982e63e282f4ae.tar.xz | |
prettier: re-format
Prettier is enabled in openbmc-build-scripts on Markdown, JSON, and YAML
files to have consistent formatting for these file types. Re-run the
formatter on the whole repository.
Change-Id: I2804ee3ab5ff6bcbf986b028db2fafec8e616779
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Diffstat (limited to 'docs')
25 files changed, 394 insertions, 372 deletions
diff --git a/docs/customization/build.md b/docs/customization/build.md index b10fd9db..4bdbd50a 100644 --- a/docs/customization/build.md +++ b/docs/customization/build.md @@ -26,19 +26,14 @@ VUE_APP_ENV_NAME=ibm ## Store -:::tip -[Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain the -application's API calls. -::: +:::tip [Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain +the application's API calls. ::: 1. If making customizations to the default store, add `CUSTOM_STORE=true` key value pair to the new .env file. -2. Create a `<ENV_NAME>.js` file in `src/env/store` - :::danger - The filename needs to match the `VUE_APP_ENV_NAME` value defined in the - .env file. The store import in `src/main.js` will resolve to this new - file. - ::: +2. Create a `<ENV_NAME>.js` file in `src/env/store` :::danger The filename needs + to match the `VUE_APP_ENV_NAME` value defined in the .env file. The store + import in `src/main.js` will resolve to this new file. ::: 3. Import the base store 4. Import environment specific store modules 5. Use the [Vuex](https://vuex.vuejs.org/api/#registermodule) `registerModule` @@ -58,24 +53,17 @@ export default store; ## Router -:::tip -[Vue Router](https://router.vuejs.org/guide/) determines which pages are -accessible in the UI. -::: +:::tip [Vue Router](https://router.vuejs.org/guide/) determines which pages are +accessible in the UI. ::: 1. If making customizations to the default router, add `CUSTOM_ROUTER=true` key value pair to the new .env file. -2. Create a `<ENV_NAME>.js` file in `src/env/router` - :::danger - The filename needs to match the `VUE_APP_ENV_NAME` value defined in the - .env file. The routes import in `src/router/index.js` will resolve to this - new file. - ::: -3. Define new [routes](https://router.vuejs.org/api/#routes). - :::tip - Use static imports (over lazy-loading routes) to avoid creating separate - JS chunks. Static imports also helps to keep the total build size down. - ::: +2. Create a `<ENV_NAME>.js` file in `src/env/router` :::danger The filename + needs to match the `VUE_APP_ENV_NAME` value defined in the .env file. The + routes import in `src/router/index.js` will resolve to this new file. ::: +3. Define new [routes](https://router.vuejs.org/api/#routes). :::tip Use static + imports (over lazy-loading routes) to avoid creating separate JS chunks. + Static imports also helps to keep the total build size down. ::: 4. Add default export ## App navigation @@ -88,13 +76,11 @@ in src/components/AppNavigation/AppNavigation.vue. 1. If making customizations to the app navigation, add `CUSTOM_APP_NAV=true` key value pair to the new .env file. -2. Create a `<ENV_NAME>.js` file in `src/env/components/AppNavigation` - :::danger - The filename needs to match the `VUE_APP_ENV_NAME` value defined in the - .env file. The AppNavigationMixin import in +2. Create a `<ENV_NAME>.js` file in `src/env/components/AppNavigation` :::danger + The filename needs to match the `VUE_APP_ENV_NAME` value defined in the .env + file. The AppNavigationMixin import in `src/components/AppNavigation/AppNavigation.vue` will resolve to this new - file. - ::: + file. ::: 3. Your custom mixin should follow a very similar structure to the default AppNavigationMixin.js file. It should include a data property named `navigationItems` that should be an array of of navigation objects. Each @@ -106,22 +92,20 @@ in src/components/AppNavigation/AppNavigation.vue. :::tip [Bootstrap theming](https://getbootstrap.com/docs/4.5/getting-started/theming/) -allows for easy visual customizations. -::: +allows for easy visual customizations. ::: 1. If making customizations to the default styles, add `CUSTOM_STYLES=true` key value pair to the new .env file. -2. Create a `_<ENV_NAME>.scss` partial in `src/env/assets/styles` - :::danger - The filename needs to match the `VUE_APP_ENV_NAME` value defined in the - .env file. The webpack sass loader will attempt to import a file with this - name. +2. Create a `_<ENV_NAME>.scss` partial in `src/env/assets/styles` :::danger The + filename needs to match the `VUE_APP_ENV_NAME` value defined in the .env + file. The webpack sass loader will attempt to import a file with this name. ::: -3. Add style customizations. Refer to [bootstrap documentation](https://getbootstrap.com/docs/4.5/getting-started/theming/) - for details about [color - overrides](https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults) - and [other customizable - options](https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options). +3. Add style customizations. Refer to + [bootstrap documentation](https://getbootstrap.com/docs/4.5/getting-started/theming/) + for details about + [color overrides](https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults) + and + [other customizable options](https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options). Example for adding custom colors @@ -145,9 +129,9 @@ $success: lime; ## Production build -Run npm build script with vue-cli `--mode` [option -flag](https://cli.vuejs.org/guide/mode-and-env.html#modes). This requires -[corresponding .env file to exist](#setup). +Run npm build script with vue-cli `--mode` +[option flag](https://cli.vuejs.org/guide/mode-and-env.html#modes). This +requires [corresponding .env file to exist](#setup). ``` npm run build -- --mode ibm diff --git a/docs/customization/readme.md b/docs/customization/readme.md index 64118060..9f808ea8 100644 --- a/docs/customization/readme.md +++ b/docs/customization/readme.md @@ -3,15 +3,14 @@ This section discusses the structure and purpose of the SCSS files and how to customize the application using Bootstrap theming. -[Read more about Bootstrap -Theming](https://getbootstrap.com/docs/4.0/getting-started/theming) +[Read more about Bootstrap Theming](https://getbootstrap.com/docs/4.0/getting-started/theming) ## SCSS Directory Structure ### `bmc` Directory -The `bmc` directory contains Sass helpers and default styles for customizing the OpenBMC -Web UI. +The `bmc` directory contains Sass helpers and default styles for customizing the +OpenBMC Web UI. ```{5} . @@ -84,9 +83,9 @@ variables that establish the custom theme of the application. #### `_colors.scss` -The `_colors.scss` file sets all the SASS variables and color maps for the OpenBMC -Web UI. Any color settings needed to meet company brand guidelines will happen -in this file. +The `_colors.scss` file sets all the SASS variables and color maps for the +OpenBMC Web UI. Any color settings needed to meet company brand guidelines will +happen in this file. ##### Sass Color Variables @@ -161,12 +160,9 @@ $theme-colors: ( ##### Color Resources -- [Learn more about Bootstrap - colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color) -- [Learn more about Bootstrap - variables](https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables) -- [View the color palette and hex values in the color - guidelines](/guide/guidelines/colors) +- [Learn more about Bootstrap colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color) +- [Learn more about Bootstrap variables](https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables) +- [View the color palette and hex values in the color guidelines](/guide/guidelines/colors) #### `_functions.scss` @@ -254,10 +250,8 @@ $exit-easing--expressive: cubic-bezier(0.4, 0.14, 1, 1); ##### Motion Resources -- [Including Animation In Your Design - System](https://www.smashingmagazine.com/2019/02/animation-design-system/) -- [Carbon Design System motion - guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/) +- [Including Animation In Your Design System](https://www.smashingmagazine.com/2019/02/animation-design-system/) +- [Carbon Design System motion guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/) #### `_variables.scss` @@ -307,10 +301,8 @@ components, and utility styles. The `obmc-custom.scss` file defines all of the presentational layer dependencies. -- [Read more about Bootstrap - options](https://getbootstrap.com/docs/4.0/getting-started/theming/#sass-options) -- [Read more about - Importing](https://getbootstrap.com/docs/4.0/getting-started/theming/#importing) +- [Read more about Bootstrap options](https://getbootstrap.com/docs/4.0/getting-started/theming/#sass-options) +- [Read more about Importing](https://getbootstrap.com/docs/4.0/getting-started/theming/#importing) ## Component / View Styles @@ -359,9 +351,9 @@ CSS styles correctly. </style> ``` -:::tip -You might notice that there is an HTML element, `<h2>`, used in the example. This is an anti-pattern in global `.scss` files. However, in a single file component that generates the markup it is acceptable. -::: +:::tip You might notice that there is an HTML element, `<h2>`, used in the +example. This is an anti-pattern in global `.scss` files. However, in a single +file component that generates the markup it is acceptable. ::: [Learn more about single file components](https://vuejs.org/v2/guide/single-file-components.html) diff --git a/docs/customization/theme.md b/docs/customization/theme.md index 6dbce1a9..10e062d3 100644 --- a/docs/customization/theme.md +++ b/docs/customization/theme.md @@ -1,10 +1,12 @@ # Theme customization + Customization of the application requires knowledge of Sass and CSS. It also will require becoming familiar with the Bootstrap and Bootstrap-Vue component libraries. This section outlines the global options and variables that can be removed or updated to meet organizational brand guidelines. ## Environment specific builds + Any organization can create a build that meets their branding and other customization needs. This includes customization of the state store, routing, application navigation, and theming. @@ -12,59 +14,68 @@ application navigation, and theming. [Read more in the Build Customization section](/customization/build) ### Configuring environment specific builds + The complete instructions can be found in the `env` directory in a file called -env.md or by viewing the [Configuring environment specific builds -page](./env.md) +env.md or by viewing the +[Configuring environment specific builds page](./env.md) ## Bootstrap Sass Options + The Bootstrap Sass options are global styling toggles. The naming convention for these built-in variables is `enabled-*`. ### $enable-rounded + This option enables or disables the border-radius styles on various components. - Set to `false` to remove rounded corners on all container elements and buttons ### $enable-validation-icons + This option enables or disables background-image icons within textual inputs and some custom forms for validation states. - Set to `false` due to inability to style icons using CSS ### More information -- [View all the Bootstrap Sass - Options](https://getbootstrap.com/docs/4.2/getting-started/theming/#sass-options) + +- [View all the Bootstrap Sass Options](https://getbootstrap.com/docs/4.2/getting-started/theming/#sass-options) ## Bootstrap Sass Variables + These are global variables that Bootstrap defines in the `/node_modules/bootstrap/scss/variables.scss` helper file. Adding a variable listed in this file to the `/src/assets/styles/bmc/helpers/_variables.scss` file will override the Bootstrap defined value. ### $transition-base + This variable sets the base CSS transition style throughout the application. + - Set to `all $duration--moderate-02 $standard-easing--productive` ### $transition-fade + This variable sets the transition when showing and hiding elements. - Set to `opacity $duration--moderate-01 $standard-easing--productive` ### $transition-collapse + This variable sets the CSS transitions throughout the application when expanding and collapsing elements. - Set to `height $duration--slow-01 $standard-easing--expressive` ### More Information -- [Carbon Design System Motion - Guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/) -- [Including Animation In Your Design - System](https://www.smashingmagazine.com/2019/02/animation-design-system/) + +- [Carbon Design System Motion Guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/) +- [Including Animation In Your Design System](https://www.smashingmagazine.com/2019/02/animation-design-system/) ## OpenBMC Custom Sass Options ### $responsive-layout-bp + This variable determines when the primary navigation is hidden and when the hamburger menu is displayed. The breakpoint is defined using a Bootstrap function that only accepts a key from the Bootstrap `$grid-breakpoints` map. @@ -76,46 +87,52 @@ function that only accepts a key from the Bootstrap `$grid-breakpoints` map. - xl - Navigation displayed when the viewport is less than 1200px #### Responsive Resources -- [Bootstrap responsive - breakpoints](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints) -- [Bootstrap Sass - Mixins](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints) -- [Customizing the Bootstrap - Grid](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints) + +- [Bootstrap responsive breakpoints](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints) +- [Bootstrap Sass Mixins](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints) +- [Customizing the Bootstrap Grid](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints) ### $header-height + This variable determines the height of the OpenBMC Web UI header element. - Default value: 56px ### $navigation-width + This variable determines the width of the primary navigation menu when expanded. - Default value: 300px ### $container-bgd + This option sets the background of page containers. Changing the value of this variable will change the background color for the following elements: -- Login page + +- Login page - Primary navigation section - Quick links section on the overview page #### Value + - Default value: $gray-200 ### $primary-nav-hover + The semantic naming of this variable identifies its purpose. This color should always be slightly darker than the `$container-bgd` value. - Default value: $gray-300 ## Updating Colors + Supporting a different color palette is a simple process. The default color palette is supported using the Sass variables outlined in the color guidelines -and color maps outlined in the theme's overview. The following sections provide +and color maps outlined in the theme's overview. The following sections provide directions to update the settings to meet your organization's needs. ### Color + The OpenBMC Web UI uses Sass variables and maps to build its layout and components. Bootstrap variables and maps use the `!default` flag to allow for overrides. There are three Sass maps created to establish the color palette. @@ -123,6 +140,7 @@ These include the `color` map, `theme-color` map, and `gray` map. These maps are used by Bootstrap to build the application's CSS stylesheets. #### All Colors + The OpenBMC Web UI custom colors are available as Sass variables and a Sass map in `/src/assets/styles/bmc/helpers/_variables.scss`. The OpenBMC theme only requires a subset of the colors to create the look and feel of the application. @@ -137,6 +155,7 @@ keys for customization. Using these keys in Sass stylesheets or single-file components is discouraged. #### Theme Colors + The theme color variables and the `theme-color` map consist of a subset of the color variables. This smaller color palette creates a scheme that is not dependent on specific colors like blue or green. Several of the Bootstrap @@ -151,6 +170,7 @@ at the [color guidelines](/guide/guidelines/colors) to better understand default theme-colors map. #### Gray Colors + The gray color palette contains nine shades of gray that range from light to dark. Bootstrap sets a default gray color value for each color variable from 100-900 in increments of one hundred, for example, `$gray-100`, `$gray-200`, @@ -160,16 +180,16 @@ maps for all the default colors is scheduled to be delivered in a future patch. The OpenBMC Web UI color theme overrides all shades of the Bootstrap default gray variable values. -[Learn more about Bootstrap -colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color) +[Learn more about Bootstrap colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color) ### Bootstrap Color Functions + - `color('<color map key>)` - `theme-color('<theme color map key>)` - `gray('<gray color palette key'>)` - #### Example + ```SCSS .some-selector { color: color("blue"); @@ -178,9 +198,10 @@ colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color) } ``` -[Learn more about using Bootstrap -functions](https://getbootstrap.com/docs/4.0/getting-started/theming/#functions) +[Learn more about using Bootstrap functions](https://getbootstrap.com/docs/4.0/getting-started/theming/#functions) + ## Adding a logo + The updated page header can include a small logo. The guidelines for adding a logo and the suggested logo dimensions are currently in progress. It may be challenging to meet all organization brand guidelines due to the minimal height diff --git a/docs/guide/coding-standards/accessibility.md b/docs/guide/coding-standards/accessibility.md index 0a9a1a75..63cc870f 100644 --- a/docs/guide/coding-standards/accessibility.md +++ b/docs/guide/coding-standards/accessibility.md @@ -2,18 +2,19 @@ It is important that the OpenBMC Web UI meet accessibility guidelines established by the [World Wide Web Consortium (W3C)](https://www.w3.org/). These -guidelines are known as the [Web Content Accessibility Guidelines -(WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/). Making the Web UI -accessible to as many users as possible is the right thing to do. In many -countries, it is also legally required. Organizations providing interfaces that -users with permanent or temporary disabilities can not use, may lose sales or be -susceptible to discriminatory lawsuits. +guidelines are known as the +[Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/). +Making the Web UI accessible to as many users as possible is the right thing to +do. In many countries, it is also legally required. Organizations providing +interfaces that users with permanent or temporary disabilities can not use, may +lose sales or be susceptible to discriminatory lawsuits. ## Accessibility Principles + These [principles](https://www.w3.org/WAI/fundamentals/accessibility-principles/) -reference a set of international standards from the [W3C Web Accessibility -Intitiative (WAI)](https://www.w3.org/WAI/). +reference a set of international standards from the +[W3C Web Accessibility Intitiative (WAI)](https://www.w3.org/WAI/). - [Perceiveable](https://www.w3.org/WAI/fundamentals/accessibility-principles/#perceivable) - [Operable](https://www.w3.org/WAI/fundamentals/accessibility-principles/#operable) @@ -21,6 +22,7 @@ Intitiative (WAI)](https://www.w3.org/WAI/). - [Robust](https://www.w3.org/WAI/fundamentals/accessibility-principles/#robust) ## Semantic HTML + Coding the UI using semantic markup is the most important step in creating an inclusive interface. The use of [WAI-ARIA](https://www.w3.org/WAI/standards-guidelines/aria/) can help make an @@ -31,6 +33,7 @@ rules to follow: 2. No ARIA is better than Bad ARIA ## Testing + Assuring the Web UI meets accessibility guidelines requires a combination of automated and manual testing. Automated tests will test the application against common problems such as color contrast and ARIA use. Automated testing can be @@ -41,35 +44,32 @@ The OpenBMC Web UI developers should test their development pages using one of the tools listed in the tools section below. If using Chrome, the Lighthouse application comes bundled with the browser and also includes testing for performance and best practices. If there is an issue that is created when using -a Bootstrap-Vue component, we can [create an issue in the Bootstrap-vue -repo](https://github.com/bootstrap-vue/bootstrap-vue/issues/new/choose). +a Bootstrap-Vue component, we can +[create an issue in the Bootstrap-vue repo](https://github.com/bootstrap-vue/bootstrap-vue/issues/new/choose). Contributing to the Bootstrap-Vue open-source library, when possible, is strongly encouraged. ## Tools + - [Deque Axe](https://www.deque.com/axe/) -- [Firefox Accessibility - Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector) +- [Firefox Accessibility Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector) - [IBM Accessibility Tools](https://www.ibm.com/able/toolkit/tools) - [Lighthouse](https://developers.google.com/web/tools/lighthouse) ## Screen Readers + - [Jaws - (Windows only)](https://webaim.org/articles/jaws/) -- [Narrator - (Windows - only)](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1) +- [Narrator - (Windows only)](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1) - [NVDA (Windows only)](https://webaim.org/articles/nvda/) - [Voiceover (Mac only)](https://webaim.org/articles/voiceover/) ## Resources -- [Mozilla Developer Network - - Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) -- [Web Content Accessibility Guidelines - (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) + +- [Mozilla Developer Network - Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) +- [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) - [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/) -- [WAI-ARIA - Basics](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics) +- [WAI-ARIA Basics](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics) - [WebAIM Articles](https://webaim.org/articles/) - [A11Y Project](https://a11yproject.com/) - [IBM Accessibility](https://www.ibm.com/able/) - [Inclusive Components](https://inclusive-components.design/) - diff --git a/docs/guide/coding-standards/readme.md b/docs/guide/coding-standards/readme.md index a6ab3669..48d6cfc7 100644 --- a/docs/guide/coding-standards/readme.md +++ b/docs/guide/coding-standards/readme.md @@ -1,31 +1,36 @@ # JavaScript and SASS + This project uses the following libraries to determine the best practices and guidelines for both SCSS and JavaScript syntax. + - [ESLint](https://eslint.org/) - [Prettier](https://prettier.io/) - [ESLint Plugin for Vue](https://eslint.vuejs.org/) The guidelines we are following are: -- [Vue - Recommended](https://eslint.vuejs.org/rules/#priority-c-recommended-minimizing-arbitrary-choices-and-cognitive-overhead-for-vue-js-3-x) + +- [Vue Recommended](https://eslint.vuejs.org/rules/#priority-c-recommended-minimizing-arbitrary-choices-and-cognitive-overhead-for-vue-js-3-x) - [ESLint Recommended](https://eslint.org/docs/rules/) - [Prettier](https://prettier.io/docs/en/options.html) The rules are applied in the following order: + 1. Vue rules 1. ESLint recommended 1. Prettier ## Overrides + Any overrides to a rule are located in the ESLint configuration file, `.eslintrc.js`, located in the root directory. ## Running the lint test + To test all files for linting, run `npm run lint`. This command will evaluate the syntax of all files and update any code that that does not require manual review. -The linting script runs when code is committed, during pre-commit, and when the +The linting script runs when code is committed, during pre-commit, and when the CI tool runs after a push to Gerrit. There is a shell script named `format-code.sh` that installs node package dependencies and runs the test -script in your CI.
\ No newline at end of file +script in your CI. diff --git a/docs/guide/components/alerts/index.md b/docs/guide/components/alerts/index.md index aa2c5e13..0ce5167c 100644 --- a/docs/guide/components/alerts/index.md +++ b/docs/guide/components/alerts/index.md @@ -1,11 +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. -[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)  @@ -13,4 +13,4 @@ options](https://bootstrap-vue.js.org/docs/components/alert) <alert show variant="warning">This is a warning message</alert> <alert show variant="danger">This is an error message</alert> <alert show variant="info">This is an info message</alert> -```
\ No newline at end of file +``` diff --git a/docs/guide/components/buttons/index.md b/docs/guide/components/buttons/index.md index 83b8e8a7..251316ff 100644 --- a/docs/guide/components/buttons/index.md +++ b/docs/guide/components/buttons/index.md @@ -6,10 +6,10 @@ 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. @@ -57,4 +57,4 @@ text on hover over the button. <b-button disabled variant="link" title="Delete" class="btn-icon-only"> <icon-trashcan /> </b-button> -```
\ No newline at end of file +``` diff --git a/docs/guide/components/file-upload/readme.md b/docs/guide/components/file-upload/readme.md index fb833648..e0819a85 100644 --- a/docs/guide/components/file-upload/readme.md +++ b/docs/guide/components/file-upload/readme.md @@ -4,12 +4,13 @@ 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 @@ -23,10 +24,7 @@ component](https://bootstrap-vue.org/docs/components/form-file) ## Example of form file ```vue -<form-file - id="image-file" - accept=".tar" - > +<form-file id="image-file" accept=".tar"> </form-file> ``` diff --git a/docs/guide/components/info-tooltip/index.md b/docs/guide/components/info-tooltip/index.md index b6117924..4b6416c9 100644 --- a/docs/guide/components/info-tooltip/index.md +++ b/docs/guide/components/info-tooltip/index.md @@ -4,15 +4,12 @@ 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 ```vue -<info-tooltip - :title="Title" //should be translated -/> +<info-tooltip :title="Title" //should be translated /> ```  diff --git a/docs/guide/components/page-section/index.md b/docs/guide/components/page-section/index.md index 2a8a22ef..94113c58 100644 --- a/docs/guide/components/page-section/index.md +++ b/docs/guide/components/page-section/index.md @@ -4,10 +4,9 @@ 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 +```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). diff --git a/docs/guide/components/page-title/index.md b/docs/guide/components/page-title/index.md index db43f29f..2f635e74 100644 --- a/docs/guide/components/page-title/index.md +++ b/docs/guide/components/page-title/index.md @@ -1,4 +1,5 @@ # 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`. @@ -19,10 +20,9 @@ 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 +```vue // Example: `src/views/AccessControl/Ldap/Ldap.vue` - <page-title :description="$t('pageLdap.pageDescription')" /> +<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 aef688af..b200b305 100644 --- a/docs/guide/components/readme.md +++ b/docs/guide/components/readme.md @@ -1,4 +1,5 @@ # 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 @@ -7,4 +8,4 @@ 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 +[Learn more about Vue components](https://vuejs.org/v2/guide/components.html) diff --git a/docs/guide/components/status-icon/readme.md b/docs/guide/components/status-icon/readme.md index aef1f93c..e2041986 100644 --- a/docs/guide/components/status-icon/readme.md +++ b/docs/guide/components/status-icon/readme.md @@ -9,6 +9,7 @@ following statuses: - danger To use this component: + 1. Import it into the single file component (SFC) 2. Add the `<status-icon />` tag 3. Add the optional status prop and set the value to one of the statuses @@ -29,9 +30,7 @@ import StatusIcon from '@/components/Global/StatusIcon' ## Status icon with success status ```vue -<status-icon -:status="success" -/> +<status-icon :status="success" /> ```  @@ -39,9 +38,7 @@ import StatusIcon from '@/components/Global/StatusIcon' ## Status icon with info status ```vue -<status-icon -:status="info" -/> +<status-icon :status="info" /> ```  @@ -49,9 +46,7 @@ import StatusIcon from '@/components/Global/StatusIcon' ## Status icon with warning status ```vue -<status-icon -:status="warning" -/> +<status-icon :status="warning" /> ```  @@ -59,9 +54,7 @@ import StatusIcon from '@/components/Global/StatusIcon' ## Status icon with danger status ```vue -<status-icon -:status="danger" -/> +<status-icon :status="danger" /> ```  diff --git a/docs/guide/components/table/index.md b/docs/guide/components/table/index.md index 614ef60f..47bc51d8 100644 --- a/docs/guide/components/table/index.md +++ b/docs/guide/components/table/index.md @@ -1,17 +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. ## 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 @@ -20,12 +19,13 @@ page](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-props). - `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 +- `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 +- `empty-text` _(required if table data is generated dynamically)_ - the translated empty message -  + ```vue @@ -41,36 +41,36 @@ example](./table-empty.png) </template> <script> - export default { - data() { - items: [ - { - name: 'Babe', - age: '3 years', - color: 'white, orange, grey' - }, - { - name: 'Grey Boy', - age: '4 months', - color: 'grey' - }, - ], - fields: [ - { - key: 'name', - label: this.$t('table.name') //translated label - }, - { - key: 'age', - label: this.$t('table.age') //translated label - }, - { - key: 'color', - label: this.$t('table.color') // translated label - } - ] - } +export default { + data() { + items: [ + { + name: 'Babe', + age: '3 years', + color: 'white, orange, grey' + }, + { + name: 'Grey Boy', + age: '4 months', + color: 'grey' + }, + ], + fields: [ + { + key: 'name', + label: this.$t('table.name') //translated label + }, + { + key: 'age', + label: this.$t('table.age') //translated label + }, + { + key: 'color', + label: this.$t('table.color') // translated label + } + ] } +} </script> ``` @@ -85,7 +85,6 @@ columns and add the following props to the `<b-table>` component:  - ```vue <template> <b-table @@ -130,9 +129,9 @@ export default { 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. +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). @@ -141,9 +140,10 @@ 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 @@ -159,12 +159,7 @@ format the expanded row content. The slot has access to the row `item` property. ```vue <template> - <b-table - hover - responsive="md" - :items="items" - :fields="fields" - > + <b-table hover responsive="md" :items="items" :fields="fields"> <template #cell(expandRow)="row"> <b-button variant="link" @@ -208,9 +203,9 @@ export default { ## Search -The table is leveraging [BootstrapVue table -filtering](https://bootstrap-vue.org/docs/components/table#filtering) for -search. Add the +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. @@ -240,29 +235,29 @@ if there are no search matches. ```vue <template> <b-container> - <b-row> - <b-col> - <search - @changeSearch="onChangeSearchInput" - @clearSearch="onClearSearchInput" - /> - </b-col> - <b-col> - <table-cell-count - :filtered-items-count="filteredItemsCount" - :total-number-of-cells="items.length" - /> - </b-col> - </b-row> - <b-table - hover - responsive="md" - :items="items" - :fields="fields" - :filter="searchFilter" - :empty-filtered-text="$t('global.table.emptySearchMessage')" - @filtered="onFiltered" - /> + <b-row> + <b-col> + <search + @changeSearch="onChangeSearchInput" + @clearSearch="onClearSearchInput" + /> + </b-col> + <b-col> + <table-cell-count + :filtered-items-count="filteredItemsCount" + :total-number-of-cells="items.length" + /> + </b-col> + </b-row> + <b-table + hover + responsive="md" + :items="items" + :fields="fields" + :filter="searchFilter" + :empty-filtered-text="$t('global.table.emptySearchMessage')" + @filtered="onFiltered" + /> </b-container> </template> <script> @@ -383,6 +378,7 @@ export default { ## Filters 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. @@ -411,12 +407,7 @@ from the TableFilterMixin to show the filtered table data. /> </b-col> </b-row> - <b-table - hover - responsive="md" - :items="filteredItems" - :fields="fields" - /> + <b-table hover responsive="md" :items="filteredItems" :fields="fields" /> </b-container> </template> <script> @@ -454,20 +445,19 @@ export default { </script> ``` - ### 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`. - ## Batch actions 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` @@ -571,10 +561,10 @@ export default { </script> ``` - ## Pagination 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 @@ -607,6 +597,7 @@ To add table pagination: </b-col> </b-row> ``` +  ```vue @@ -667,4 +658,4 @@ export default { } } </script> -```
\ No newline at end of file +``` diff --git a/docs/guide/components/toasts/index.md b/docs/guide/components/toasts/index.md index 3f0c815d..b19643de 100644 --- a/docs/guide/components/toasts/index.md +++ b/docs/guide/components/toasts/index.md @@ -1,12 +1,13 @@ # 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 +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` +`informational`, `warning`, and `error` toast messages. The `BVToastMixin` provides a simple API that generates a toast message that meets the transition guidelines. @@ -67,4 +68,4 @@ methods: { }) } } -```
\ No newline at end of file +``` diff --git a/docs/guide/guidelines/colors.md b/docs/guide/guidelines/colors.md index 3ba91b6a..6ddcfeee 100644 --- a/docs/guide/guidelines/colors.md +++ b/docs/guide/guidelines/colors.md @@ -1,4 +1,5 @@ # Colors + This color palette has been agreed upon by the OpenBMC community and differs from the Bootstrap color patterns. The OpenBMC palette includes custom hex values, along with additional blue, green, red, and yellow color variables used @@ -6,45 +7,45 @@ as accent colors for components. The `.scss` component files use these accent colors to override default styles set by the Bootstrap library. - [Learn more about theme customization](/customization/theme/) -- [Open an issue in the OpenBMC webui-vue - repo](https://github.com/openbmc/webui-vue/issues/new/choose) to request a - change -- [Learn more about Bootstrap - colors](https://getbootstrap.com/docs/4.4/getting-started/theming/#theme-colors) +- [Open an issue in the OpenBMC webui-vue repo](https://github.com/openbmc/webui-vue/issues/new/choose) + to request a change +- [Learn more about Bootstrap colors](https://getbootstrap.com/docs/4.4/getting-started/theming/#theme-colors) ## Grays + <colors-grays/> ## Blues + <colors-blues/> ## Greens + <colors-greens/> ## Reds + <colors-reds/> ## Yellows + <colors-yellows/> ## All Colors + `All Colors` is the term Bootstrap uses to describe the colors that make up the `colors` map. These colors and the Grays color variables define the `theme-colors` map colors. -[Learn more about the Bootstrap color -maps](https://getbootstrap.com/docs/4.0/getting-started/theming/#all-colors). +[Learn more about the Bootstrap color maps](https://getbootstrap.com/docs/4.0/getting-started/theming/#all-colors). <colors-all/> ## Theme Colors + The theme colors are keys in the `theme-colors` map. Bootstrap-Vue has a variant prop that accepts any of the `theme-colors` keys to set the theme of a component. -[Learn more about the Bootstrap theme-colors -maps](https://getbootstrap.com/docs/4.0/getting-started/theming/#theme-colors). +[Learn more about the Bootstrap theme-colors maps](https://getbootstrap.com/docs/4.0/getting-started/theming/#theme-colors). <colors-theme/> - - - diff --git a/docs/guide/guidelines/internationalization.md b/docs/guide/guidelines/internationalization.md index 6ff17d76..7afc4598 100644 --- a/docs/guide/guidelines/internationalization.md +++ b/docs/guide/guidelines/internationalization.md @@ -1,41 +1,48 @@ # Internationalization + The OpenBMC Web UI implements internationalization and separates the language- -specific parts of the interface from the rest of the code, so they can be -easily replaced. The OpenBMC Web UI uses the following library for +specific parts of the interface from the rest of the code, so they can be easily +replaced. The OpenBMC Web UI uses the following library for internationalization: + - [Vue I18n](https://kazupon.github.io/vue-i18n/introduction.html) ## Key naming convention + The OpenBMC Web UI follows the following key naming conventions: - Page specific labels should be nested in an object with a key prefixed `page` -followed by the page title. Formatting in this manner provides a systematic -structure and improves readability of the language file. - - e.g. `pageLocalUserManagement.editUser` + followed by the page title. Formatting in this manner provides a systematic + structure and improves readability of the language file. + - e.g. `pageLocalUserManagement.editUser` - Any 'major' child components should be nested inside page specific objects -(ex. table, modal) - - e.g. `pageEventLogs.table.eventType` + (ex. table, modal) + - e.g. `pageEventLogs.table.eventType` - Avoid any complex linked locale messages. - Alphabetize object keys. This helps in locating the keys. - We use the `$t()` function in markup and `this.$t` in scripts (which Vue I18n -provides to our components) for outputting translation messages. + provides to our components) for outputting translation messages. ## Using the Vue I18n plugin -- A new `src/i18n.js` file is added and it registers Vue I18n as a plugin to -our Vue instance via the `Vue.use()` function. + +- A new `src/i18n.js` file is added and it registers Vue I18n as a plugin to our + Vue instance via the `Vue.use()` function. - The CLI creates a `src/locales/en-US.json` file, which contains our default -translation messages. + translation messages. - The keys are placed in the `src/locales/en-US.json` file and then the `$t()` -function is used to output the translation messages. + function is used to output the translation messages. - After adding or removing calls to `$t` please run this to ensure consistent -English translation (note: using variable expansion in key names is not -handled automatically, you need to manually check them): + English translation (note: using variable expansion in key names is not + handled automatically, you need to manually check them): + ```bash node node_modules/vue-i18n-extract/bin/vue-i18n-extract.js -v 'src/**/*.?(js|vue)' -l 'src/locales/en-US.json' ``` + - If you're working on updating a translation for another language (e.g. -Russian), run this to see the omissions (as well as cruft) and add the -necessary keys automatically: + Russian), run this to see the omissions (as well as cruft) and add the + necessary keys automatically: + ```bash node node_modules/vue-i18n-extract/bin/vue-i18n-extract.js -v 'src/**/*.?(js|vue)' -l 'src/locales/ru-RU.json' -a ``` @@ -51,8 +58,7 @@ node node_modules/vue-i18n-extract/bin/vue-i18n-extract.js -v 'src/**/*.?(js|vue ``` - Vue I18n’s `$tc()` function can help with displaying plurals. -[Learn more about -pluralization.](https://kazupon.github.io/vue-i18n/guide/pluralization.html) + [Learn more about pluralization.](https://kazupon.github.io/vue-i18n/guide/pluralization.html) ```json "modal": { diff --git a/docs/guide/guidelines/motion.md b/docs/guide/guidelines/motion.md index 4e176293..8ec9f5b7 100644 --- a/docs/guide/guidelines/motion.md +++ b/docs/guide/guidelines/motion.md @@ -1,18 +1,20 @@ # Motion + The motion guidelines are based on Carbon Design System guidelines. These guidelines avoid easing curves that are unnatural, distracting, or purely -decorative. [The documentation below is attributed to Carbon's animation -documentation](https://www.carbondesignsystem.com/guidelines/motion/basics/). - +decorative. +[The documentation below is attributed to Carbon's animation documentation](https://www.carbondesignsystem.com/guidelines/motion/basics/). ## Easing ### Productive motion + Productive motion creates a sense of efficiency and responsiveness, while remaining subtle and out of the way. Productive motion is appropriate for moments when the user needs to focus on completing tasks. ### Expressive motion + Expressive motion delivers enthusiastic, vibrant, and highly visible movement. Use expressive motion for significant moments such as opening a new page, clicking the primary action button, or when the movement itself conveys a @@ -20,6 +22,7 @@ meaning. System alerts and the appearance of notification boxes are great cases for expressive motion. ### Easing tokens + ``` $standard-easing--productive: cubic-bezier(0.2, 0, 0.38, 0.9); $standard-easing--expressive: cubic-bezier(0.4, 0.14, 0.3, 1); @@ -30,6 +33,7 @@ $exit-easing--expressive: cubic-bezier(0.4, 0.14, 1, 1); ``` ## Duration + Duration is calculated based on the style and size of the motion. Among the two motion styles, productive motion is significantly faster than expressive motion. Motion’s duration should be dynamic based on the size of the animation; the @@ -37,6 +41,7 @@ larger the change in distance (traveled) or size (scaling) of the element, the longer the animation takes. ### Duration tokens + ``` $duration--fast-01: 70ms; //Micro-interactions such as button and toggle $duration--fast-02: 110ms; //Micro-interactions such as fade @@ -44,4 +49,4 @@ $duration--moderate-01: 150ms; //Micro-interactions, small expansion, short dist $duration--moderate-02: 240ms; //Expansion, system communication, toast $duration--slow-01: 400ms; //Large expansion, important system notifications $duration--slow-02: 700ms; //Background dimming -```
\ No newline at end of file +``` diff --git a/docs/guide/guidelines/typography.md b/docs/guide/guidelines/typography.md index db88d407..c972c3a8 100644 --- a/docs/guide/guidelines/typography.md +++ b/docs/guide/guidelines/typography.md @@ -1 +1 @@ -# Typography
\ No newline at end of file +# Typography diff --git a/docs/guide/quickstart/forms.md b/docs/guide/quickstart/forms.md index 5356eac0..b30c946d 100644 --- a/docs/guide/quickstart/forms.md +++ b/docs/guide/quickstart/forms.md @@ -1,23 +1,24 @@ # Forms -Forms are created using the [bootstrap-vue form -component](https://bootstrap-vue.org/docs/components/form) +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. +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: +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) @@ -25,21 +26,19 @@ commonly used form components: - [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. +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. +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. +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 @@ -53,7 +52,7 @@ A complete form will look like this. label-for="form-input-id" > <b-form-text id="form-input-helper-text"> - {{ $t('pageName.form.helperText') }} + {{ $t("pageName.form.helperText") }} </b-form-text> <b-form-input id="form-input-id" @@ -65,12 +64,12 @@ A complete form will look like this. /> <b-form-invalid-feedback role="alert"> <div v-if="!$v.form.input.required"> - {{ $t('global.form.fieldRequired') }} + {{ $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') }} + {{ $t("global.action.save") }} </b-button> </b-form> </template> diff --git a/docs/guide/quickstart/page-anatomy.md b/docs/guide/quickstart/page-anatomy.md index fd49a8f5..0a347e50 100644 --- a/docs/guide/quickstart/page-anatomy.md +++ b/docs/guide/quickstart/page-anatomy.md @@ -1,15 +1,18 @@ # Page Anatomy + Single-file components (SFC) consist of a `template`, `script` and `style` block. ## Template block + When creating a new page, each template consists of at least 3 components: + - `<b-container>` - `<page-title>` - `<page-section>` -Learn more about the [page title](/guide/components/page-title)and [page -section](/guide/components/page-section) components. +Learn more about the [page title](/guide/components/page-title)and +[page section](/guide/components/page-section) components. ```vue <template> @@ -21,7 +24,9 @@ section](/guide/components/page-section) components. </b-container> </template> ``` + ## Scripts block + In the scripts section, be sure to import the `PageTitle` and `PageSection` components and declare them in the `components` property. @@ -30,45 +35,49 @@ it is already registered globally. ```vue <script> -import PageTitle from '@/components/Global/PageTitle'; -import PageSection from '@/components/Global/PageSection'; +import PageTitle from "@/components/Global/PageTitle"; +import PageSection from "@/components/Global/PageSection"; export default { - name: 'PageName', - components: { PageTitle, PageSection } + name: "PageName", + components: { PageTitle, PageSection }, }; </script> ``` ## Style block + Add the `scoped` attribute to the style block to keep the styles isolated to the SFC. While the `scoped` attribute is optional, it is preferred and global changes should be done in global style sheets. + ```vue -<style lang="scss" scoped> </style> +<style lang="scss" scoped></style> ``` ## Complete single-file component (SFC) + The final SFC will look like this. + ```vue <template> <b-container fluid="xl"> - <page-title :description="$t('pageName.pageDescription')"/> + <page-title :description="$t('pageName.pageDescription')" /> <page-section :section-title="$t('pageName.sectionTitle')"> // Page content goes here </page-section> </b-container> </template> <script> -import PageTitle from '@/components/Global/PageTitle'; -import PageSection from '@/components/Global/PageSection'; +import PageTitle from "@/components/Global/PageTitle"; +import PageSection from "@/components/Global/PageSection"; export default { - name: 'PageName', - components: { PageTitle, PageSection } + name: "PageName", + components: { PageTitle, PageSection }, }; </script> <style lang="scss" scoped> - .example-class { - /* Styles go here */ - } - </style> -```
\ No newline at end of file +.example-class { + /* Styles go here */ +} +</style> +``` diff --git a/docs/guide/quickstart/store-anatomy.md b/docs/guide/quickstart/store-anatomy.md index 3ad5694f..a01ddb64 100644 --- a/docs/guide/quickstart/store-anatomy.md +++ b/docs/guide/quickstart/store-anatomy.md @@ -2,8 +2,8 @@ ## Store -A "store" is a container that holds the application's state. [Learn more about -Vuex.](https://vuex.vuejs.org/) +A "store" is a container that holds the application's state. +[Learn more about Vuex.](https://vuex.vuejs.org/) ```sh # Store structure @@ -26,26 +26,26 @@ bloated. Each module contains its own state, mutations, actions, and getters. #### Module Anatomy -- **State:** You cannot directly mutate the store's state. [Learn more about - state.](https://vuex.vuejs.org/guide/state.html) +- **State:** You cannot directly mutate the store's state. + [Learn more about state.](https://vuex.vuejs.org/guide/state.html) - **Getters:** Getters are used to compute derived state based on store state. [Learn more about getters.](https://vuex.vuejs.org/guide/getters.html) - **Mutations:** The only way to mutate the state is by committing mutations, - which are synchronous transactions. [Learn more about - mutations.](https://vuex.vuejs.org/guide/mutations.html) + which are synchronous transactions. + [Learn more about mutations.](https://vuex.vuejs.org/guide/mutations.html) - **Actions:** Asynchronous logic should be encapsulated in, and can be composed - with actions. [Learn more about - actions.](https://vuex.vuejs.org/guide/actions.html) + with actions. + [Learn more about actions.](https://vuex.vuejs.org/guide/actions.html) Import new store modules in `src/store/index.js`. ```js // `src/store/index.js` -import Vue from 'vue'; -import Vuex from 'vuex'; +import Vue from "vue"; +import Vuex from "vuex"; -import FeatureNameStore from './modules/FeatureNameStore'; +import FeatureNameStore from "./modules/FeatureNameStore"; Vue.use(Vuex); @@ -64,42 +64,42 @@ export default new Vuex.Store({ A store module will look like this. ```js -import api from '@/store/api'; -import i18n from '@/i18n'; +import api from "@/store/api"; +import i18n from "@/i18n"; const FeatureNameStore = { // getters, actions, and mutations will be namespaced // based on the path the module is registered at namespaced: true, state: { - exampleValue: 'Off', + exampleValue: "Off", }, getters: { // namespace -> getters['featureNameStore/getExampleValue'] - getExampleValue: state => state.exampleValue, + getExampleValue: (state) => state.exampleValue, }, mutations: { // namespace -> commit('featureNameStore/setExampleValue) - setExampleValue: state => state.exampleValue, + setExampleValue: (state) => state.exampleValue, }, actions: { // namespace -> dispatch('featureNameStore/getExampleValue') async getExampleValue({ commit }) { return await api - .get('/redfish/v1/../..') - .then(response => { - commit('setExampleValue', response.data.Value); + .get("/redfish/v1/../..") + .then((response) => { + commit("setExampleValue", response.data.Value); }) - .catch(error => console.log(error)); + .catch((error) => console.log(error)); }, // namespace -> ('featureNameStore/saveExampleValue', payload) async saveExampleValue({ commit }, payload) { return await api - .patch('/redfish/v1/../..', { Value: payload }) + .patch("/redfish/v1/../..", { Value: payload }) .then(() => { - commit('setExampleValue', payload); + commit("setExampleValue", payload); }) - .catch(error => { + .catch((error) => { console.log(error); }); }, diff --git a/docs/guide/readme.md b/docs/guide/readme.md index 0a0db1d7..19c481c2 100644 --- a/docs/guide/readme.md +++ b/docs/guide/readme.md @@ -12,9 +12,11 @@ Web UI. This guide exists to serve the following goals: 1. Act as a collection of community agreed-upon standards ## Coding Standards + Having an understanding of semantic HTML, CSS, and JavaScript is the critical knowledge required to contribute to this project. The frameworks and libraries used to build this UI include: + - [Vue](https://vuejs.org/) - [Vuex](https://vuex.vuejs.org/) - [Vue Router](https://router.vuejs.org/) @@ -30,12 +32,13 @@ You will find more information about the standards and best practices in the [Coding Standards section of this guide](/guide/coding-standards/). ## Guidelines + The [guidelines section](/guide/guidelines/colors.md) contains the OpenBMC community agreed-upon decisions on color, motion, and typography within the application. How to theme the application to meet company brand guidelines is documented in [Customization](/customization/). ## Components + The [components section](/guide/components/) is a guide to using both custom Vue components and components from the Bootstrap-Vue library. - diff --git a/docs/guide/unit-testing/readme.md b/docs/guide/unit-testing/readme.md index b8ca4533..76183768 100644 --- a/docs/guide/unit-testing/readme.md +++ b/docs/guide/unit-testing/readme.md @@ -1,19 +1,20 @@ # Unit Testing - The goal of a unit test is to improve code quality and assure future - development or refactoring does not result in broken builds and functionality. - Tests that require consistent updating when refactoring code are likely tightly - coupled to the internals of the component. - - > Writing unit tests is a constant struggle between writing enough tests and - > not writing too many. I call this the unit testing Goldilocks rule—not too - > many, not too few, but just enough. Thousands of tests for a small - > application can be as damaging to development time as no tests. - > - > -- <cite>Ed Yerburgh, Testing Vue Applications (New York: Manning - > Publications, 2019)</cite> +The goal of a unit test is to improve code quality and assure future development +or refactoring does not result in broken builds and functionality. Tests that +require consistent updating when refactoring code are likely tightly coupled to +the internals of the component. + +> Writing unit tests is a constant struggle between writing enough tests and not +> writing too many. I call this the unit testing Goldilocks rule—not too many, +> not too few, but just enough. Thousands of tests for a small application can +> be as damaging to development time as no tests. +> +> -- <cite>Ed Yerburgh, Testing Vue Applications (New York: Manning +> Publications, 2019)</cite> ## Test Libraries + The OpenBMC Web UI unit test framework uses the Jest test runner and relies on the following libraries: @@ -21,18 +22,20 @@ the following libraries: - @vue/test-utils ## Test specification location and naming conventions + - Create the test files in the /tests/unit directory - The naming convention is to replicate the folder and component name ### Examples + - The AppHeader.vue single-file component's (SFC) spec file is named `AppHeader.spec.js` - Create a global component like `PageSection.vue` in the `/tests/global` directory with the name `PageSection.spec.js` -- Create a mixin like BVToastMixin in the `/tests/mixins` directory with the +- Create a mixin like BVToastMixin in the `/tests/mixins` directory with the name `BVToastMixin.spec.js` Running Tests - ## Running Tests +## Running Tests The `test:unit` script will run all the test suites. Until the integration of the test script with the continuous integration tool is complete, it needs to be @@ -40,8 +43,8 @@ run manually before pushing up code for review. If you are working on fixing a test that is failing, follow the guidelines for debugging a failed tests or fixing failed snapshot tests. - ### Debugging a failed test + The `test:unit:debugger` script will help to debug failing tests using the Chrome Developer Tools. To debug a test: @@ -50,19 +53,21 @@ Chrome Developer Tools. To debug a test: 1. Open the Chrome browser and go to `chrome://inspect` ### Fixing failed snapshot tests + The `test:update` script will update snapshot tests. If the UI has changed and the snapshot tests are failing, after manually verifying the UI changes, run the update script to update the snapshots. Running `test:update` can be dangerous, as it will update all snapshot tests. It is critical to verify all snapshot tests before running the update script. -The easiest way is to run the unit test in watch mode, `npm run test:unit -- ---watch` and verify each snapshot. +The easiest way is to run the unit test in watch mode, +`npm run test:unit -- --watch` and verify each snapshot. ## Guidelines + - Avoid coupling test code to source code when testing functionality - - If test cases fail during refactoring, the test case may be tightly - coupled with the application structure. + - If test cases fail during refactoring, the test case may be tightly coupled + with the application structure. - A test should not break if the functionality it tests has not changed - To maintain test readability, only pass in the data needed for the test to work in your mock object @@ -76,13 +81,15 @@ The easiest way is to run the unit test in watch mode, `npm run test:unit -- ## Components ### What to test + 1. Test the function's inputs and outputs - - Test only dynamically generated output - - Test only output that is part of the component contract + - Test only dynamically generated output + - Test only output that is part of the component contract 1. Test any side-effects 1. Test correct rendering using a snapshot test ### What not to test + 1. Don't test third-party functionality 1. Don't test the internals of your components or that specific functions are called. This can lead to unnecessary refactoring. @@ -91,6 +98,7 @@ The easiest way is to run the unit test in watch mode, `npm run test:unit -- 1. Static components do not need unit tests, use snapshot testing ### Strategy + 1. Define a component contract that is based upon the component API 1. Create smaller functions with a specific purpose to make testing easier 1. Test the component API by writing tests first and then writing code to fix @@ -99,6 +107,7 @@ The easiest way is to run the unit test in watch mode, `npm run test:unit -- visual testing ### Snapshot Testing + A snapshot test is a comparison of the code from two different points in time. When the view is rendering as expected, a snapshot is taken and when the test suite is run, this snapshot is compared to the current code to make sure nothing @@ -114,60 +123,68 @@ presentational layer is complete and validated. There are two testing strategies for testing a Vuex store, which include testing store parts separately or testing a running store instance. Each strategy has its pros and cons. Given the size of the store and the number of developers that -could potentially contribute to the project, the suggested strategy is to `test -store parts separately`. +could potentially contribute to the project, the suggested strategy is to +`test store parts separately`. ### Testing Store Parts Separately + Testing the parts separately is easy since each of the parts is a JavaScript function. Store parts to test include `actions`, `getters`, and `mutations`. #### Actions + Since HTTP calls should never be used in a test, actions require extreme mocking. Mocking tests rely on assumptions and can lead to faulty tests. #### Getters + Getters are JavaScript functions that return an output. These are basic functions that may not require testing unless there is getter logic. Any logic in a getter should be tested. #### Mutations + Mutations are JavaScript functions that mutate the store state. These are basic functions that may not require testing unless there is mutation logic. Any logic in a mutation should be tested. #### Pros + - Easier to debug - Smaller tests #### Cons + - Requires extreme mocking when testing actions - Tightly coupled with implementation details - More maintenance required when refactoring ### Testing Store Instance + - Uses mutations and actions as inputs - State is the output - Requires the use of `localVue` when creating the store to avoid leaky tests #### Pros + - Avoids mocking and brittle tests - Refactoring does not break test unless contract changes #### Cons + - Debugging is more difficult ## Vue Router + - Our current structure does not warrant testing the vue router - If there is logic used for creating `RouteLink` items, we should unit test that functionality, which requires stubbing - When testing a vue router, it is important to use localVue - [Vuex Testing](https://vuex.vuejs.org/guide/testing.html) ## Resources + - [Vue Test Utils](https://vue-test-utils.vuejs.org/) -- [Knowing What To Test — Vue Component Unit - Testing](https://vuejsdevelopers.com/2019/08/26/vue-what-to-unit-test-components/) -- [How to unit test a vuex - Store](https://www.dev-tips-and-tricks.com/how-to-unit-test-a-vuex-store)
\ No newline at end of file +- [Knowing What To Test — Vue Component Unit Testing](https://vuejsdevelopers.com/2019/08/26/vue-what-to-unit-test-components/) +- [How to unit test a vuex Store](https://www.dev-tips-and-tricks.com/how-to-unit-test-a-vuex-store) diff --git a/docs/readme.md b/docs/readme.md index 0630f0d0..0f0f7f5d 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -4,4 +4,4 @@ heroImage: openbmc-logo.svg heroText: Style Guide and Coding Conventions actionText: Getting Started actionLink: /guide/ ----
\ No newline at end of file +--- |