diff --git a/client/src/linkManager.js b/client/src/linkManager.js index e682b982bc..1008638071 100644 --- a/client/src/linkManager.js +++ b/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 diff --git a/client/src/uxManager.js b/client/src/uxManager.js index 9dec26bc34..564cdbc730 100644 --- a/client/src/uxManager.js +++ b/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. diff --git a/core/package.json b/core/package.json index 5818269059..1a24dd8df0 100644 --- a/core/package.json +++ b/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": [ { diff --git a/core/src/core-api/auth.js b/core/src/core-api/auth.js index 296c898b2b..ebb423d850 100644 --- a/core/src/core-api/auth.js +++ b/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(); diff --git a/core/src/core-api/config.js b/core/src/core-api/config.js index 0c16b2aaee..97e705109a 100644 --- a/core/src/core-api/config.js +++ b/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,10 +70,21 @@ 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.'; @@ -44,6 +92,10 @@ class LuigiConfigManager { 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(); diff --git a/core/src/core-api/dom-elements.js b/core/src/core-api/dom-elements.js index 38b6fa664f..f41e40c19e 100644 --- a/core/src/core-api/dom-elements.js +++ b/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(); diff --git a/docs/README.md b/docs/README.md index b2ca31910e..c0b31ab769 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/luigi-client-api.md b/docs/luigi-client-api.md index 6031acc42d..7e8ec15e2e 100644 --- a/docs/luigi-client-api.md +++ b/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. diff --git a/docs/luigi-core-api.md b/docs/luigi-core-api.md new file mode 100644 index 0000000000..4e9e792d48 --- /dev/null +++ b/docs/luigi-core-api.md @@ -0,0 +1,204 @@ +# Luigi Core API + +## Luigi Config + + + +### Configuration + +#### setConfig + +Sets the configuration for Luigi initially. Can also be called at a later point in time again to update the configuration. + +##### Parameters + +- `configInput` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the Luigi Core configuration object + +##### Examples + +```javascript +Luigi.setConfig({ + navigation: { + nodes: () => [ + { + pathSegment: 'home', + label: 'Home', + children: [ + { + pathSegment: 'hello', + label: 'Hello Luigi!', + viewUrl: '/assets/basicexternal.html' + } + ] + } + ] + }, + routing: { + useHashRouting: true + } +}) +``` + +#### getConfig + +Returns the current active configuration + +##### Examples + +```javascript +Luigi.getConfig() +``` + +Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** configuration object + +#### getConfigValue + +Gets value of the given property on Luigi config object. Target can be a value or a synchronous function. + +##### Parameters + +- `property` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the object traversal path + +##### Examples + +```javascript +Luigi.getConfigValue('auth.use') +Luigi.getConfigValue('settings.sideNavFooterText') +``` + +#### getConfigBooleanValue + +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. + +##### Parameters + +- `property` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the object traversal path + +##### Examples + +```javascript +Luigi.getConfigBooleanValue('settings.hideNavigation') +``` + +#### getConfigValueAsync + +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. + +##### Parameters + +- `property` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the object traversal path +- `parameters` **mixed** optional parameters that are used if the target is a function + +##### Examples + +```javascript +Luigi.getConfigValueAsync('navigation.nodes') +Luigi.getConfigValueAsync('navigation.profile.items') +Luigi.getConfigValueAsync('navigation.contextSwitcher.options') +``` + +#### isAuthorizationEnabled + +Detects if authorization is enabled via configuration. + +Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** returns true if authorization is enabled. Otherwise returns false. + +**Meta** + +- **deprecated**: now located in Luigi.auth() instead of Luigi + +## Luigi.elements() + + + +### Elements + +Use these functions to get DOM elements. + +#### getShellbar + +Returns the shellbar component. + +##### Examples + +```javascript +Luigi.elements().getShellbar(); +``` + +Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the shellbar DOM element. + +**Meta** + +- **since**: 0.4.12 + +#### getShellbarActions + +Returns the shellbar actions component. + +##### Examples + +```javascript +Luigi.elements().getShellbarActions(); +``` + +Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the shellbar actions DOM element. + +**Meta** + +- **since**: 0.4.12 + +#### getMicrofrontendIframes + +Returns all micro frontend iframes including the iframe from the modal if it exists. + +##### Examples + +```javascript +Luigi.elements().getMicrofrontendIframes(); +``` + +Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** an array of all micro frontend iframes from the DOM. + +**Meta** + +- **since**: 0.4.12 + +#### getCurrentMicrofrontendIframe + +Returns the active micro frontend iframe. +If there is a modal, which includes the micro frontend iframe, the function returns this iframe. + +##### Examples + +```javascript +Luigi.elements().getCurrentMicrofrontendIframe(); +``` + +Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the active micro frontend iframe DOM element. + +**Meta** + +- **since**: 0.4.12 + +## Luigi.auth() + + + +### Authorization + +Authorization helpers + +#### isAuthorizationEnabled + +Detects if authorization is enabled via configuration. + +##### Examples + +```javascript +Luigi.auth().isAuthorizationEnabled(); +``` + +Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if authorization is enabled. Otherwise returns false.