From e2707ef0ca20b669aca7ac06274591bd795719a9 Mon Sep 17 00:00:00 2001
From: Dixsie Wolmers <dixsie@ibm.com>
Date: Sun, 15 Nov 2020 21:45:03 -0600
Subject: Add page components documentation

Components include: b-container, page-title, and page-section.

Signed-off-by: Dixsie Wolmers <dixsie@ibm.com>
Change-Id: I5933767d44504dbfb87c2772d140de4d0607d4ab
---
 docs/.vuepress/config.js              |  1 +
 docs/guide/components/page-section.md |  1 -
 docs/guide/components/page-title.md   |  1 -
 docs/guide/components/page.md         | 67 +++++++++++++++++++++++++++++++++++
 docs/guide/quickstart/page-anatomy.md | 18 +++-------
 5 files changed, 73 insertions(+), 15 deletions(-)
 delete mode 100644 docs/guide/components/page-section.md
 delete mode 100644 docs/guide/components/page-title.md
 create mode 100644 docs/guide/components/page.md

(limited to 'docs')

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 7f286200..9f052773 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -49,6 +49,7 @@ module.exports = {
             "/guide/components/",
             "/guide/components/alert",
             "/guide/components/buttons/",
+            "/guide/components/page",
             "/guide/components/status-icon/",
             "/guide/components/table/",
             "/guide/components/toast",
diff --git a/docs/guide/components/page-section.md b/docs/guide/components/page-section.md
deleted file mode 100644
index 9c8f1b2d..00000000
--- a/docs/guide/components/page-section.md
+++ /dev/null
@@ -1 +0,0 @@
-# Page Section
\ No newline at end of file
diff --git a/docs/guide/components/page-title.md b/docs/guide/components/page-title.md
deleted file mode 100644
index ebc2fc57..00000000
--- a/docs/guide/components/page-title.md
+++ /dev/null
@@ -1 +0,0 @@
-# Page Title
\ No newline at end of file
diff --git a/docs/guide/components/page.md b/docs/guide/components/page.md
new file mode 100644
index 00000000..83106e37
--- /dev/null
+++ b/docs/guide/components/page.md
@@ -0,0 +1,67 @@
+# Page
+
+The essential building blocks of each page, or single-file component, consist of:
+- `<b-container>`
+- `<page-title>`
+- `<page-section>`
+
+```vue
+<template>
+  <b-container fluid="xl">
+    <page-title />
+    <page-section :section-title="$t('pageName.sectionTitle')">
+      // Page content goes here
+    </page-section>
+  </b-container>
+</template>
+```
+
+## Page container
+Use the `fluid="xl"` prop on the `<b-container>` component to render a container that is always 100% width on larger screen sizes. [Learn more about BootstrapVue containers](https://bootstrap-vue.org/docs/components/layout#responsive-fluid-containers).
+
+```vue
+<template>
+  <b-container fluid="xl">
+  </b-container>
+</template>
+```
+
+
+Within the page container, include the [page title](#/page-title) and [page section](#page-section) components.
+
+## 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`.
+
+```js
+// src/router/routes.js
+  {
+    path: '',
+    name: 'login',
+    component: Login,
+    meta: {
+      title: i18n.t('appPageTitle.login'),
+    },
+  },
+```
+
+Optional page descriptions can be included by using the description prop `:description` prop and passing in the i18n localized text string. Translations are found in the `src/locales` folder.
+
+``` vue
+// Example: `src/views/AccessControl/Ldap/Ldap.vue`
+  <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).
+
+## Page section
+
+The `<page-section>` component will render semantic HTML. By adding a `:section-title` prop to the `<page-section>` component, the localized text string will be rendered in an `h2` header element.
+
+``` 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).
+
+ [Visit the quick start guide](/guide/quickstart/page-anatomy) to learn how to build a single-file component using this page anatomy.
\ No newline at end of file
diff --git a/docs/guide/quickstart/page-anatomy.md b/docs/guide/quickstart/page-anatomy.md
index c0419acd..ed17c04e 100644
--- a/docs/guide/quickstart/page-anatomy.md
+++ b/docs/guide/quickstart/page-anatomy.md
@@ -7,31 +7,23 @@ When creating a new page, each template consists of at least 3 components:
 - `<page-title>`
 - `<page-section>`
 
-### Page container
-Use the `fluid="xl"` prop on the `<b-container>` component to render a container that is always 100% width on larger screen sizes. Importing `BContainer` in the [scripts block](#scripts-block) is not required as it is already registered globally.
+Learn more about the [page container, page title and page section](/guide/components/page) components.
 
-[Learn more about BootstrapVue containers](https://bootstrap-vue.org/docs/components/layout#responsive-fluid-containers).
-
-### Page title component
-By including the `<page-title>` component in the template, it will automatically render the page title that corresponds with the title property set in the route record's meta field.
-
-Optional page descriptions can be included by using the description prop `:description` prop and passing in the i18n localized text string.
-
-### Page section component
-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
 <template>
   <b-container fluid="xl">
-    <page-title :description="$t('pageName.pageDescription')"/>
+    <page-title />
     <page-section :section-title="$t('pageName.sectionTitle')">
       // Page content goes here
     </page-section>
   </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.
+
+Importing `BContainer` in the [scripts block](#scripts-block) is not required as it is already registered globally.
+
 ```vue
 <script>
 import PageTitle from '@/components/Global/PageTitle';
-- 
cgit v1.2.3