This document outlines the features provided by the Luigi Core API. It covers these topics:
- Configuration - functions related to Luigi configuration
- Elements - functions related to DOM elements
- Authorization - authorization options for Luigi
- Navigation - functions related to Luigi navigation
- Localization - options related to language, translation, and localization
- Custom messages - custom messages between Luigi Core and micro frontends
- UX - functions related to Luigi's appearance and user interface
- Global search - functions related to Luigi's global search
- Theming - functions related to Luigi theming capabilties
- Feature toggles - functions related to Luigi's feature toggle mechanism
- Routing - functions to get and set search query parameters
Sets the configuration for Luigi initially. Can also be called at a later point in time again to update the configuration.
configInput
Object the Luigi Core configuration object
Luigi.setConfig({
navigation: {
nodes: () => [
{
pathSegment: 'home',
label: 'Home',
children: [
{
pathSegment: 'hello',
label: 'Hello Luigi!',
viewUrl: '/assets/basicexternal.html'
}
]
}
]
},
routing: {
useHashRouting: true
}
})
Returns the current active configuration
Luigi.getConfig()
Returns Object configuration object
Tells Luigi that the configuration has been changed. Luigi will update the application or parts of it based on the specified scope.
scope
...string one or more scope selectors specifying what parts of the configuration were changed. If no scope selector is provided, the whole configuration is considered changed.The supported scope selectors are:
navigation
: the navigation part of the configuration was changed. This includes navigation nodes, the context switcher, the product switcher and the profile menu.navigation.nodes
: navigation nodes were changed.navigation.contextSwitcher
: context switcher related data were changed.navigation.productSwitcher
: product switcher related data were changed.navigation.profile
: profile menu was changed.settings
: settings were changed.settings.header
: header settings (title, icon) were changed.settings.footer
: left navigation footer settings were changed.
Gets value of the given property on Luigi config object. Target can be a value or a synchronous function.
property
string the object traversal path
Luigi.getConfigValue('auth.use')
Luigi.getConfigValue('settings.sideNavFooterText')
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.
property
string the object traversal path
Luigi.getConfigBooleanValue('settings.hideNavigation')
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.
property
string the object traversal pathparameters
any optional parameters that are used if the target is a function
Luigi.getConfigValueAsync('navigation.nodes')
Luigi.getConfigValueAsync('navigation.profile.items')
Luigi.getConfigValueAsync('navigation.contextSwitcher.options')
Detects if authorization is enabled via configuration.
Returns boolean returns true if authorization is enabled. Otherwise returns false.
Meta
- deprecated: now located in Luigi.auth() instead of Luigi
Unloads the current Luigi instance, which can be initialized later again by using Luigi.setConfig({...})
Luigi.unload()
Meta
- since: 1.2.2
Reads the user settings object.
You can choose a custom storage to read the user settings by implementing the userSetting.readUserSettings
function in the settings section of the Luigi configuration.
By default, the user settings will be read from the localStorage
Luigi.readUserSettings();
Returns promise a promise when a custom readUserSettings
function in the settings.userSettings section of the Luigi configuration is implemented. It resolves a stored user settings object. If the promise is rejected the user settings dialog will also closed if the error object has a closeDialog
property, e.g reject({ closeDialog: true, message: 'some error' })
. In addition a custom error message can be logged to the browser console.
Meta
- since: 1.7.1
Stores the user settings object.
You can choose a custom storage to write the user settings by implementing the userSetting.storeUserSettings
function in the settings section of the Luigi configuration
By default, the user settings will be written from the localStorage
userSettingsObj
Object to store in the storage.previousUserSettingsObj
Object the previous object from storage.
Luigi.storeUserSettings(userSettingsobject, previousUserSettingsObj);
Returns promise a promise when a custom storeUserSettings
function in the settings.userSettings section of the Luigi configuration is implemented. If it is resolved the user settings dialog will be closed. If the promise is rejected the user settings dialog will also closed if the error object has a closeDialog
property, e.g reject({ closeDialog: true, message: 'some error' })
. In addition a custom error message can be logged to the browser console.
Meta
- since: 1.7.1
Reset the current Luigi instance and initialize Luigi with the latest Luigi config.
Luigi.reset();
Meta
- since: 1.14.0
Use these functions to get DOM elements.
Returns the container of the Luigi content.
Luigi.elements().getLuigiContainer();
Returns HTMLElement the DOM element that wraps the Luigi content
Meta
- since: 0.6.0
Returns the shellbar component.
Luigi.elements().getShellbar();
Returns HTMLElement the shellbar DOM element
Meta
- since: 0.4.12
Returns the shellbar actions component.
Luigi.elements().getShellbarActions();
Returns HTMLElement the shellbar actions DOM element
Meta
- since: 0.4.12
Returns a list of all available micro frontends.
Luigi.elements().getMicrofrontends();
Returns Array<{id: string, active: boolean, container: HTMLElement, type: ("main"
| "split-view"
| "modal"
)}> list of objects defining all micro frontends from the DOM
Meta
- since: 0.6.2
Returns all micro frontend iframes including the iframe from the modal if it exists.
Luigi.elements().getMicrofrontendIframes();
Returns Array<HTMLElement> an array of all micro frontend iframes from the DOM
Meta
- since: 0.4.12
Returns the active micro frontend iframe. If there is a modal, which includes the micro frontend iframe, the function returns this iframe.
Luigi.elements().getCurrentMicrofrontendIframe();
Returns HTMLElement the active micro frontend iframe DOM element
Meta
- since: 0.4.12
Authorization helpers
Detects if authorization is enabled via configuration. Read more about custom authorization providers.
Luigi.auth().isAuthorizationEnabled();
Returns boolean true
if authorization is enabled. Otherwise returns false
.
Login the user dynamically. This will run the same functionality as though the user clicked the login button.
Luigi.auth().login();
Meta
- since: 1.5.0
Logout the user dynamically. This will run the same functionality as though the user clicked the logout button.
Luigi.auth().logout();
Meta
- since: 1.5.0
Authorization Storage helpers, to be used in your custom authorization provider. Read more about custom authorization providers here.
Retrieves the key name that is used to store the auth data.
Luigi.auth().store.getStorageKey()
Returns string name of the store key
Retrieves the storage type that is used to store the auth data. To set it, use the storage
property of the auth
Luigi configuration object. Find out more here.
Luigi.auth().store.getStorageType()
Returns ("localStorage"
| "sessionStorage"
| "none"
) storage type
Retrieves the current auth object.
Luigi.auth().store.getAuthData()
Returns AuthData the current auth data object
Sets authorization data
data
AuthData new auth data object
Luigi.auth().store.setAuthData(data)
Clears authorization data from store
Luigi.auth().store.removeAuthData()
Defines a new authorization session. Must be triggered after initial setAuthData()
in order to trigger onAuthSuccessful event after login.
Luigi.auth().store.setNewlyAuthorized()
Authorization object that is stored in auth store and used within Luigi. It is then available in LuigiClient.addInitListener and can also be used in the Core configuration.
Type: Object
accessToken
string access token valueaccessTokenExpirationDate
string timestamp valuescope
string scope, can be empty if it is not requiredidToken
string id token, used for renewing authentication
Use these functions for navigation-related features.
Refreshes top navigation badge counters by rendering the navigation again.
Luigi.navigation().updateTopNavigation();
Navigates to the given path in the application. 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.
path
string path to be navigated topreserveView
boolean preserve a view by setting it totrue
. It keeps the current view opened in the background and opens the new route in a new frame. Use the 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() function instead of goBack()modalSettings
Object opens a view in a modal. Use these settings to configure the modal's title and sizemodalSettings.title
string modal title. By default, it is the node label. If there is no label, it is left emptymodalSettings.size
("l"
|"m"
|"s"
) size of the modal (optional, default"l"
)
splitViewSettings
Object opens a view in a split view. Use these settings to configure the split view's behavioursplitViewSettings.title
string split view title. By default, it is the node label. If there is no label, it is left emptysplitViewSettings.size
number height of the split view in percent (optional, default40
)splitViewSettings.collapsed
boolean opens split view in collapsed state (optional, defaultfalse
)
drawerSettings
Object opens a view in a drawer. Use these settings to configure if the drawer has a header, backdrop and size.drawerSettings.header
any By default, the header is visible. The default title is the node label, but the header could also be an object with atitle
attribute allowing you to specify your own title. An 'x' icon is displayed to close the drawer view.drawerSettings.backdrop
boolean By default, it is set tofalse
. If it is set totrue
the rest of the screen has a backdrop.drawerSettings.size
("l"
|"m"
|"s"
|"xs"
) size of the drawer (optional, default"s"
)
Luigi.navigation().navigate('/overview')
Luigi.navigation().navigate('users/groups/stakeholders')
Luigi.navigation().navigate('/settings', null, true) // preserve view
Opens a view in a modal. You can specify the modal's title and size. If you do not specify the title, it is the node label. If there is no node label, the title remains empty. The default size of the modal is l
, which means 80%. You can also use m
(60%) and s
(40%) to set the modal size. Optionally, use it in combination with any of the navigation functions.
path
string navigation pathmodalSettings
Object? opens a view in a modal. Use these settings to configure the modal's title and sizemodalSettings.title
string modal title. By default, it is the node label. If there is no label, it is left emptymodalSettings.size
("l"
|"m"
|"s"
) size of the modal (optional, default"l"
)
Luigi.navigation().openAsModal('projects/pr1/users', {title:'Users', size:'m'});
- See: SplitView Client for further documentation. These methods from the Client SplitView are also implemented for Luigi Core:
close
,collapse
,expand
,isCollapsed
,isExpanded
,exists
Opens a view in a split view. You can specify the split view's title and size. If you don't specify the title, it is the node label. If there is no node label, the title remains empty. The default size of the split view is 40, which means 40% height of the split view.
path
string navigation pathsplitViewSettings
Object opens a view in a split view. Use these settings to configure the split view's behaviour (optional, default{}
)splitViewSettings.title
string split view title. By default, it is the node label. If there is no label, it is left emptysplitViewSettings.size
number height of the split view in percent (optional, default40
)splitViewSettings.collapsed
boolean opens split view in collapsed state (optional, defaultfalse
)
Luigi.navigation().openAsSplitView('projects/pr1/users', {title:'Users', size:'40'});
Returns Object an instance of the SplitView. It provides functions to control its behavior.
Meta
- since: 0.7.6
Opens a view in a drawer. You can specify if the drawer has a header, if a backdrop is active in the background and configure the size of the drawer. By default the header is shown. The backdrop is not visible and has to be activated. The size of the drawer is by default set to s
which means 25% of the micro frontend size. You can also use l
(75%), m
(50%) or xs
(15.5%). Optionally, use it in combination with any of the navigation functions.
path
string navigation pathdrawerSettings
Object? opens a view in a drawer. Use these settings to configure if the drawer has a header, backdrop and size.drawerSettings.header
any By default, the header is visible. Title is node label and 'x' is displayed to close the drawer view. The header could also be an object with atitle
attribute to specify an own title for the drawer component.drawerSettings.backdrop
boolean By default, it is set tofalse
. If it is set totrue
the rest of the screen has a backdrop.drawerSettings.size
("l"
|"m"
|"s"
|"xs"
) size of the drawer (optional, default"s"
)
Luigi.navigation().openAsDrawer('projects/pr1/drawer', {header:true, backdrop:true, size:'s'});
Luigi.navigation().openAsDrawer('projects/pr1/drawer', {header:{title:'My drawer component'}, backdrop:true, size:'xs'});
Meta
- since: 1.6.0
Sets the current navigation context to that of a specific parent node which has the navigationContext field declared in the navigation configuration. This navigation context is then used by the navigate
function.
navigationContext
string
Luigi.navigation().fromContext('project').navigate('/settings')
Returns linkManager link manager instance
Sets the current navigation context which is then used by the navigate
function. This has to be a parent navigation context, it is not possible to use the child navigation contexts.
Luigi.navigation().fromClosestContext().navigate('/users/groups/stakeholders')
Returns linkManager link manager instance
Sets the current navigation base to the parent node that is defined as virtualTree. This method works only when the currently active micro frontend is inside a virtualTree.
Luigi.navigation().fromVirtualTreeRoot().navigate('/users/groups/stakeholders')
Returns linkManager link manager instance
Meta
- since: 1.0.1
Sends node parameters to the route. The parameters are used by the navigate
function. Use it optionally in combination with any of the navigation functions and receive it as part of the context object in Luigi Client.
nodeParams
Object
Luigi.navigation().withParams({foo: "bar"}).navigate("path")
// Can be chained with context setting functions such as:
Luigi.navigation().fromContext("currentTeam").withParams({foo: "bar"}).navigate("path")
Returns linkManager link manager instance
Checks if the path you can navigate to exists in the main application. For example, you can use this helper method conditionally to display a DOM element like a button.
path
string path which existence you want to check
let pathExists;
Luigi
.navigation()
.pathExists('projects/pr2')
.then(
(pathExists) => { }
);
Returns promise a promise which resolves to a Boolean variable specifying whether the path exists or not
Checks if there is one or more preserved views. You can use it to show a back button.
Returns boolean indicating if there is a preserved view you can return to
Discards the active view and navigates back to the last visited view. Works with preserved views, and also acts as the substitute of the browser back button. goBackContext is only available when using preserved views.
goBackValue
any data that is passed in the goBackContext field to the last visited view when using preserved views
Luigi.navigation().goBack({ foo: 'bar' });
Luigi.navigation().goBack(true);
Localization-related functions.
Gets the current locale.
Returns string current locale
Meta
- since: 0.5.3
Sets current locale to the specified one.
locale
string locale to be set as the current locale
Meta
- since: 0.5.3
Registers a listener for locale changes.
listener
Function function called on every locale change with the new locale as argument
Returns number listener ID associated with the given listener; use it when removing the listener
Meta
- since: 0.5.3
Unregisters a listener for locale changes.
listenerId
number listener ID associated with the listener to be removed, returned by addCurrentLocaleChangeListener
Meta
- since: 0.5.3
Gets translated text for the specified key in the current locale or in the specified one. Property values for token replacement in the localization key will be taken from the specified interpolations object.
TIP: Be aware that this function is not asynchronous and therefore the translation table must be existing already at initialization. Take a look at our i18n section for an implementation suggestion.
key
string key to be translatedinterpolations
Object objects with properties that will be used for token replacements in the localization key (optional, defaultundefined
)locale
locale optional locale to get the translation for; default is the current locale (optional, defaultundefined
)
Meta
- since: 0.5.3
Functions related to custom messages.
Sends a custom message to all opened micro frontends.
message
Object an object containing data to be sent to the micro frontend to process it further. This object is set as an input parameter of the custom message listener on the micro frontend side.message.id
string the id of the messagemessage.MY_DATA_FIELD
any any other message data field
Luigi.customMessages().sendToAll({
id: 'myprefix.my-custom-message-for-client',
dataField1: 'here goes some data',
moreData: 'here goes some more'
});
Meta
- since: 0.6.2
Sends a message to specific micro frontend identified with an id. Use Luigi.elements().getMicrofrontends() to get the iframe id.
microfrontendId
number the id of the micro frontendmessage
Object an object containing data to be sent to the micro frontend to process it further. This object is set as an input parameter of the custom message listener on the micro frontend sidemessage.id
number the id of the messagemessage.MY_DATA_FIELD
any any other message data field
Luigi.customMessages().send(microfrontend.id, {
id: 'myprefix.my-custom-message-for-client',
dataField1: 'here goes some data',
moreData: 'here goes some more'
});
Meta
- since: 0.6.2
Functions to use Luigi Core UX features.
Hides the app loading indicator.
Meta
- since: 0.6.4
Shows an alert.
settings
Object the settings for the alertsettings.text
string the content of the alert. To add a link to the content, you have to set up the link in thelinks
object. The key(s) in thelinks
object must be used in the text to reference the links, wrapped in curly brackets with no spaces. If you do not specify any text, the alert is not displayedsettings.type
("info"
|"success"
|"warning"
|"error"
) sets the type of alertsettings.links
Object provides links datasettings.links.LINK_KEY
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 parametersettings.links.LINK_KEY.text
string text which replaces the link identifier in the alert contentsettings.links.LINK_KEY.url
string url to navigate when you click the link. Currently, only internal links are supported in the form of relative or absolute pathssettings.links.LINK_KEY.dismissKey
string dismissKey which represents the key of the link.
settings.closeAfter
number (optional) time in milliseconds that tells Luigi when to close the Alert automatically. If not provided, the Alert will stay on until closed manually. It has to be greater than100
const settings = {
text: "Ut enim ad minim veniam, {goToHome} quis nostrud exercitation ullamco {relativePath}. Duis aute irure dolor {goToOtherProject}",
type: 'info',
links: {
goToHome: { text: 'homepage', url: '/overview' },
goToOtherProject: { text: 'other project', url: '/projects/pr2' },
relativePath: { text: 'relative hide side nav', url: 'hideSideNav' }
neverShowItAgain: { text: 'Never show it again', dismissKey: 'neverShowItAgain' }
},
closeAfter: 3000
}
Luigi
.ux()
.showAlert(settings)
.then(() => {
// Logic to execute when the alert is dismissed
});
Returns promise which is resolved when the alert is dismissed
Meta
- since: 0.6.4
NOTE: You can also define a customAlertHandler function to implement custom alerts.
Shows a confirmation modal.
settings
Object the settings of the confirmation modal. If you do not provide any value for any of the fields, a default value is usedsettings.type
("confirmation"
|"success"
|"warning"
|"error"
|"information"
) the content of the modal type. (Optional)settings.header
string the content of the modal header (optional, default"Confirmation"
)settings.body
string the content of the modal body. It supports HTML formatting elements such as<br>
,<b>
,<strong>
,<i>
,<em>
,<mark>
,<small>
,<del>
,<ins>
,<sub>
,<sup>
. (optional, default"Are you sure you want to do this?"
)settings.buttonConfirm
(string |false
) the label for the modal confirmation button. If set tofalse
, the button will not be shown. (optional, default"Yes"
)settings.buttonDismiss
string the label for the modal dismiss button (optional, default"No"
)
const settings = {
header: "Confirmation",
body: "Are you sure you want to do this?",
buttonConfirm: "Yes",
buttonDismiss: "No"
}
Luigi
.ux()
.showConfirmationModal(settings)
.then(() => {
// Logic to execute when the confirmation modal is dismissed
});
Returns promise which is resolved when accepting the confirmation modal and rejected when dismissing it
Meta
- since: 0.6.4
Set the document title
documentTitle
string
Luigi.ux().setDocumentTitle('Luigi');
Meta
- since: 1.4.0
Get the document title
Luigi.ux().getDocumentTitle();
Returns any a string, which is displayed in the tab.
Meta
- since: 1.4.0
Set the collapsed state of the left side navigation
state
boolean
Meta
- since: 1.5.0
Open user settings dialog
Meta
- since: 1.7.1
Close user settings dialog
Meta
- since: 1.7.1
Functions to use Luigi Global Search
Opens the global search field.
Luigi.globalSearch().openSearchField();
Meta
- since: 1.3.0
Closes the global search field.
Luigi.globalSearch().closeSearchField();
Meta
- since: 1.3.0
Clears the global search field.
Luigi.globalSearch().clearSearchField();
Meta
- since: 1.3.0
Opens the global search result. By standard it is a popover.
searchResultItems
Array
let searchResultItem = {
pathObject: {
link,
params: {}
},
label,
description
}
Luigi.globalSearch().showSearchResult([searchResultItem1, searchResultItem2]);
Meta
- since: 1.3.0
Closes the global search result. By standard it is rendered as a popover.
Luigi.globalSearch().closeSearchResult();
Meta
- since: 1.3.0
Gets the value of the search input field.
Luigi.globalSearch().getSearchString();
Meta
- since: 1.3.0
Sets the value of the search input field.
searchString
search value
Luigi.globalSearch().setSearchString('searchString');
Meta
- since: 1.3.0
Sets the value of the Placeholder search input field.
searchString
search value
Luigi.globalSearch().setSearchInputPlaceholder('HERE input Placeholder');
Meta
- since: 1.7.1
Functions to use Luigi Core Theming features.
Retrieves the available themes
Luigi
.theming()
.getAvailableThemes()
.then((themes) => {
// Logic to generate theme selector
});
Returns promise resolves an array of theming objects
Meta
- since: 1.4.0
Sets the current theme id
id
string of a theme object
Luigi.theming().setCurrentTheme('light')
Meta
- since: 1.4.0
Retrieves a theme object by name.
id
string a theme id
Luigi
.theming()
.getThemeObject('light')
.then((id => {
// Logic
}))
Returns promise resolves a theme object
Meta
- since: 1.4.0
Retrieves the current active theme. Falls back to defaultTheme if none explicitly specified before.
Luigi.theming().getCurrentTheme()
Returns string theme id
Meta
- since: 1.4.0
The general status about the Theming configuration.
Luigi.theming().isThemingAvailable()
Returns boolean true
if settings.theming configuration object is defined
Meta
- since: 1.4.0
Functions to use feature toggles in Luigi
Add a feature toggle to an active feature toggles list
featureToggleName
Luigi.featureToggles().setFeatureToggle('featureToggleName');
Meta
- since: 1.4.0
Remove a feature toggle from the list
featureToggleName
Luigi.featureToggles().unsetFeatureToggle('featureToggleName');
Meta
- since: 1.4.0
Get a list of active feature toggles
Luigi.featureToggles().getActiveFeatureToggleList();
Returns Array of active feature toggles
Meta
- since: 1.4.0
Get search parameter from URL as an object.
Luigi.routing().getSearchParams();
Returns Object
Meta
- since: 1.16.1
Add search parameters to the URL. If hash routing is enabled, the search parameters will be set after the hash. In order to delete a search query param you can set the value of the param to undefined.
params
Object
Luigi.routing().addSearchParams({luigi:'rocks', mario:undefined});
Meta
- since: 1.16.1