Core API docu (SAP#602)

documented core api

client/src/linkManager.js

@@ -32,9 +32,9 @@ export class linkManager extends LuigiClientBase {
    * Navigates to the given path in the application hosted by Luigi. It contains either a full absolute path or a relative path without a leading slash that uses the active route as a base. This is the standard navigation.
    * @memberof linkManager
    * @param {string} path path to be navigated to
-   * @param {string} [sessionId] current Luigi **sessionId**
-   * @param {boolean} [preserveView] preserve a view by setting it to `true`. It keeps the current view opened in the background and opens the new route in a new frame. Use the {@link #goBack goBack()} function to navigate back. You can use this feature across different levels. Preserved views are discarded as soon as the standard {@link #navigate navigate()} function is used instead of {@link #goBack goBack()}
-   * @param {Object} [modalSettings] opens a view in a modal. Use these settings to configure the modal's title and size
+   * @param {string} sessionId current Luigi **sessionId**
+   * @param {boolean} preserveView preserve a view by setting it to `true`. It keeps the current view opened in the background and opens the new route in a new frame. Use the {@link #goBack goBack()} function to navigate back. You can use this feature across different levels. Preserved views are discarded as soon as you use the standard {@link #navigate navigate()} function instead of {@link #goBack goBack()}
+   * @param {Object} modalSettings opens a view in a modal. Use these settings to configure the modal's title and size
    * @param {string} modalSettings.title modal title. By default, it is the node label. If there is no label, it is left empty
    * @param {('l'|'m'|'s')} [modalSettings.size="l"] size of the modal
    * @example

client/src/uxManager.js

@@ -77,7 +77,7 @@ class UxManager extends LuigiClientBase {
   /**
    * Shows a confirmation modal.
    * @memberof uxManager
-   * @param {Object} [settings] the settings the confirmation modal. If no value is provided for any of the fields, a default value is set for it
+   * @param {Object} settings the settings of the confirmation modal. If you don't provide any value for any of the fields, a default value is used
    * @param {string} [settings.header="Confirmation"] the content of the modal header
    * @param {string} [settings.body="Are you sure you want to do this?"] the content of the modal body
    * @param {string} [settings.buttonConfirm="Yes"] the label for the modal confirm button
@@ -130,8 +130,8 @@ class UxManager extends LuigiClientBase {
    * @memberof uxManager
    * @param {Object} settings the settings for the alert
    * @param {string} settings.text the content of the alert. To add a link to the content, you have to set up the link in the `links` object. The key(s) in the `links` object must be used in the text to reference the links, wrapped in curly brackets with no spaces. If you don't specify any text, the alert is not displayed
-   * @param {('info'|'success'|'warning'|'error')} [settings.type] sets the type of the alert
-   * @param {Object} [settings.links] provides links data
+   * @param {('info'|'success'|'warning'|'error')} settings.type sets the type of alert
+   * @param {Object} settings.links provides links data
    * @param {Object} settings.links.LINK_KEY object containing the data for a particular link. To properly render the link in the alert message refer to the description of the **settings.text** parameter
    * @param {string} settings.links.LINK_KEY.text text which replaces the link identifier in the alert content
    * @param {string} settings.links.LINK_KEY.url url to navigate when you click the link. Currently, only internal links are supported in the form of relative or absolute paths.

core/package.json

@@ -50,7 +50,11 @@
     "test": "babel-node ./node_modules/nyc/bin/nyc.js mocha -- --recursive test",
     "test:watch": "npm run test -- --watch",
     "bundlesize": "npm run bundle && bundlesize",
-    "docu:validate": "documentation lint src/core-api/dom-elements.js"
+    "docu": "npm run docu:validate && npm run docu:generate:config && npm run docu:generate:dom-elements && npm run docu:generate:auth",
+    "docu:validate": "documentation lint --shallow src/core-api/config.js src/core-api/elements.js src/core-api/auth.js",
+    "docu:generate:config": "documentation readme src/core-api/config.js --shallow -f md --section='Luigi Config' --readme-file=../docs/luigi-core-api.md --markdown-toc=false --github false --quiet",
+    "docu:generate:dom-elements": "documentation readme src/core-api/dom-elements.js --shallow -f md --section='Luigi.elements()' --readme-file=../docs/luigi-core-api.md --markdown-toc=false --github false --quiet",
+    "docu:generate:auth": "documentation readme src/core-api/auth.js --shallow -f md --section='Luigi.auth()' --readme-file=../docs/luigi-core-api.md --markdown-toc=false --github false --quiet"
   },
   "bundlesize": [
     {

core/src/core-api/auth.js

@@ -1,16 +1,35 @@
 import { config } from './config';
 
-class LuigiAuthManager {
+/**
+ * Authorization helpers
+ * @name Authorization
+ */
+class LuigiAuth {
+  /**
+   * @private
+   * @memberof Authorization
+   */
   constructor() {}
 
-  /*
+  /**
    * Detects if authorization is enabled via configuration.
-   * @returns {boolean} returns true if authorization is enabled. Otherwise returns false.
+   * @memberof Authorization
+   * @returns {boolean} true if authorization is enabled. Otherwise returns false.
+   * @example
+   * Luigi.auth().isAuthorizationEnabled();
    */
   isAuthorizationEnabled() {
     return !!config.getConfigValue('auth.use');
   }
 
+  /**
+   * @private
+   * @memberof Authorization
+   * @param {string} eventName
+   * @param {Object} providerInstanceSettings
+   * @param {mixed} data
+   * @param {string} redirectUrl
+   */
   async handleAuthEvent(
     eventName,
     providerInstanceSettings,
@@ -32,4 +51,4 @@ class LuigiAuthManager {
   }
 }
 
-export const auth = new LuigiAuthManager();
+export const auth = new LuigiAuth();

core/src/core-api/config.js

@@ -1,7 +1,14 @@
 import { AsyncHelpers, GenericHelpers } from '../utilities/helpers';
 import { auth } from './auth';
 
-class LuigiConfigManager {
+/**
+ * @name Configuration
+ */
+class LuigiConfig {
+  /**
+   * @private
+   * @memberof Configuration
+   */
   constructor() {
     this.configReadyTimeout = {
       valueMs: 65000,
@@ -13,6 +20,10 @@ class LuigiConfigManager {
     this.initialized = false;
   }
 
+  /**
+   * @private
+   * @memberof Configuration
+   */
   setConfigCallbacks(configReadyCallback) {
     this.configReadyCallback = configReadyCallback;
     this.configReadyTimeout.id = setTimeout(() => {
@@ -22,6 +33,32 @@ class LuigiConfigManager {
     }, this.configReadyTimeout.valueMs);
   }
 
+  /**
+   * Sets the configuration for Luigi initially. Can also be called at a later point in time again to update the configuration.
+   * @memberof Configuration
+   * @param {Object} configInput the Luigi Core configuration object
+   * @example
+   * Luigi.setConfig({
+   *   navigation: {
+   *     nodes: () => [
+   *       {
+   *         pathSegment: 'home',
+   *         label: 'Home',
+   *         children: [
+   *           {
+   *             pathSegment: 'hello',
+   *             label: 'Hello Luigi!',
+   *             viewUrl: '/assets/basicexternal.html'
+   *           }
+   *         ]
+   *       }
+   *     ]
+   *   },
+   *   routing: {
+   *     useHashRouting: true
+   *   }
+   * })
+   */
   setConfig(configInput) {
     clearTimeout(this.configReadyTimeout.id);
     this.config = configInput;
@@ -33,17 +70,32 @@ class LuigiConfigManager {
     }
   }
 
+  /**
+   * Returns the current active configuration
+   * @returns {Object} configuration object
+   * @memberof Configuration
+   * @example
+   * Luigi.getConfig()
+   */
   getConfig() {
     return this.config;
   }
 
+  /**
+   * @private
+   * @memberof Configuration
+   */
   configNotReadyCallback() {
     const errorMsg =
       'Ups.. Looks like Luigi was not configured. Please use Luigi.setConfig(config) function to configure Luigi.';
     console.error(errorMsg);
     this.setErrorMessage(errorMsg);
   }
 
+  /**
+   * @private
+   * @memberof Configuration
+   */
   setErrorMessage(errorMsg) {
     var errorTextNode = document.createTextNode(errorMsg);
     var fd_ui = document.createElement('div');
@@ -62,16 +114,25 @@ class LuigiConfigManager {
     document.body.appendChild(fd_ui);
   }
 
-  /*
-   * Gets value of the given property on Luigi config object.
+  /**
+   * Gets value of the given property on Luigi config object. Target can be a value or a synchronous function.
+   * @memberof Configuration
+   * @param {string} property the object traversal path
+   * @example
+   * Luigi.getConfigValue('auth.use')
+   * Luigi.getConfigValue('settings.sideNavFooterText')
    */
   getConfigValue(property) {
     return GenericHelpers.getConfigValueFromObject(this.getConfig(), property);
   }
 
-  /*
+  /**
    * Gets boolean value of the given property on Luigi config object.
    * Function return true if the property value is equal true or 'true'. Otherwise the function returns false.
+   * @memberof Configuration
+   * @param {string} property the object traversal path
+   * @example
+   * Luigi.getConfigBooleanValue('settings.hideNavigation')
    */
   getConfigBooleanValue(property) {
     const configuredValue = GenericHelpers.getConfigValueFromObject(
@@ -84,10 +145,17 @@ class LuigiConfigManager {
     return false;
   }
 
-  /*
+  /**
    * Gets value of the given property on the Luigi config object.
    * If the value is a Function it is called (with the given parameters) and the result of that call is the value.
    * If the value is not a Promise it is wrapped to a Promise so that the returned value is definitely a Promise.
+   * @memberof Configuration
+   * @param {string} property the object traversal path
+   * @param {mixed} parameters optional parameters that are used if the target is a function
+   * @example
+   * Luigi.getConfigValueAsync('navigation.nodes')
+   * Luigi.getConfigValueAsync('navigation.profile.items')
+   * Luigi.getConfigValueAsync('navigation.contextSwitcher.options')
    */
   getConfigValueAsync(property, ...parameters) {
     return AsyncHelpers.getConfigValueFromObjectAsync(
@@ -97,12 +165,14 @@ class LuigiConfigManager {
     );
   }
 
-  /*
+  /**
    * Executes the function of the given property on the Luigi config object.
    * Fails if property is not a function.
    *
    * If the value is a Function it is called (with the given parameters) and the result of that call is the value.
    * If the value is not a Promise it is wrapped to a Promise so that the returned value is definitely a Promise.
+   * @private
+   * @memberof Configuration
    */
   async executeConfigFnAsync(property, throwError = false, ...parameters) {
     const fn = this.getConfigValue(property);
@@ -119,14 +189,15 @@ class LuigiConfigManager {
     // Promise.reject(property + ' is not a function.');
     return Promise.resolve(undefined);
   }
-  /*
+  /**
    * Detects if authorization is enabled via configuration.
+   * @memberof Configuration
    * @returns {boolean} returns true if authorization is enabled. Otherwise returns false.
-   * @deprecated now located in Luigi.auth() instead of LuigiConfig
+   * @deprecated now located in Luigi.auth() instead of Luigi
    */
   isAuthorizationEnabled() {
     return auth.isAuthorizationEnabled();
   }
 }
 
-export const config = new LuigiConfigManager();
+export const config = new LuigiConfig();

core/src/core-api/dom-elements.js

@@ -1,13 +1,15 @@
-/** @namespace */
-class LuigiElementsManager {
-  /**
-   * Use these functions to get DOM elements.
-   * @name LuigiElements
-   */
+/**
+ * Use these functions to get DOM elements.
+ * @namespace Elements
+ */
+class LuigiElements {
   /**
    * Returns the shellbar component.
    * @returns {Object} the shellbar DOM element.
-   * @memberof LuigiElements
+   * @memberof Elements
+   * @since 0.4.12
+   * @example
+   * Luigi.elements().getShellbar();
    */
   getShellbar() {
     return document.getElementsByClassName('fd-shellbar')[0];
@@ -16,7 +18,10 @@ class LuigiElementsManager {
   /**
    * Returns the shellbar actions component.
    * @returns {Object} the shellbar actions DOM element.
-   * @memberof LuigiElements
+   * @memberof Elements
+   * @since 0.4.12
+   * @example
+   * Luigi.elements().getShellbarActions();
    */
   getShellbarActions() {
     return document.getElementsByClassName('fd-shellbar__actions')[0];
@@ -25,7 +30,10 @@ class LuigiElementsManager {
   /**
    * Returns all micro frontend iframes including the iframe from the modal if it exists.
    * @returns {Object} an array of all micro frontend iframes from the DOM.
-   * @memberof LuigiElements
+   * @memberof Elements
+   * @since 0.4.12
+   * @example
+   * Luigi.elements().getMicrofrontendIframes();
    */
   getMicrofrontendIframes() {
     return [...document.querySelectorAll('.iframeContainer iframe')].concat([
@@ -37,7 +45,10 @@ class LuigiElementsManager {
    * Returns the active micro frontend iframe.
    * If there is a modal, which includes the micro frontend iframe, the function returns this iframe.
    * @returns {Object} the active micro frontend iframe DOM element.
-   * @memberof LuigiElements
+   * @memberof Elements
+   * @since 0.4.12
+   * @example
+   * Luigi.elements().getCurrentMicrofrontendIframe();
    */
   getCurrentMicrofrontendIframe() {
     let modalIframes = document.querySelectorAll('.iframeModalCtn iframe');
@@ -53,4 +64,4 @@ class LuigiElementsManager {
   }
 }
 
-export const elements = new LuigiElementsManager();
+export const elements = new LuigiElements();

docs/README.md

@@ -11,6 +11,7 @@ Set up and configure the main application.
 * [Authorization configuration](authorization-configuration.md) guides you through the configuration to secure Luigi.
 * [Authorization events](authorization-events.md) guides you through the event configuration to react to Luigi authorization events.
 * [General settings](general-settings.md) provides you with additional configuration parameters for Luigi.
+* [Core API](luigi-core-api.md) provides you with API features that help you enrich and use Luigi Core.
 
 ## Luigi Client
 

docs/luigi-client-api.md

@@ -84,9 +84,9 @@ Navigates to the given path in the application hosted by Luigi. It contains eith
 #### Parameters
 
 -   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** path to be navigated to
--   `sessionId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** current Luigi **sessionId**
--   `preserveView` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** preserve a view by setting it to `true`. It keeps the current view opened in the background and opens the new route in a new frame. Use the [goBack()](#goBack) function to navigate back. You can use this feature across different levels. Preserved views are discarded as soon as the standard [navigate()](#navigate) function is used instead of [goBack()](#goBack)
--   `modalSettings` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** opens a view in a modal. Use these settings to configure the modal's title and size
+-   `sessionId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** current Luigi **sessionId**
+-   `preserveView` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** preserve a view by setting it to `true`. It keeps the current view opened in the background and opens the new route in a new frame. Use the [goBack()](#goBack) function to navigate back. You can use this feature across different levels. Preserved views are discarded as soon as you use the standard [navigate()](#navigate) function instead of [goBack()](#goBack)
+-   `modalSettings` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** opens a view in a modal. Use these settings to configure the modal's title and size
     -   `modalSettings.title` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** modal title. By default, it is the node label. If there is no label, it is left empty
     -   `modalSettings.size` **(`"l"` \| `"m"` \| `"s"`)** size of the modal (optional, default `"l"`)
 
@@ -239,7 +239,7 @@ Shows a confirmation modal.
 
 #### Parameters
 
--   `settings` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** the settings the confirmation modal. If no value is provided for any of the fields, a default value is set for it
+-   `settings` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the settings of the confirmation modal. If you don't provide any value for any of the fields, a default value is used
     -   `settings.header` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the content of the modal header (optional, default `"Confirmation"`)
     -   `settings.body` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the content of the modal body (optional, default `"Are you sure you want to do this?"`)
     -   `settings.buttonConfirm` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the label for the modal confirm button (optional, default `"Yes"`)
@@ -255,8 +255,8 @@ Shows an alert.
 
 -   `settings` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the settings for the alert
     -   `settings.text` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the content of the alert. To add a link to the content, you have to set up the link in the `links` object. The key(s) in the `links` object must be used in the text to reference the links, wrapped in curly brackets with no spaces. If you don't specify any text, the alert is not displayed
-    -   `settings.type` **(`"info"` \| `"success"` \| `"warning"` \| `"error"`)?** sets the type of the alert
-    -   `settings.links` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** provides links data
+    -   `settings.type` **(`"info"` \| `"success"` \| `"warning"` \| `"error"`)** sets the type of alert
+    -   `settings.links` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** provides links data
         -   `settings.links.LINK_KEY` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** object containing the data for a particular link. To properly render the link in the alert message refer to the description of the **settings.text** parameter
             -   `settings.links.LINK_KEY.text` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** text which replaces the link identifier in the alert content
             -   `settings.links.LINK_KEY.url` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** url to navigate when you click the link. Currently, only internal links are supported in the form of relative or absolute paths.