Retalia Sidebar Navigation Module

To implement the sidebar navigation module into an Angular project, you will need to:

1. Run npm i @retalia/sidebar-navigation, the package can be found here: https://www.npmjs.com/package/@retalia/sidebar-navigation

2. import { NavigationLibModule } from '@retalia/sidebar-navigation'; in the app.module.ts and the imports of the NgModule.

3. import 'CUSTOM_ELEMENTS_SCHEMA'; into the app.module.ts if it isn't already there. schemas: [CUSTOM_ELEMENTS_SCHEMA],

4. Call the component's HTML tag in the app.component.html file, with your <router-outlet> in between the <sidebar-navigation> tags and pass in values from your UI's environment variables, this allows the navigation library to make module calls to the correct gateway. As each UI's environment variables are set-up differently, the sidebar expects the apiRequestUrl and the portalUrl from the env. For the portalUrl I'd suggest only setting it if in a production environment. This ensures that the sidebar will remain on localhost and not route you to the module via the portal.

this.sidebarEnvironment = {
portalUrl: env.portalUrl,
apiRequestUrl: `${env.apiRequestUrl}api/v${env.apiVersion}`
};

<sidebar-navigation  [environment]="sidebarEnvironment" (selectedRoute)="routeToItem($event)">
<router-outlet></router-outlet>
</sidebar-navigation>

You will also need a routeToItem handler in the consuming app. The sidebar emits (selectedRoute) when the user is already inside the current module (same pathname prefix as the module url). Otherwise it performs a full navigation with window.location.href using the gateway URL.

selectedRoute payload

The emitted item is a copy of the clicked sidebar entry plus routing helpers:

| Field | Description | |--------|-------------| | url | Route segment(s) joined with / (e.g. partners, reports/apps-by-tenant). Empty when the gateway URL contains #. Do not rely on this alone. | | appPath | Full gateway URL (e.g. /rbo/#/shops, /platform-admin/partners). Always set on emit. | | routeCommands | Path segments for Router.navigate(routeCommands) (e.g. ['reports', 'apps-by-tenant']). Empty when navigateByUrlOnly is true. | | navigateByUrlOnly | true when appPath contains # (hash / hashbang apps). Use hash-aware navigation (see below). |

Gateway sidebarEntries URLs should include the module prefix when deployed (e.g. /platform-admin/tenants, /rbo/#/shops). The library strips the module path into routeCommands where possible.

Recommended routeToItem implementation

Use routeCommands first, then hash appPath, then fall back to url / appPath. Avoid router.navigate([selectedItem.url]) when url is empty — that often navigates to the app's default route.

public routeToItem(selectedItem: {
  url: string;
  appPath?: string;
  navigateByUrlOnly?: boolean;
  routeCommands?: string[];
}): void {
  this.zone.run(() => {
    // Hash / hashbang modules (e.g. RBO: /rbo/#/shops)
    if (selectedItem.navigateByUrlOnly && selectedItem.appPath) {
      const hashIndex = selectedItem.appPath.indexOf('#');
      if (hashIndex >= 0) {
        // HashLocationStrategy: navigate using the hash segment(s)
        const hashPart = selectedItem.appPath.slice(hashIndex);
        const segments = hashPart.replace('#/', '').split('/').filter(Boolean);
        void this.router.navigate(segments);
        return;
      }
      void this.router.navigateByUrl(selectedItem.appPath);
      return;
    }

    // Path-based modules (e.g. Platform Admin: /platform-admin/partners)
    if (selectedItem.routeCommands?.length) {
      void this.router.navigate(selectedItem.routeCommands);
      return;
    }

    const raw = selectedItem.url || selectedItem.appPath || '';
    if (!raw) {
      return;
    }
    // Strip deploy prefix if routes are registered at app root (see your app base-href)
    let path = raw.replace(/^\/+/, '');
    if (path.startsWith('platform-admin/')) {
      path = path.slice('platform-admin/'.length);
    }
    void this.router.navigateByUrl('/' + path);
  });
}

Adjust prefix stripping and hash handling to match your app's RouterModule setup (base-href, HashLocationStrategy, etc.).

5. Optionally, you can include useCustomPage="true" which will remove the existing page-container and page-body wrappers which set margins and padding.

6. In your angular.json, you need to configure the input of the library's assets as so:

{ "glob": "**/*", "input": "./node_modules/@retalia/sidebar-navigation/lib/assets", "output": "/assets/" }

When passing in the environment variables, you can set the apiVersion to TEST in order to have a sidebar populated with mock data for immediate testing purposes.

Local Development

When adding new sidebar sidebarEntries/children, you will still need to configure the module UI's internal routing and components as normal, but also be sure to add the destination into your mock node server's data - this will allow you to see it on the sidebar and navigate to/from the new route.

Adding this new item to the module call will require a migration.

This project was generated with Angular CLI version 11.2.4.