appData.appBar for app-bar items

Author: ShukantPal

packages/webdoc-default-template/helper/crawl/crawl-tutorials.js

@@ -28,7 +28,12 @@ function crawlTutorials(docTree /*: RootDoc */)/*: ?ExplorerTarget */ {
 
   // No need for single top-level item
   if (Object.keys(rootTarget.children).length === 1) {
-    rootTarget = { children: rootTarget.children[Object.keys(rootTarget.children)[0]].children };
+    const implicitRootTarget = rootTarget.children[Object.keys(rootTarget.children)[0]];
+
+    rootTarget = {
+      page: implicitRootTarget.page,
+      children: implicitRootTarget.children,
+    };
   }
 
   return rootTarget;
@@ -49,7 +54,7 @@ function buildTutorialTargets(
   if (tutorial.members.length > 0) {
     if (tutorialTarget.page) {
       tutorialTarget.children.overview = {
-        title: '(overview)',
+        title: "(overview)",
         page: tutorialTarget.page,
       };
     }

packages/webdoc-default-template/publish.js

@@ -27,6 +27,16 @@ import type {
 } from "@webdoc/types";
 
 import type {CrawlData} from './crawl';
+
+type AppBarItem = {
+  name: string;
+  uri: string;
+};
+
+type AppBarData = {
+  current: string;
+  items: { [id: string]: AppBarItem };
+};
 */
 
 Object.assign(linker.standaloneDocTypes, [
@@ -62,13 +72,31 @@ exports.publish = async function publish(options /*: PublishOptions */) {
   fse.ensureDir(outDir);
 
   const crawlData = crawl(docTree, index);
+  const appBarItems = {
+    "reference": {
+      name: "API Reference",
+      uri: index,
+    },
+    ...(crawlData.tutorials && {
+      "tutorials": {
+        name: "Tutorials",
+        uri: crawlData.tutorials.page ||
+          crawlData.tutorials.children[Object.keys(crawlData.tutorials.children)[0]].page,
+      },
+    }),
+  };
   const renderer = new TemplateRenderer(path.join(__dirname, "tmpl"), null, docTree)
     .setLayoutTemplate("layout.tmpl")
     .installPlugin("linker", linker)
     .installPlugin("generateIndex", indexSorterPlugin)
     .installPlugin("signature", signaturePlugin)
     .installPlugin("categoryFilter", categoryFilterPlugin)
-    .installPlugin("relations", RelationsPlugin);
+    .installPlugin("relations", RelationsPlugin)
+    .setGlobalTemplateData({
+      appBar: {
+        items: appBarItems,
+      },
+    });
 
   const pipeline = new TemplatePipeline(renderer).pipe(new TemplateTagsResolver());
 
@@ -190,6 +218,7 @@ async function outReadme(
   }
 
   pipeline.render("pages/main-page.tmpl", {
+    appBar: {current: "reference"},
     document: null,
     readme,
     title: "Documentation",
@@ -212,6 +241,7 @@ function outIndexes(
     const url = linker.processInternalURI(indexList.url, {outputRelative: true});
 
     pipeline.render("pages/api-index.tmpl", {
+      appBar: {current: "reference"},
       documentList: indexList,
       title,
       env: config,
@@ -262,6 +292,7 @@ function outReference(
       );
     } else {
       pipeline.render("document.tmpl", {
+        appBar: {current: "reference"},
         document: doc,
         title: doc.name,
         env: config,
@@ -282,6 +313,7 @@ function outTutorials(
     const uri = linker.getURI(tutorial);
 
     pipeline.render("tutorial.tmpl", {
+      appBar: {current: "tutorials"},
       document: tutorial,
       title: tutorial.title,
       env: config,

packages/webdoc-default-template/src/app/components/Header/Header.js

@@ -11,6 +11,9 @@ export default connect(({explorerOpen}) => ({
   explorerOpen,
   setExplorerOpen,
 }) {
+  const items = Object.entries(appData.appBar.items);
+  const currentItemId = appData.appBar.current;
+
   return (
     <div className="header__container">
       {explorerOpen ? null :
@@ -19,8 +22,14 @@ export default connect(({explorerOpen}) => ({
           toggleOpen={() => setExplorerOpen(!explorerOpen)}
         />}
       <div className="header__contents">
-        <a className="header__link header__link__current">API Reference</a>
-        {/* <a className="header__link">Guides</a> */ /* TODO: Add guides */}
+        {items.map(([id, appBarItem], i) => (
+          <a
+            className={`header__link${id === currentItemId ? " header__link__current" : ""}`}
+            href={appBarItem.uri}
+          >
+            {appBarItem.name}
+          </a>
+        ))}
         {appData.integrations.search && <Search integration={appData.integrations.search} />}
       </div>
     </div>

packages/webdoc-default-template/static/scripts/default-template.js

@@ -9657,6 +9657,18 @@ function Search(_ref) {
   }));
 }
 // CONCATENATED MODULE: ./src/app/components/Header/Header.js
+function Header_slicedToArray(arr, i) { return Header_arrayWithHoles(arr) || Header_iterableToArrayLimit(arr, i) || Header_unsupportedIterableToArray(arr, i) || Header_nonIterableRest(); }
+
+function Header_nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+
+function Header_unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return Header_arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return Header_arrayLikeToArray(o, minLen); }
+
+function Header_arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function Header_iterableToArrayLimit(arr, i) { if (typeof Symbol === "undefined" || !(Symbol.iterator in Object(arr))) return; var _arr = []; var _n = true; var _d = false; var _e = undefined; try { for (var _i = arr[Symbol.iterator](), _s; !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i["return"] != null) _i["return"](); } finally { if (_d) throw _e; } } return _arr; }
+
+function Header_arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+
 
 
 
@@ -9676,6 +9688,8 @@ function Search(_ref) {
 })(function Header(_ref2) {
   var explorerOpen = _ref2.explorerOpen,
       setExplorerOpen = _ref2.setExplorerOpen;
+  var items = Object.entries(appData.appBar.items);
+  var currentItemId = appData.appBar.current;
   return React.createElement("div", {
     className: "header__container"
   }, explorerOpen ? null : React.createElement(ExplorerHeader, {
@@ -9685,9 +9699,16 @@ function Search(_ref) {
     }
   }), React.createElement("div", {
     className: "header__contents"
-  }, React.createElement("a", {
-    className: "header__link header__link__current"
-  }, "API Reference"), appData.integrations.search && React.createElement(Search, {
+  }, items.map(function (_ref3, i) {
+    var _ref4 = Header_slicedToArray(_ref3, 2),
+        id = _ref4[0],
+        appBarItem = _ref4[1];
+
+    return React.createElement("a", {
+      className: "header__link".concat(id === currentItemId ? " header__link__current" : ""),
+      href: appBarItem.uri
+    }, appBarItem.name);
+  }), appData.integrations.search && React.createElement(Search, {
     integration: appData.integrations.search
   })));
 }));

packages/webdoc-default-template/tmpl/layout.tmpl

@@ -3,6 +3,7 @@
  * Global layout render component.
  */
 const rootData = obj;
+const appBar = rootData.appBar;
 const document = rootData.document;
 const config = rootData.env.template;
 const siteRoot = this.getPlugin("linker").siteRoot;
@@ -27,6 +28,7 @@ const integrations = JSON.stringify(config.integrations);
     <script>
       window.appData = {
         applicationName: "<?js= config.applicationName ?>",
+        appBar: JSON.parse(`<?js= JSON.stringify(appBar) ?>`),
         explorerTree: "<?js= siteRoot + "/explorer/" + (document && document.type === "TutorialDoc" ? "tutorials" : "reference") + ".json" ?>",
         siteRoot: "<?js= siteRoot ?>",
         integrations: JSON.parse(`<?js= integrations ?>`),

packages/webdoc-template-library/src/TemplateRenderer.js

@@ -8,6 +8,7 @@ import type {
 import {tag, templateLogger} from "./Logger";
 import {SymbolLinks} from "./SymbolLinks";
 import fs from "fs";
+import {merge} from "lodash";
 import path from "path";
 
 let printedDefaultLinker = false;
@@ -65,6 +66,11 @@ export class TemplateRenderer {
     };
   }
 
+  setGlobalTemplateData(data: any): TemplateRenderer {
+    Object.assign(this.data, data);
+    return this;
+  }
+
   setLayoutTemplate(templateFile: string) /*: TemplateRenderer */ {
     this.layout = templateFile;
     return this;
@@ -132,7 +138,7 @@ export class TemplateRenderer {
     try {
       return _.template(fs.readFileSync(filePath, "utf8"), this.settings);
     } catch (e) {
-      templateLogger.error(tag.TemplateLibrary, 'Failure loading template ' + filePath);
+      templateLogger.error(tag.TemplateLibrary, "Failure loading template " + filePath);
       console.error(e);
       throw e;
     }
@@ -167,7 +173,7 @@ export class TemplateRenderer {
     } catch (e) {
       console.error(`Rendering template: ${filePath}`);
       console.error(this.cache[filePath].source
-        .split('\n')
+        .split("\n")
         .map((line, i) => `${i}: ${line}`)
         .join('\n'));
       throw e;
@@ -182,7 +188,8 @@ export class TemplateRenderer {
    * This method automaticaly applies layout if set.
    *
    * @param {string} filePath - file path of the template
-   * @param {object} data - dictionary of all the variables & their values used in the template
+   * @param {object} data - dictionary of all the variables & their values used in the template. For the
+   *  layout, this is deep merged with {@link TemplateRenderer#data}.
    * @return {string} Rendered template.
    */
   render(filePath: string, data: any) {
@@ -195,9 +202,15 @@ export class TemplateRenderer {
 
     // apply layout
     if (this.layout) {
-      data.content = content;
+      const templateData = Array.isArray(data) ? [...data] : { ...data };
+
+      for (const key in this.data) {
+        templateData[key] = merge({}, this.data[key], templateData[key] || {});
+      }
+
+      templateData.content = content;
       templateLogger.info(tag.TemplateLibrary, `Request layout ${filePath} ${data}`);
-      content = this.partial(this.layout, data);
+      content = this.partial(this.layout, templateData);
     }
 
     templateLogger.info(tag.TemplateLibrary, `Rendering2 template ${filePath} ${data}`);