Document view groups (SAP#627)

README.md

@@ -50,7 +50,7 @@ import {
   linkManager,
   uxManager
 } from '@kyma-project/luigi-client/luigi-client-ie11';
-<!-- } from '@kyma-project/luigi-client'; -->
+// } from '@kyma-project/luigi-client';
 ``` 
 
 >**NOTE**: The angular example application is not fully compatible with IE11.

core/src/services/preloading.js

@@ -13,7 +13,7 @@ class ViewGroupPreloadingClass {
     const preloadViewGroupsSetting = LuigiConfig.getConfigValue(
       'navigation.preloadViewGroups'
     );
-    if ([false, 'false'].includes(preloadViewGroupsSetting)) {
+    if (preloadViewGroupsSetting === false) {
       return;
     }
     const vgSettings = Iframe.getAllViewGroupSettings();

docs/navigation-configuration.md

@@ -268,3 +268,16 @@ Luigi.setConfig({
     ]
   }
 });
+```
+
+## View groups
+
+The view groups feature allows you to override the default iframes management policy. Imagine your application hosts two micro frontend views: `http://mysite.com/a#e` and  `http://mysite.com/b#f`. Due to hash routing and a different path up to `#`, they are, by default, rendered in different iframes. However, as they both have the **same origin**, such as`mysite.com`, and belong to the **same micro frontend** you want to render them in the same iframe. To achieve that, use the view groups feature. Define the **viewGroup** parameter for top navigation nodes. The children nodes will automatically be considered as part of the same view group. 
+
+Nodes belonging to the same view group are always rendered in their own view group iframe. Nodes not belonging to any view group follow the same-origin iframe rendering policy. 
+
+The view groups feature also offers out-of-the-box caching. Each time you navigate to another view group, either a new iframe is created or it is reused if already exists. In both cases, the iframe you are navigating from becomes hidden and is available for you to use again. If you navigate back to the first iframe and it should be updated with new data, such when a new entry was added in the second iframe and you want to display it in a table in the first iframe, you must define a **preloadUrl** parameter for a given view in the view group to ensure that the view is refreshed when you navigate back to it. 
+
+You can also preload view groups. You just need to define which URL you want to preload, and Luigi will preload the view after some user interactions when the browser is most likely to be idle. This option is active by default, but you can deactivate it with a [configuration flag](navigation-parameters-reference.md#node-parameters).
+
+For more information on setting caching with view refreshing and preloading for view groups, read [this document](navigation-parameters-reference.md#node-parameters).

docs/navigation-parameters-reference.md

@@ -16,29 +16,87 @@ Luigi.setConfig({
   // navigation structure and settings
   navigation: {
     nodeAccessibilityResolver: function (nodeToCheckPermissionFor, parentNode, currentContext) {},
-    nodes: [
-        // STATIC navigation node
-      {
-        pathSegment: 'settings',
-        label: 'Settings',
-        viewUrl: 'https://admin.mydomain.com/settings',
-        viewGroup: 'settingsGroup',
-        // optional
-        children: [node, node, node],
-        hideFromNav: false,
-        isolateView: false,
-        icon: 'settings'
+  viewGroupSettings: {
+    main: {
+      preloadUrl: 'https://my-site.com/index.html#/preload',
+    },
+    projects: {
+      preloadUrl: 'https://my-site.com/projects.html#/preloading',
+    },
+    envs: {
+      preloadUrl: 'https://my-site.com/environments-details.html#/preload-view',
+    }
+  },
+  nodes: [
+    // STATIC navigation node
+    {
+      pathSegment: 'settings',
+      label: 'Settings',
+      viewUrl: 'https://admin.mydomain.com/settings',
+      viewGroup: 'settingsGroup',
+      // optional
+      children: [node, node, node],
+      hideFromNav: false,
+      isolateView: false,
+      icon: 'settings'
+    },
+    // DYNAMIC navigation node
+    {
+      navigationContext: 'contextName',
+      pathSegment: ':projectId',
+      viewUrl: '/some/path/:projectId',
+      context: {
+        projectId: ':projectId'
       },
-        // DYNAMIC navigation node
-      {
-        navigationContext: 'contextName',
-        pathSegment: ':projectId',
-        viewUrl: '/some/path/:projectId',
-        context: {
-          projectId: ':projectId'
-        },
-        children: [node, node, node]
+      children: [node, node, node]
+    },
+    // View groups nodes
+    {
+      viewGroup: 'main',
+      pathSegment: 'overview',
+      label: 'Overview',
+      viewUrl: 'https://my-site.com/index.html#/overview'
+    },
+    {
+      viewGroup: 'main',
+      pathSegment: 'preload',
+      viewUrl: 'https://my-site.com/index.html#/preload'
+    },
+    {
+      viewGroup: 'projects',
+      pathSegment: 'projects',
+      label: 'Projects',
+      viewUrl: 'https://my-site.com/projects.html#/list',
+      children: [
+        {
+          pathSegment: 'preloading',
+          viewUrl: 'https://my-site.com/projects.html#/preloading'
+        }
+      ]
+    },
+    {
+      viewGroup: 'envs',
+      pathSegment: 'create-environment',
+      viewUrl: 'https://my-site.com/environments.html#/create',
+      context: {
+        label: 'Create Environment'
       }
+    },
+    {
+      viewGroup: 'envs',
+      pathSegment: 'environments',
+      viewUrl: 'https://my-site.com/environments-details.html#/list',
+      children: [
+        {
+          pathSegment: 'preload',
+          viewUrl: 'https://my-site.com/environments-details.html#/preload-view'
+        },
+        {
+          pathSegment: 'env1',
+          viewUrl: 'https://my-site.com/environments-details.html#/details/env1'
+        }
+      ]
+    }
     ],
     contextSwitcher: {
       defaultLabel: 'Select Environment ...',
@@ -91,6 +149,9 @@ The node navigation parameters are as follows:
 - **nodeAccessibilityResolver** allows you to define a permission checker function that gets executed on every node. If it returns `false`, Luigi removes the node and its children from the navigation structure.
 - **nodeAccessibilityResolver** receives all values defined in the node configuration. See [angular basicConfiguration.js](../core/examples/luigi-sample-angular/src/assets/basicConfiguration.js) for the **constraints** example.
 - **defaults.isolateView** renders all views in new frames. This setting overrides the same-domain frame reuse. The **defaults.isolateView** is disabled by default, and you can overwrite it using the **isolateView** value on a single node level.
+- **preloadViewGroups**(bool) allows deactivating the default preloading of [view groups](navigation-configuration.md#view-groups) iframes.
+- **viewGroupsSettings** is an object containing key-object pairs, where the key is the view group name as specified in the node parameters, and the object contains key-value pairs. In each key-value pair, the key is the feature name and the value is the actual setting. The following options are supported:
+  - **preloadUrl**(string): needs to be an absolute URL for a node from the view group. It is recommended that you use a dedicated small, visually empty view, which imports Luigi Client and is fine with getting an empty context, for example, without an access token. The **preloadUrl** parameter is also required for view group caching in case you need a view group iframe to refresh whenever you navigate back to it.
 
 ## Node parameters
 
@@ -110,6 +171,7 @@ The node parameters are as follows:
 - **context** sends the specified object as context to the view. Use this parameter 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**.
 - **defaultChildNode** sets the child node that Luigi activates automatically if the current node has no **viewUrl** defined. Provide **pathSegment** of the child node you want to activate as a string.
 - **isolateView** renders the view in a new frame when you enter and leave the node. This setting overrides the same-domain frame re-usage. The **isolateView** is disabled by default.
+- **viewGroup** allows you to associate nodes to be rendered in the same iframe, as long as they belong to the same origin. The value of this parameter is considered as the view group id. For further explanations, see [this section](navigation-configuration.md#view-groups).
 - **keepSelectedForChildren** focuses the navigation on its current hierarchy, omitting the display of children.
 - **loadingIndicator.enabled** shows a loading indicator when switching between micro front-ends. If you have a fast micro front-end, you can disable this feature to prevent flickering of the loading indicator. This parameter is enabled by default.
 - **loadingIndicator.hideAutomatically** disables the automatic hiding of the loading indicator once the micro front-end is loaded. It is only considered if the loading indicator is enabled. It does not apply if the loading indicator is activated manually with the `LuigiClient.uxManager().showLoadingIndicator()` function. If the loading indicator is enabled and automatic hiding is disabled, use `LuigiClient.uxManager().hideLoadingIndicator()` to hide it manually in your micro front-end during the startup. This parameter is enabled by default.
@@ -152,3 +214,5 @@ The profile section is a configurable drop-down list available in the top naviga
   - **externalLink** is an object which indicates that the node links to an external URL. If this parameter is defined, the **link** parameter is ignored. It has the following properties:
     - **sameWindow** defines if the external URL is opened in the current tab or in a new one. The default value for this parameter is `false`.
     - **url** is the external URL that the link leads to.
+
+