@openmfp/portal-ui-lib 0.189.5 → 0.190.0

package/README.md

@@ -22,22 +22,9 @@ The main features of this library are:
     - [Angular Configuration](#angular-configuration)
   - [Import the Portal providers and Bootstrap the app with PortalComponent](#import-the-portal-providers-and-bootstrap-the-app-with-portalcomponent)
   - [Update index html file of the project](#update-index-html-file-of-the-project)
-  - [Implement the Custom Service](#implement-the-custom-service)
-    - [Configuration services](#configuration-services)
-      - [The staticSettingsConfigService Option](#the-staticsettingsconfigservice-option)
-      - [The luigiExtendedGlobalContextConfigService Option](#the-luigiextendedglobalcontextconfigservice-option)
-      - [The userSettingsConfigService Option](#the-usersettingsconfigservice-option)
-      - [The globalSearchConfigService option](#the-globalsearchconfigservice-option)
-      - [The luigiBreadcrumbConfigService Option](#the-headerBarConfigService-option)
-      - [The userProfileConfigService Option](#the-userprofileconfigservice-option)
-    - [Functional Services](#functional-services)
-      - [The luigiAuthEventsCallbacksService Option](#the-luigiautheventscallbacksservice-option)
-      - [The customMessageListeners Option](#the-custommessagelisteners-option)
-      - [The customGlobalNodesService Option](#the-customglobalnodesservice-option)
-      - [The navigationRedirectStrategy Option](#the-navigationredirectstrategy-option)
-    - [Listen and react to Authentication Events](#listen-and-react-to-authentication-events)
-    - [Configure Proxy for Backend REST Calls](#configure-proxy-for-backend-rest-calls)
-    - [Start your Project](#start-your-project)
+  - [Implement the Custom Services](#implement-the-custom-services)
+  - [Configure Proxy for Backend REST Calls](#configure-proxy-for-backend-rest-calls)
+  - [Start your Project](#start-your-project)
   - [Local Extension Development](#local-extension-development)
   - [Requirements](#requirements)
   - [Contributing](#contributing)
@@ -143,571 +130,13 @@ Below is an example:
 ```
 
 
+### Implement the Custom Services
 
-## Implement the Custom Service
+The library comes with a set of services that can be used to customize the portal behavior.
+Please visit the [Frontend configuration - Extended Guide](https://openmfp.org/documentation/extended-guide/frontend-configuration/)
+to get familiar with the configuration options and how to use them.
 
 
-There are two types of services that are considered: Services that provide Luigi configuration (aka. Configuration Services) and services that provide or extend functionality (aka. Functional Services).
-For each service there is a corresponding interface that you have to implement.
-Afterward you provide your specific implementation in the `providePortal(portalOptions)` by placing it in the `portalOptions` object and thus make it available to the `Portal`.
-
-### Configuration services
-
-#### The staticSettingsConfigService Option
-
-With this you can customize [Luigis general settings](https://docs.luigi-project.io/docs/general-settings) and override any defaults.
-Make sure to return a valid Luigi configuration object.
-
-```ts
-import { StaticSettingsConfigService } from '@openmfp/portal-ui-lib';
-
-export class StaticSettingsConfigServiceImpl
-        implements StaticSettingsConfigService
-{
-  constructor() {}
-
-  getStaticSettingsConfig() {
-    const logo = 'assets/my-logo.svg';
-
-    return {
-      header: {
-        title: 'My App',
-        logo: logo,
-        favicon: logo,
-      },
-      appLoadingIndicator: {
-        hideAutomatically: false,
-      },
-      links: [{ title: 'OpemMFP', link: 'https://openmfp.org/' }],
-      // ... the rest of the configuration 
-    };
-  }
-}
-```
-
-The `getStaticSettingsConfig()` is called while [Luigi lifecycle hook luigiAfterInit](https://docs.luigi-project.io/docs/lifecycle-hooks?section=luigiafterinit).
-The latter adds additional setup to the root of the Luigi configuration object.
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  staticSettingsConfigService: StaticSettingsConfigServiceImpl,
-  // ... other portal options
-}
-```
-
-#### The routingConfigService Option
-
-With this you can customize [Luigis routing settings](https://docs.luigi-project.io/docs/navigation-parameters-reference?section=routing-parameters) and override any defaults.
-Make sure to return a valid Luigi configuration object.
-
-```ts
-import { Injectable, inject } from '@angular/core';
-import { RoutingConfigService } from '@openmfp/portal-ui-lib';
-
-@Injectable()
-export class CustomRoutingConfigServiceImpl implements RoutingConfigService {
-getInitialRoutingConfig(): any {
-    return {
-      useHashRouting: false,
-      showModalPathInUrl: false,
-      modalPathParam: 'modalPathParamDisabled',
-      skipRoutingForUrlPatterns: [/.*/],
-      pageNotFoundHandler: () => {},
-    };
-  }
-
-  getRoutingConfig(): any {
-    return {
-      useHashRouting: false,
-      showModalPathInUrl: true,
-      modalPathParam: 'modal',
-      pageNotFoundHandler: (
-        notFoundPath: string,
-        isAnyPathMatched: boolean,
-      ) => {
-        return {
-          redirectTo: 'error/404',
-          keepURL: true,
-        };
-      },
-    };
-  }
-}
-```
-
-The `getInitialRoutingConfig()` method is called while constructing the Luigi initial config object.
-The `getRoutingConfig()` is called while [Luigi lifecycle hook luigiAfterInit](https://docs.luigi-project.io/docs/lifecycle-hooks?section=luigiafterinit).
-The latter adds additional setup to the root of the Luigi configuration object.
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-   routingConfigService: CustomRoutingConfigService,
-  // ... other portal options
-}
-```
-
-#### The errorComponentConfig Option
-
-With this option you can configure custom error handling when entity error occurs.
-By default, the library shows an alert with the error message.
-
-```ts
-import { ErrorComponentConfig, EntityDefinition, LuigiNode } from '@openmfp/portal-ui-lib';
-
-const errorComponentConfig: ErrorComponentConfig = {
-  handleEntityRetrievalError: (
-    entityDefinition: EntityDefinition,
-    errorCode: number,
-    additionalContext?: Record<string, string>,
-  ): LuigiNode[] => {
-    if (errorCode === 404) {
-      return [
-        {
-          pathSegment: 'not-found',
-          label: 'Not Found',
-          viewUrl: '/assets/not-found.html',
-        },
-      ];
-    }
-
-    return [
-      {
-        pathSegment: 'error',
-        label: 'Error',
-        viewUrl: `/assets/error.html?code=${errorCode}`,
-      },
-    ];
-  },
-};
-```
-The `handleEntityRetrievalError()` method is called when entity configuration retrieval fails. It receives the entity definition, HTTP error code, and optional additional context. Return an array of Luigi nodes to display instead of failed content.
-
-In your `main.ts` you can provide your configuration like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  errorComponentConfig: errorComponentConfig,
-  // ... other portal options
-}
-```
-
-#### The luigiExtendedGlobalContextConfigService Option
-
-By default, in the [Luigi's global context](https://docs.luigi-project.io/docs/navigation-parameters-reference?section=globalcontext) following data is set by the library and available:
-
-```json
-{
-  "portalContext": {...} ,
-  "portalBaseUrl": "portal base url",
-  "userId": "logged in user id",
-  "userEmail": "logged in user email",
-  "token": "id token of the logged in user"
-}
-```
-
-With the `luigiExtendedGlobalContextConfigService` option you can define global data you want to be available alongside with the default values present.
-The Luigi's global context is available afterwards in all the micro-frontends.
-
-```ts
-import { LuigiExtendedGlobalContextConfigService, LuigiNode } from '@openmfp/portal-ui-lib';
-
-export class LuigiExtendedGlobalContextConfigServiceImpl implements LuigiExtendedGlobalContextConfigService {
-
-  async createLuigiExtendedGlobalContext(): Promise<ExtendedGlobalContext> {
-
-    return {
-      isLocal: true,
-      analyticsConfig: 'global',
-    };
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  luigiExtendedGlobalContextConfigService: LuigiExtendedGlobalContextConfigServiceImpl,
-  // ... other portal options
-}
-```
-
-
-#### The userSettingsConfigService Option
-
-With this you can define the [Luigi user settings and a corresponding userSettingGroups configuration](https://docs.luigi-project.io/docs/user-settings?section=user-settings)
-Make sure to return a valid Luigi configuration object.
-
-```ts
-import { UserSettingsConfigService, LuigiNode } from '@openmfp/portal-ui-lib';
-
-export class UserSettingsConfigServiceImpl implements UserSettingsConfigService {
-
-  async getUserSettings(childrenByEntity: Record<string, LuigiNode[]>) {
-    return {
-      userSettingsDialog: {
-        dialogHeader: 'User Settings',
-      },
-      userSettingGroups: {
-        // ...the rest of the configuration  
-      }
-      // ...the rest of the configuration  
-    }
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  userSettingsConfigService: UserSettingsConfigServiceImpl,
-  // ... other portal options
-}
-```
-
-#### The globalSearchConfigService option
-
-With this you have the possibility configure [Luigis global search element](https://docs.luigi-project.io/docs/global-search) with provided configuration and events handlers.
-Make sure to return a valid Luigi configuration object.
-
-```ts
-import { GlobalSearchConfigService} from '@openmfp/portal-ui-lib';
-
-export class GlobalSearchConfigServiceImpl implements GlobalSearchConfigService {
-
-  getGlobalSearchConfig() {
-    return {
-      searchFieldCentered: true,
-      searchProvider: {
-        onEnter: () => {
-          // ... handler implementation
-        },
-        onSearchBtnClick: () => {
-          // ... handler implementation
-        },
-        onEscape: () => {
-          // ... handler implementation
-        },
-
-        // ...the rest of the configuration
-      },
-      // ...the rest of the configuration
-    };
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  globalSearchConfigService: GlobalSearchConfigServiceImpl,
-  // ... other portal options
-}
-```
-
-#### The headerBarConfigService Option
-
-This enables you to define configiration for your header bar section. Under the hood It extends [Luigi breadcrumbs](https://docs.luigi-project.io/docs/navigation-advanced?section=breadcrumbs) by adding ability to provide multiple renderer functions
-
-Make sure to return a valid HeaderBar configuration object.
-
-
-```ts
-import {
-  HeaderBarConfigService,
-  HeaderBarConfig,
-} from '@openmfp/portal-ui-lib';
-
-
-export class HeaderBarConfigServiceImpl implements HeaderBarConfigService
-{
-  getBreadcrumbsConfig(): Promise<HeaderBarConfig> {
-    return  {
-      autoHide: true,
-      omitRoot: false,
-      pendingItemLabel: '...',
-      rightRenderers: [(
-              containerElement: HTMLElement,
-              nodeItems: NodeItem[],
-              clickHandler,
-      ) => {
-        // ... renderer implementation
-      }];
-      leftRenderers: [(
-              containerElement: HTMLElement,
-              nodeItems: NodeItem[],
-              clickHandler,
-      ) => {
-        // ... renderer implementation
-      }];
-    };
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  headerBarConfigService: HeaderBarConfigServiceImpl,
-  // ... other portal options
-}
-```
-
-#### The userProfileConfigService Option
-
-This option allows you to define the [Luigi user profile](https://docs.luigi-project.io/docs/navigation-advanced?section=profile).
-Make sure to return a valid Luigi configuration object.
-
-```ts
-import { UserProfileConfigService, UserProfile } from '@openmfp/portal-ui-lib';
-
-
-export class UserProfileConfigServiceImpl implements UserProfileConfigService
-{
-  async getProfile(): Promise<UserProfile> {
-    return {
-      logout: {
-        label: 'Sign out',
-        icon: 'log',
-      },
-      items: [
-        {
-          label: 'Overview',
-          icon: 'overview',
-          link: `/users/overview`,
-        },
-      ],
-    };
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  userProfileConfigService: UserProfileConfigServiceImpl,
-  // ... other portal options
-}
-```
-
-### Functional Services
-
-#### The luigiAuthEventsCallbacksService Option
-
-This option allows you to provide a service that listens to [Luigi authorization events](https://docs.luigi-project.io/docs/authorization-events)
-Make sure to return a valid Luigi configuration object.
-
-```ts
-import { LuigiAuthEventsCallbacksService } from '@openmfp/portal-ui-lib';
-
-export class LuigiAuthEventsCallbacksServiceImpl
-        implements LuigiAuthEventsCallbacksService {
-
-  onAuthSuccessful(settings: any, authData: any) {
-    concole.log('User succesfully authenticated.');
-  }
-
-  // ...
-
-  onLogout(settings: any) {
-    concole.log('User succesfully logged out.');
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-
-const portalOptions: PortalOptions = {
-  luigiAuthEventsCallbacksService: LuigiAuthEventsCallbacksServiceImpl,
-  // ... other portal options
-}
-```
-
-#### The customMessageListeners Option
-
-With this option it is possible to define listeners for [Luigi custom messages](https://docs.luigi-project.io/docs/communication?section=custom-messages).
-
-Custom messages are sent from any part of your application to Luigi and then routed to any other micro frontend application in the same application.
-A custom message is sent by using Luigi `sendCustomMessage({ id: 'unique.message.id'});` method (see also the following example).
-
-```ts
-import { inject, Injectable } from '@angular/core';
-import { LuigiCoreService } from '@openmfp/portal-ui-lib';
-
-@Injectable({ providedIn: 'root' })
-export class MessageService {
-  private luigiCoreService: LuigiCoreService = inject(LuigiCoreService);
-
-  public sendMessage() {
-    this.luigiCoreService.sendCustomMessage({ id: 'unique.message.id' });
-  }
-}
-```
-
-To react on such a message in your micro frontend, you have to provide a custom message listener.
-You have to specify the corresponding message id you want to listen to.
-If there is a match, the callback function `onCustomMessageReceived()` will be called.
-Make sure to return a valid Luigi configuration object.
-
-```ts
-import { CustomMessageListener } from '@openmfp/portal-ui-lib';
-
-export class CustomMessageListenerImpl
-        implements CustomMessageListener
-{
-  messageId(): string {
-    return `unique.message.id`;
-  }
-
-  onCustomMessageReceived(
-          customMessage: string,
-          mfObject: any,
-          mfNodesObject: any,
-  ): void {
-    // ... logic to be executed
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  customMessageListeners: [CustomMessageListenerImpl, CustomMessageListenerImpl2, ...],
-  // ... other portal options
-}
-```
-
-#### The customGlobalNodesService Option
-
-This option adds the possibility to define and add the global level Luigi nodes to your application.
-
-```ts
-import { LuigiNode, CustomGlobalNodesService } from '@openmfp/portal-ui-lib';
-
-export class CustomGlobalNodesServiceImpl implements CustomGlobalNodesService {
-
-  async getCustomGlobalNodes(): Promise<LuigiNode[]> {
-    return [
-      this.createGlobalNode1(),
-      this.createGlobalNode2(),
-      // ...other globaL nodes
-    ];
-  }
-
-  private async createGlobalNode1(): LuigiNode {
-    return {
-      label: 'Global 1',
-      entityType: 'global',
-      link: '/global_1',
-      // ... other luigi node properties
-    };
-  }
-
-  private createGlobalNode2(): LuigiNode {
-    return {
-      label: 'Global 2',
-      entityType: 'global.topnav',
-      viewUrl: '/global_2',
-      pathSegment: 'global_2',
-      // ... other luigi node properties
-    };
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  customGlobalNodesService: CustomGlobalNodesServiceImpl,
-  // ... other portal options
-}
-```
-
-#### The navigationRedirectStrategy Option
-
-This option allows you to customize where and how the portal stores the URL to redirect the user to after login (for example after session expiry or logout). By default the library uses `localStorage`. You can provide your own implementation of `NavigationRedirectStrategy` to use session storage, a backend, or custom logic.
-
-```ts
-import { Injectable } from '@angular/core';
-import { NavigationRedirectStrategy } from '@openmfp/portal-ui-lib';
-
-@Injectable()
-export class CustomNavigationRedirectStrategy implements NavigationRedirectStrategy {
-  getRedirectUrl(): string {
-    return sessionStorage.getItem('returnUrl') || '/';
-  }
-
-  saveRedirectUrl(url: string): void {
-    sessionStorage.setItem('returnUrl', url);
-  }
-
-  clearRedirectUrl(): void {
-    sessionStorage.removeItem('returnUrl');
-  }
-}
-```
-
-In your `main.ts` you can provide your custom implementation like so:
-
-```ts
-const portalOptions: PortalOptions = {
-  navigationRedirectStrategy: CustomNavigationRedirectStrategy,
-  // ... other portal options
-}
-```
-
-### Listen and react to Authentication Events
-
-There are following Authentication Events, to which the library consuming application can subscribe and react upon, in case required.
-
-```ts
-export enum AuthEvent {
-  AUTH_SUCCESSFUL = 'AuthSuccessful',
-  AUTH_ERROR = 'AuthError',
-  AUTH_EXPIRED = 'AuthExpired',
-  AUTH_REFRESHED = 'AuthRefreshed',
-  AUTH_EXPIRE_SOON = 'AuthExpireSoon',
-  AUTH_CONFIG_ERROR = 'AuthConfigError',
-  LOGOUT = 'Logout',
-}
-```
-Below is an example of reacting to `AuthEvent.AUTH_SUCCESSFUL` 
-
-```ts
-import { AuthEvent, AuthService } from '@openmfp/portal-ui-lib';
-import { filter } from 'rxjs';
-import { MyService } from '../services';
-
-export function actWhenUserAuthSuccedsful(
-    myService: MyService,
-    authService: AuthService,
-): () => void {
-  return () => {
-    authService.authEvents
-      .pipe(
-        filter((event: AuthEvent) => event === AuthEvent.AUTH_SUCCESSFUL),
-      )
-      .subscribe({
-        next: (event: AuthEvent) => {
-          myService.act();
-        },
-      });
-  };
-}
-```
-
 ### Configure Proxy for Backend REST Calls
 
 The library executes rest calls `"/rest/**"` against backend running with the library [portal-server-lib](https://github.com/openmfp/portal-server-lib?tab=readme-ov-file#portal-server-library).