Documentation fixes (SAP#1003)

* various fixes * example information * tab nav illustration * fix * add defaults to parameters * fix pics * Update docs/navigation-advanced.md Co-Authored-By: Markus <[email protected] Co-authored-by: JohannesDoberer <[email protected]> Co-authored-by: Markus <[email protected]>
kazydek · Jan 15, 2020 · 7085b1a · 7085b1a
1 parent 9ef7fba
commit 7085b1a
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 122 deletions.
diff --git a/docs/application-setup.md b/docs/application-setup.md
@@ -29,7 +29,7 @@ Choose the framework to build your application:
 
 Follow these steps to build a web application based on Luigi:
 
-1. Add Luigi npm packages to your project dependencies. 
+1. Add Luigi npm packages to your project dependencies.
 
 ````
 npm install --save @kyma-project/luigi-core
@@ -44,8 +44,8 @@ npm install --save @kyma-project/luigi-client
 
 The examples on this page demonstrate commands that perform each of the necessary steps to set up your application. Each set of commands is grouped by the framework on which you execute it.
 
-<a name="noframework"></a> 
-### Application setup for an application not using a framework 
+<a name="noframework"></a>
+### Application setup for an application not using a framework
 
 <!-- add-attribute:class:warning -->
 > **NOTE:** You need a development server capable of hosting Single Page Applications. The recommended server is Live Server.
@@ -68,7 +68,7 @@ mkdir my-new-app && cd my-new-app
 npm init -y
 sed 's/"scripts": {/"scripts": {\
 \   "buildConfig":"webpack --entry .\/src\/luigi-config\/basic\/basicConfiguration.js -o .\/public\/assets\/sampleconfig.js --mode production",/1' package.json > p.tmp.json && mv p.tmp.json package.json
-npm i -save @kyma-project/luigi-core @kyma-project/luigi-client fiori-fundamentals webpack webpack-cli @babel/core @babel/preset-env babel-loader 
+npm i -save @kyma-project/luigi-core @kyma-project/luigi-client fiori-fundamentals webpack webpack-cli @babel/core @babel/preset-env babel-loader
 mkdir -p public/assets
 mkdir -p src/luigi-config/basic
 curl https://raw.githubusercontent.com/SAP/luigi/master/core/examples/luigi-sample-angular/src/index.html > public/index.html
@@ -98,7 +98,7 @@ bash <(curl -s https://raw.githubusercontent.com/SAP/luigi/master/scripts/setup/
 or execute these commands manually to get the same result:
 ```bash
 ng new my-angular-app --routing && cd my-angular-app
-npm i -P @kyma-project/luigi-core @kyma-project/luigi-client fiori-fundamentals webpack webpack-cli @babel/core @babel/preset-env babel-loader 
+npm i -P @kyma-project/luigi-core @kyma-project/luigi-client fiori-fundamentals webpack webpack-cli @babel/core @babel/preset-env babel-loader
 sed 's/"scripts": {/"scripts": {\
 \   "buildConfig":"webpack --entry .\/src\/luigi-config\/basic\/basicConfiguration.js -o .\/src\/assets\/sampleconfig.js --mode production",/1' package.json > p.tmp.json && mv p.tmp.json package.json
 mkdir -p src/luigi-config/basic
@@ -116,7 +116,7 @@ npm run start
 
 <a name="sapui5"></a>
 
-### Application setup for SAPUI5/OpenUI5 
+### Application setup for SAPUI5/OpenUI5
 
 <!-- add-attribute:class:warning -->
 > **NOTE:** Live Server must be installed as your development server.
@@ -150,7 +150,7 @@ $ live-server --entry-file=index.html public
 
 <a name="vuejs"></a>
 
-### Application setup for VUE.JS 
+### Application setup for VUE.JS
 
 <!-- add-attribute:class:warning -->
 > **NOTE:** The VUE CLI is a prerequisite for this example.

diff --git a/docs/assets/tabnav.png b/docs/assets/tabnav.png
diff --git a/docs/navigation-advanced.md b/docs/navigation-advanced.md
@@ -24,6 +24,7 @@ This document shows you how to configure the following Luigi features:
 * [Context switcher](#context-switcher) 
 * [Product switcher](#product-switcher) 
 * [App switcher](#app-switcher) 
+* [Tab navigation](#tab-navigation)
 * [Additional options](#additional-options)
 
 ## View groups
@@ -207,37 +208,27 @@ Luigi.setConfig({
 
 ## Contexts
 
-Contexts can serve as an alternative way to create a dynamically changeable path in the **viewUrl**. They are used together with path parameters and utilize the Luigi Client to receive contexts for the micro frontends.
-
-You can create a context by adding these parameters to your node:
-
-### navigationContext
-- **type**: string
-- **description**: contains a named node that is mainly for use in combination with a dynamic **pathSegment** to start navigation from a dynamic node using `LuigiClient.linkManager().fromContext('contextname')`.
+The purpose of contexts is to send objects to the micro frontend. You can do this by adding this parameter to your node:
 
 ### context
 - **type**: object
 - **description**: sends the specified object as context to the view. Use this property in combination with the dynamic **pathSegment** to receive the context through the context listeners of Luigi Client. This is an alternative to using the dynamic value in the **viewUrl**.
 
-Here is an example of a dynamic navigation node including a context:
+One example of where contexts are used is during the creation of dynamic navigation nodes. Used together with path parameters and Luigi Client, contexts pass information to the micro frontend:
 
 ```javascript
-...
-      {
-        navigationContext: 'contextName',
-        pathSegment: ':projectId',
-        testId: 'myTestId',
-        viewUrl: '/some/path/:projectId',
-        context: {
-          projectId: ':projectId'
-        },
-        children: [node, node, node]
-      }
-```
+{
+  pathSegment: ':projectId',
+  viewUrl: '/some/path/:projectId',
+  context: {
+    projectId: ':projectId'
+  }
+}
+ ```
 
 ## Profile
 
-<img src="https://github.com/SAP/luigi/raw/c70658fcb78c48012303a4e59012d5d158ca46b3/docs/assets/profile.png" width="628">
+<img src="https://github.com/SAP/luigi/blob/master/docs/assets/profile.png?raw=true" width="628">
 
 The profile is a drop-down list in the top navigation that allows you to override the logout item content if authorization is already configured. You can also add links to Luigi navigation nodes.
 
@@ -246,103 +237,113 @@ You can configure the profile element in the top navigation by adding the **prof
 Example:
 
 ```javascript
-  profile: {
-      logout: {
-        label: 'End session'
-        icon: "sys-cancel",
-        customLogoutFn: myLogoutFn
-      },
+profile: {
+  logout: {
+    label: 'End session'
+    icon: "sys-cancel",
+    customLogoutFn: myLogoutFn
+  },
+}
 ```
 
 
 ## Context switcher
 
-<img src="https://github.com/SAP/luigi/raw/c70658fcb78c48012303a4e59012d5d158ca46b3/docs/assets/context-switcher.png" width="628">
+<img src="https://github.com/SAP/luigi/blob/master/docs/assets/context-switcher.png?raw=true" width="628">
 
 The context switcher is a drop-down element in the top navigation. It allows you to switch between a curated list of navigation elements such as Environments. To do so, add the **contextSwitcher** property to the navigation object. Find all the parameters you can use to configure it [here](navigation-parameters-reference.md#context-switcher).
 
  Example:
 
 ```javascript
 contextSwitcher: {
-      defaultLabel: 'Select Environment ...',
-      testId: 'myTestId',
-      parentNodePath: '/environments',
-      lazyloadOptions: false,
-      fallbackLabelResolver: (id) => (id.toUpperCase()),
-      options: [{label,pathValue}, {label,pathValue}],
-      customOptionsRenderer: (option, isSelected) => {let className = 'fd-menu__item' + (isSelected ? ' is-selected' : '');
-      return `<a class="${className}">${option.label} test</a>`;},
-      actions: [{label,link,position,clickHandler?}]
-    },
+  defaultLabel: 'Select Environment ...',
+  testId: 'myTestId',
+  parentNodePath: '/environments',
+  lazyloadOptions: false,
+  fallbackLabelResolver: (id) => (id.toUpperCase()),
+  options: [{label,pathValue}, {label,pathValue}],
+  customOptionsRenderer: (option, isSelected) => {let className = 'fd-menu__item' + (isSelected ? ' is-selected' : '');
+  return `<a class="${className}">${option.label} test</a>`;},
+  actions: [{label,link,position,clickHandler?}]
+},
 ```
 
 ## Product switcher
 
-<img src="https://github.com/SAP/luigi/raw/c70658fcb78c48012303a4e59012d5d158ca46b3/docs/assets/product-switcher.png" width="704">
+<img src="https://github.com/SAP/luigi/blob/master/docs/assets/product-switcher.png?raw=true" width="704">
 
 The product switcher is window in top the navigation which allows you to switch between navigation elements displayed there. To add it to your application, include the **productSwitcher** property in your **navigation** object. You may also add any of the parameters listed [here](navigation-parameters-reference.md#product-switcher).
 
 Example:
 ```javascript
 productSwitcher: {
-      label: 'My Products',
+  label: 'My Products',
+  testId: 'myTestId',
+  icon: 'grid',
+  items: [
+    {
+      icon: '',
+      label: 'Luigi in Github',
       testId: 'myTestId',
-      icon: 'grid',
-      items: [
-        {
-          icon: '',
-          label: 'Luigi in Github',
-          testId: 'myTestId',
-          externalLink: {
-            url: 'https://luigi-project.io/',
-            sameWindow: false
-          }
-        },
-        {
-          icon: '',
-          label: 'Project 1',
-          testId: 'myTestId',
-          link: '/projects/pr1'
-        }
-      ]
+      externalLink: {
+        url: 'https://luigi-project.io/',
+        sameWindow: false
+      }
     },
+    {
+      icon: '',
+      label: 'Project 1',
+      testId: 'myTestId',
+      link: '/projects/pr1'
+    }
+  ]
+},
 ```
 
 ## App switcher
 
-<img src="https://github.com/SAP/luigi/raw/c70658fcb78c48012303a4e59012d5d158ca46b3/docs/assets/app-switcher.png" width="407">
+<img src="https://github.com/SAP/luigi/blob/master/docs/assets/app-switcher.png?raw=true" width="407">
 
 The app switcher is a drop-down in top the navigation which allows you to switch between applications. To use it, add the **appSwitcher** property in your **navigation** object. You may also add any of the parameters listed [here](navigation-parameters-reference.md#app-switcher).
 
 Example:
 
 ```javascript
 appSwitcher = {
-    showMainAppEntry: true,
-    items: [
-      {
-        title: 'Application One',
-        subTitle: 'the first app',
-        link: '/projects/pr1'
-      },
-      {
-        title: 'Application Two',
-        link: '/projects/pr2',
-        subTitle: 'the second app'
-      },
-    ]
-  };
+  showMainAppEntry: true,
+  items: [
+    {
+      title: 'Application One',
+      subTitle: 'the first app',
+      link: '/projects/pr1'
+    },
+    {
+      title: 'Application Two',
+      link: '/projects/pr2',
+      subTitle: 'the second app'
+    },
+  ]
+};
 ```
 
+## Tab navigation
+
+<img src="https://github.com/SAP/luigi/blob/master/docs/assets/tabnav.png?raw=true" width="710">
+
+Tab-style navigation in Luigi can be displayed directly above the micro frontend area, providing you with additional menu options. When you put tab navigation nodes into a [category](navigation-configuration.md#category), they will be rendered in a drop-down. Add this parameter to your configuration to create tab navigation nodes:
+
+### tabNav
+- **type**: boolean
+- **description**: renders the children of the node as a horizontal navigation bar. Sub-children are not supported. When you categorize nodes you will get a drop-down menu in the horizontal navigation.
+
 ## Additional options
 
 For more options and parameters which you can use to configure navigation in Luigi, read the [full parameter reference](navigation-parameters-reference.md). Some of the topics you can find there include:
 
 * Defining the [routing](navigation-parameters-reference.md#routing-parameters) strategy of your application
 * Enabling and disabling the [loading indicator](navigation-parameters-reference.md#loadingindicatorenabled)
 * Hiding [navigation nodes](navigation-parameters-reference.md#hidefromnav) or [side navigation](navigation-parameters-reference.md#hidesidenav)
-* Including a horizontal [tab navigation](navigation-parameters-reference.md#tabnav) bar
 * Displaying content in a [modal](navigation-parameters-reference.md#opennodeinmodal)
 * Adding a [badge counter](navigation-parameters-reference.md#badgecounter) to your nodes
-* Defining a custom [testId](navigation-parameters-reference.md#testid) for your nodes
+* Defining a custom [testId](navigation-parameters-reference.md#testid) for end-to-end tests
diff --git a/docs/navigation-configuration-example.md b/docs/navigation-configuration-example.md
@@ -1,22 +1,23 @@
 <!-- meta
 {
   "node": {
-    "label": "Configuration Example",
+    "label": "Navigation configuration Example",
     "category": {
-      "label": "Luigi Core"
+      "label": "Examples"
     },
     "metaData": {
-      "categoryPosition": 2,
-      "position": 10
-    },
-    "hideFromNav": true
+      "categoryPosition": 5,
+      "position": 0
+    }
   }
 }
 meta -->
 
 # Navigation configuration example
 
-This example represents a sample Luigi navigation configuration including parameters described in the [navigation parameters reference](navigation-parameters-reference.md).
+This example represents a Luigi navigation configuration example including parameters described in the [navigation parameters reference](navigation-parameters-reference.md).
+
+Note that this is not a functional example, as its purpose is to illustrate different configuration options. For example, the line `children: [node, node, node]` will return an error because `node` is just a placeholder which has to be replaced by actual nodes.
 
 ```javascript
 Luigi.setConfig({

diff --git a/docs/navigation-configuration.md b/docs/navigation-configuration.md
@@ -15,12 +15,7 @@ meta -->
 
 #  Basic navigation configuration
 
-Read these guides to get started with configuring your navigation:
-
-* [Navigation elements](#navigation-elements)
-* [First steps](#first-steps)
-* [Basic navigation parameters](#basic-navigation-parameters)
-* [Grouping navigation nodes](#grouping-navigation-nodes)
+This guide describes some basic features of Luigi navigation and how to configure it.
 
 If you are already familiar with the basics, take a look at:
 * [Advanced navigation configuration](navigation-advanced.md)
@@ -30,9 +25,10 @@ If you are already familiar with the basics, take a look at:
 
 There are three main elements to Luigi:
 
-1. Top navigation which displays the main navigation path. Additionally, it can include context, product, app, and profile [switchers](navigation-parameters-reference.md#context-switcher) .
+1. Top navigation which displays the main navigation path. Additionally, it can include context, product, app, and profile [switchers](navigation-advanced.md#context-switcher).
 
 2. Side navigation which displays the child nodes of the root navigation node. It can include structures like collapsible dropdowns and categories which can be used for deep linking.
+
 3. Main content window which renders the micro frontend.
 
 
@@ -41,11 +37,11 @@ There are three main elements to Luigi:
 
 ## First steps
 
-To configure navigation, edit the `luigi-config/extended/navigation.js` file in your project.
+To configure navigation, edit the file in the `src/luigi-config` folder of your project, specifically the `navigation:` category.
 
-You can also use the file in `luigi-config/basic` or the [Luigi Fiddle](https://fiddle.luigi-project.io) to configure a simple application that is not intended for real-life purposes.
+>**TIP:** You can use [Luigi Fiddle](https://fiddle.luigi-project.io) to experiment with configuration.
 
-The configuration file consists of a tree-like structure of **navigation nodes**. The first level nodes represent the top navigation, while their children represent the side navigation. The nodes have some basic properties, such as labels, links, views, and (optionally) children. These properties are called **navigation parameters**.
+The configuration file contains a tree-like structure of **navigation nodes**. The first level nodes represent the top navigation, while their children represent the side navigation. The nodes have some basic properties, such as labels, links, views, and (optionally) children. These properties are called **navigation parameters**.
 
 Here is an example of a simple navigation structure:
 
@@ -90,7 +86,7 @@ navigation: {
 <!-- add-attribute:class:warning -->
 >**NOTE:** For a full list of available parameters, see the [parameter reference](navigation-parameters-reference.md) document.
 
-The [first steps](#first-steps) example provides some basic navigation parameters:
+The [first steps](#first-steps) example contains some basic navigation parameters:
 
 ### pathSegment
 This is used to build the path in the browser URL. The main application path is built from values in the navigation path, joined with the **/** character. For example, if the value of a node's **pathSegment** is `home`, the path for that node would be `[YOUR.WEBSITE]/home`.  You can override this setting by using one of the following instead of **pathSegment**: