diff options
| author | GitHub Action <action@github.com> | 2022-03-25 21:22:29 +0300 |
|---|---|---|
| committer | GitHub Action <action@github.com> | 2022-03-25 21:22:29 +0300 |
| commit | 6d8f40c4ac31386460f33d0b4522ea8357e03894 (patch) | |
| tree | dead2423a6c240256a28d4eb9c55cac2b45d71d0 /customization/build.html | |
| download | webui-vue-gh-pages.tar.xz | |
deploygh-pages
Diffstat (limited to 'customization/build.html')
| -rw-r--r-- | customization/build.html | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/customization/build.html b/customization/build.html new file mode 100644 index 000000000..b3c714cf2 --- /dev/null +++ b/customization/build.html @@ -0,0 +1,83 @@ +<!DOCTYPE html> +<html lang="en-US"> + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width,initial-scale=1"> + <title>Build Customization | OpenBMC Web UI Style Guide</title> + <meta name="generator" content="VuePress 1.8.2"> + + <meta name="description" content="Guidance on code style and development for the OpenBMC browser-based UI"> + + <link rel="preload" href="/webui-vue/assets/css/0.styles.ee48119c.css" as="style"><link rel="preload" href="/webui-vue/assets/js/app.6e5ae7e9.js" as="script"><link rel="preload" href="/webui-vue/assets/js/2.3066748c.js" as="script"><link rel="preload" href="/webui-vue/assets/js/21.f51dd518.js" as="script"><link rel="prefetch" href="/webui-vue/assets/js/10.eff1bc3e.js"><link rel="prefetch" href="/webui-vue/assets/js/11.f760a167.js"><link rel="prefetch" href="/webui-vue/assets/js/12.05e32ea2.js"><link rel="prefetch" href="/webui-vue/assets/js/13.3011b8ba.js"><link rel="prefetch" href="/webui-vue/assets/js/14.366e135a.js"><link rel="prefetch" href="/webui-vue/assets/js/15.9a576a5a.js"><link rel="prefetch" href="/webui-vue/assets/js/16.8d8a2baa.js"><link rel="prefetch" href="/webui-vue/assets/js/17.067a94f4.js"><link rel="prefetch" href="/webui-vue/assets/js/18.88267105.js"><link rel="prefetch" href="/webui-vue/assets/js/19.781066f3.js"><link rel="prefetch" href="/webui-vue/assets/js/20.afaf92e0.js"><link rel="prefetch" href="/webui-vue/assets/js/22.22ba3b96.js"><link rel="prefetch" href="/webui-vue/assets/js/23.42b49486.js"><link rel="prefetch" href="/webui-vue/assets/js/24.7c316dcb.js"><link rel="prefetch" href="/webui-vue/assets/js/25.79d3357c.js"><link rel="prefetch" href="/webui-vue/assets/js/26.c82c48a9.js"><link rel="prefetch" href="/webui-vue/assets/js/27.f4d5e099.js"><link rel="prefetch" href="/webui-vue/assets/js/28.e8d46e0f.js"><link rel="prefetch" href="/webui-vue/assets/js/29.a85a251f.js"><link rel="prefetch" href="/webui-vue/assets/js/3.4aa24478.js"><link rel="prefetch" href="/webui-vue/assets/js/30.994c9683.js"><link rel="prefetch" href="/webui-vue/assets/js/31.06af27be.js"><link rel="prefetch" href="/webui-vue/assets/js/32.57a17f1c.js"><link rel="prefetch" href="/webui-vue/assets/js/33.b9e5db10.js"><link rel="prefetch" href="/webui-vue/assets/js/34.0e496acd.js"><link rel="prefetch" href="/webui-vue/assets/js/35.49b0ff49.js"><link rel="prefetch" href="/webui-vue/assets/js/36.dbed5155.js"><link rel="prefetch" href="/webui-vue/assets/js/37.c48db488.js"><link rel="prefetch" href="/webui-vue/assets/js/38.2cecf29e.js"><link rel="prefetch" href="/webui-vue/assets/js/4.e088be67.js"><link rel="prefetch" href="/webui-vue/assets/js/5.666cf43b.js"><link rel="prefetch" href="/webui-vue/assets/js/6.c4bd7641.js"><link rel="prefetch" href="/webui-vue/assets/js/7.2afc0a47.js"><link rel="prefetch" href="/webui-vue/assets/js/8.50aab72d.js"><link rel="prefetch" href="/webui-vue/assets/js/9.9f3d8ba6.js"> + <link rel="stylesheet" href="/webui-vue/assets/css/0.styles.ee48119c.css"> + </head> + <body> + <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/webui-vue/" class="home-link router-link-active"><!----> <span class="site-name">OpenBMC Web UI Style Guide</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/webui-vue/guide/" class="nav-link"> + Guide +</a></div><div class="nav-item"><a href="/webui-vue/customization/" class="nav-link router-link-active"> + Customization +</a></div><div class="nav-item"><a href="https://github.com/openbmc/webui-vue" target="_blank" rel="noopener noreferrer" class="nav-link external"> + Github + <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <!----></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/webui-vue/guide/" class="nav-link"> + Guide +</a></div><div class="nav-item"><a href="/webui-vue/customization/" class="nav-link router-link-active"> + Customization +</a></div><div class="nav-item"><a href="https://github.com/openbmc/webui-vue" target="_blank" rel="noopener noreferrer" class="nav-link external"> + Github + <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <!----></nav> <ul class="sidebar-links"><li><a href="/webui-vue/customization/" aria-current="page" class="sidebar-link">Presentation Layer Architecture</a></li><li><a href="/webui-vue/customization/theme.html" class="sidebar-link">Theme customization</a></li><li><a href="/webui-vue/customization/build.html" aria-current="page" class="active sidebar-link">Build Customization</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/webui-vue/customization/build.html#setup" class="sidebar-link">Setup</a></li><li class="sidebar-sub-header"><a href="/webui-vue/customization/build.html#store" class="sidebar-link">Store</a></li><li class="sidebar-sub-header"><a href="/webui-vue/customization/build.html#router" class="sidebar-link">Router</a></li><li class="sidebar-sub-header"><a href="/webui-vue/customization/build.html#app-navigation" class="sidebar-link">App navigation</a></li><li class="sidebar-sub-header"><a href="/webui-vue/customization/build.html#theming" class="sidebar-link">Theming</a></li><li class="sidebar-sub-header"><a href="/webui-vue/customization/build.html#local-development" class="sidebar-link">Local development</a></li><li class="sidebar-sub-header"><a href="/webui-vue/customization/build.html#production-build" class="sidebar-link">Production build</a></li></ul></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="build-customization"><a href="#build-customization" class="header-anchor">#</a> Build Customization</h1> <p>This document provides instructions for how to add environment specific +modifications to the Web UI.</p> <ul><li><a href="#setup">Setup</a></li> <li><a href="#store">Store</a></li> <li><a href="#router">Router</a></li> <li><a href="#app-navigation">App Navigation</a></li> <li><a href="#theming">Theming</a></li> <li><a href="#local-development">Local development</a></li> <li><a href="#production-build">Production build</a></li></ul> <h2 id="setup"><a href="#setup" class="header-anchor">#</a> Setup</h2> <ol><li>Create a <code>.env.<ENV_NAME></code> file in the project root</li> <li>Add <code>NODE_ENV=production</code> key value pair in the file</li> <li>Add <code>VUE_APP_ENV_NAME</code> key with the value set to the new environment name</li></ol> <p>Example <code>.env.ibm</code>:</p> <div class="language- extra-class"><pre class="language-text"><code>NODE_ENV=production +VUE_APP_ENV_NAME=ibm +</code></pre></div><h2 id="store"><a href="#store" class="header-anchor">#</a> Store</h2> <div class="custom-block tip"><p class="custom-block-title">TIP</p> <p><a href="https://vuex.vuejs.org/guide/modules.html" target="_blank" rel="noopener noreferrer">Vuex store modules<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> contain the +application's API calls.</p></div> <ol><li>If making customizations to the default store, add <code>CUSTOM_STORE=true</code> key +value pair to the new .env file.</li> <li>Create a <code><ENV_NAME>.js</code> file in <code>src/env/store</code><div class="custom-block danger"><p class="custom-block-title">WARNING</p> <p>The filename needs to match the <code>VUE_APP_ENV_NAME</code> value defined in the +.env file. The store import in <code>src/main.js</code> will resolve to this new +file.</p></div></li> <li>Import the base store</li> <li>Import environment specific store modules</li> <li>Use the <a href="https://vuex.vuejs.org/api/#registermodule" target="_blank" rel="noopener noreferrer">Vuex<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> <code>registerModule</code> +and <code>unregisterModule</code> instance methods to add/remove store modules</li> <li>Add default export</li></ol> <p>Example <code>src/env/store/ibm.js</code>:</p> <div class="language- extra-class"><pre class="language-text"><code>import store from '@/store; //@ aliases to src directory +import HmcStore from './Hmc/HmcStore'; + +store.registerModule('hmc', HmcStore); + +export default store; +</code></pre></div><h2 id="router"><a href="#router" class="header-anchor">#</a> Router</h2> <div class="custom-block tip"><p class="custom-block-title">TIP</p> <p><a href="https://router.vuejs.org/guide/" target="_blank" rel="noopener noreferrer">Vue Router<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> determines which pages are +accessible in the UI.</p></div> <ol><li>If making customizations to the default router, add <code>CUSTOM_ROUTER=true</code> key +value pair to the new .env file.</li> <li>Create a <code><ENV_NAME>.js</code> file in <code>src/env/router</code><div class="custom-block danger"><p class="custom-block-title">WARNING</p> <p>The filename needs to match the <code>VUE_APP_ENV_NAME</code> value defined in the +.env file. The routes import in <code>src/router/index.js</code> will resolve to this +new file.</p></div></li> <li>Define new <a href="https://router.vuejs.org/api/#routes" target="_blank" rel="noopener noreferrer">routes<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>.<div class="custom-block tip"><p class="custom-block-title">TIP</p> <p>Use static imports (over lazy-loading routes) to avoid creating separate +JS chunks. Static imports also helps to keep the total build size down.</p></div></li> <li>Add default export</li></ol> <h2 id="app-navigation"><a href="#app-navigation" class="header-anchor">#</a> App navigation</h2> <p>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.</p> <ol><li>If making customizations to the app navigation, add <code>CUSTOM_APP_NAV=true</code> key +value pair to the new .env file.</li> <li>Create a <code><ENV_NAME>.js</code> file in <code>src/env/components/AppNavigation</code><div class="custom-block danger"><p class="custom-block-title">WARNING</p> <p>The filename needs to match the <code>VUE_APP_ENV_NAME</code> value defined in the +.env file. The AppNavigationMixin import in +<code>src/components/AppNavigation/AppNavigation.vue</code> will resolve to this new +file.</p></div></li> <li>Your custom mixin should follow a very similar structure to the default +AppNavigationMixin.js file. It should include a data property named +<code>navigationItems</code> that should be an array of of navigation objects. Each +navigation object should have an <code>id</code> and <code>label</code> property defined. +Optionally it can include <code>icon</code>, <code>route</code>, or <code>children</code> properties.</li> <li>Add default export</li></ol> <h2 id="theming"><a href="#theming" class="header-anchor">#</a> Theming</h2> <div class="custom-block tip"><p class="custom-block-title">TIP</p> <p><a href="https://getbootstrap.com/docs/4.5/getting-started/theming/" target="_blank" rel="noopener noreferrer">Bootstrap theming<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> +allows for easy visual customizations.</p></div> <ol><li>If making customizations to the default styles, add <code>CUSTOM_STYLES=true</code> key +value pair to the new .env file.</li> <li>Create a <code>_<ENV_NAME>.scss</code> partial in <code>src/env/assets/styles</code><div class="custom-block danger"><p class="custom-block-title">WARNING</p> <p>The filename needs to match the <code>VUE_APP_ENV_NAME</code> value defined in the +.env file. The webpack sass loader will attempt to import a file with this +name.</p></div></li> <li>Add style customizations. Refer to <a href="https://getbootstrap.com/docs/4.5/getting-started/theming/" target="_blank" rel="noopener noreferrer">bootstrap documentation<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> +for details about <a href="https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults" target="_blank" rel="noopener noreferrer">color +overrides<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> +and <a href="https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options" target="_blank" rel="noopener noreferrer">other customizable +options<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>.</li></ol> <p>Example for adding custom colors</p> <p><code>src/env/assets/styles/_ibm.scss</code></p> <div class="language- extra-class"><pre class="language-text"><code>// Custom theme colors + +$primary: rebeccapurple; +$success: lime; +</code></pre></div><h2 id="local-development"><a href="#local-development" class="header-anchor">#</a> Local development</h2> <ol><li>Add the same <code>VUE_APP_ENV_NAME</code> key value pair to your +<code>env.development.local</code> file.</li> <li>Use serve script<div class="language- extra-class"><pre class="language-text"><code>npm run serve +</code></pre></div></li></ol> <h2 id="production-build"><a href="#production-build" class="header-anchor">#</a> Production build</h2> <p>Run npm build script with vue-cli <code>--mode</code> <a href="https://cli.vuejs.org/guide/mode-and-env.html#modes" target="_blank" rel="noopener noreferrer">option +flag<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>. This requires +<a href="#setup">corresponding .env file to exist</a>.</p> <div class="language- extra-class"><pre class="language-text"><code>npm run build -- --mode ibm +</code></pre></div><p><strong>OR</strong></p> <p>pass env variable directly to script</p> <div class="language- extra-class"><pre class="language-text"><code>VUE_APP_ENV_NAME=ibm npm run build +</code></pre></div></div> <footer class="page-edit"><!----> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev"> + ← + <a href="/webui-vue/customization/theme.html" class="prev"> + Theme customization + </a></span> <!----></p></div> </main></div><div class="global-ui"></div></div> + <script src="/webui-vue/assets/js/app.6e5ae7e9.js" defer></script><script src="/webui-vue/assets/js/2.3066748c.js" defer></script><script src="/webui-vue/assets/js/21.f51dd518.js" defer></script> + </body> +</html> |