OpenBMC Web UI Style Guide

# Build Customization

This document provides instructions for how to add environment specific modifications to the Web UI.

# Setup

  1. Create a .env.<ENV_NAME> file in the project root
  2. Add NODE_ENV=production key value pair in the file
  3. Add VUE_APP_ENV_NAME key with the value set to the new environment name

Example .env.ibm:

NODE_ENV=production
VUE_APP_ENV_NAME=ibm

# Store

TIP

Vuex store modules (opens new window) 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

    WARNING

    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 (opens new window) registerModule and unregisterModule instance methods to add/remove store modules
  6. Add default export

Example src/env/store/ibm.js:

import store from '@/store; //@ aliases to src directory
import HmcStore from './Hmc/HmcStore';

store.registerModule('hmc', HmcStore);

export default store;

# Router

TIP

Vue Router (opens new window) 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

    WARNING

    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 (opens new window).

    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

The Vue Router definition is closely tied to the app navigation but should be configured separately. The Vue Router is responsible for defining the application routes which is not always the same as what is visible in the app navigation. This configuration will make customizations to the rendered markup 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

    WARNING

    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.

  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 navigation object should have an id and label property defined. Optionally it can include icon, route, or children properties.
  4. Add default export

# Theming

TIP

Bootstrap theming (opens new window) 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

    WARNING

    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 (opens new window) for details about color overrides (opens new window) and other customizable options (opens new window).

Example for adding custom colors

src/env/assets/styles/_ibm.scss

// Custom theme colors

$primary: rebeccapurple;
$success: lime;

# Local development

  1. Add the same VUE_APP_ENV_NAME key value pair to your env.development.local file.
  2. Use serve script
    npm run serve

# Production build

Run npm build script with vue-cli --mode option flag (opens new window). This requires corresponding .env file to exist.

npm run build -- --mode ibm

OR

pass env variable directly to script

VUE_APP_ENV_NAME=ibm npm run build

←