@genesislcap/foundation-header

Foundation Header

API

Introduction

The Header micro front-end is a semi-batteries-included component. It consists of a navigation bar and flyout menu, with routing and account-logout capabilities.

Customise

You can customise:

• the icon shown on the navigation bar and flyout menu (this shows the Genesis logo by default)
• navigation links at the left-hand side of the navigation bar
• the control buttons on the right-hand side of the navigation bar; these can be shown or hidden, and their behaviour controlled via event listeners
• the contents of the flyout menu

Examples

Here is an example of the navigation bar with three navigation items, and all three control buttons shown.

This next example is the same as the previous example, except the Genesis logo is replaced with a custom icon.

In this next example, we have put a set of example options set in the flyout menu.

Header set-up

A lot of the Genesis seed apps come with the Header set up by default. To verify, you can do a text search in the client code for the <rapid-header> tag.

Icon

By default, the navigation bar and flyout menu show the Genesis logo. You can override this by setting the logoSrc attribute. For example:

<rapid-header logoSrc="https://icotar.com/avatar/genesis"></rapid-header>

The logoSrc defines the image that you want to display. Adding this attribute updates the logo on both the flyout and navigation bar. If you want to keep the Genesis logo, just omit this attribute.

Navigation items

You can add navigation items to the left-hand side of the navigation bar. For each element, you can set slot="routes" attribute, so that navigation is controlled via a @click event. The following is a really basic example for adding a 'Home' button:

html`
<rapid-header>
  <rapid-button
    slot="routes"
    value="1"
    @click=${(x, c) => c.parent.navigation.navigateTo("home")}
  >Home</rapid-button>
</rapid-header>`;

The navigation object referenced via the parent object is why the navigation object is added as an attribute to the router in the setup step. From it, the navigateTo method can be called, which allows the user to navigate around the finished application from the navigation buttons.

Moving on from this basic example, a dynamic set of routes can be configured, using the repeat directive from @genesislcap/web-core.

1. Add the routes configuration into an array in the router configuration class.

export class MainRouterConfig extends RouterConfiguration<LoginSettings> {

  // New configuration added to existing MainRouterConfig class
  public allRoutes = [
    { index: 1, path: 'protected', title: 'Home', icon: 'home', variant: 'solid' },
    { index: 2, path: 'admin', title: 'Admin', icon: 'cog', variant: 'solid' },
    { index: 3, path: 'reporting', title: 'Reporting', variant: 'solid' },
  ];

  ...
}

2. When setting the navigation items, use the repeat directive to iterate over the defined routes and create a navigation item for each one.

The following example creates a button with an associated logo for each of the three defined routes:

html`

${repeat( (x) => x.config.allRoutes, html` c.parent.navigation.navigateTo(x.path)} > ${(x) => x.title} ` )}

`; ```

Control buttons

There are three control buttons that can be shown or hidden on the right-hand side of the navigation bar (these are hidden by default). Each one of them is a boolean attribute that can be added where the <rapid-header> tag is defined.

Logo	Toggle Attribute	Dispatched Event
Moon	show-luminance-toggle-button	luminance-icon-clicked
Misc	show-misc-toggle-button	misc-icon-clicked
Notifications	show-notification-button	notification-icon-clicked

Implementing the functionality of the buttons is up to the client. For example:

• Define the functionality of the event callback in the class of a class which is a parent to the router.

export class MainApplication extends GenesisElement {

  onMiscButtonPressed() {
    // ... do something
  }
  //...
}

• Set the event listener in the parent html to call the defined functionality.

const MainTemplate: ViewTemplate<MainApplication> = html`
  <foundation-router
    :navigation=${(x) => x.navigation}
    @misc-icon-clicked=${(x) => x.onMiscButtonPressed()}
  >
  </foundation-router>
`;

Language Selector

The rapid-header component can display a language selector if the show-language-selector attribute is set. This allows users to switch between different languages within the application.

<rapid-header show-language-selector></rapid-header>

By default, the component uses the languageOptions object, which contains an availableLanguage array and a selectedLanguage property. These default options provide a list of available languages and the currently selected language.

You can also pass custom language options by providing an attribute with this data. Here is an example of how to set up the rapid-header component with the show-language-selector attribute and custom language options:

<rapid-header show-language-selector :languageOptions=${() => { return { availableLanguages: ['en', 'es'], selectedLanguage: 'es' }; }}

Menu contents

To set the content of the flyout menu, add the content in the html within an element that has the slot="menu-contents" attribute.

<rapid-header>
  <div slot="menu-contents">
    <!-- Example markup -->
    <p>GROUP SLOT</p>
    <rapid-tree-view>
      <rapid-tree-item>
        <rapid-icon name="location-arrow"></rapid-icon>
        Slot Tree Item
      </rapid-tree-item>
      <rapid-tree-item>
        <rapid-icon name="location-arrow"></rapid-icon>
        Slot Tree Item
      </rapid-tree-item>
    </rapid-tree-view>
    <p>GROUP SLOT 2</p>
    <rapid-tree-view>
      <rapid-tree-item>
        <rapid-icon name="location-arrow"></rapid-icon>
        Slot Tree Item 2
      </rapid-tree-item>
      <rapid-tree-item>
        <rapid-icon name="location-arrow"></rapid-icon>
        Slot Tree Item 2
      </rapid-tree-item>
    </rapid-tree-view>
  </div>
</rapid-header>

:::tip The allRoutes array, which you need to change to set the navigation buttons on the Header, is found in client/web/src/routes/config.ts. :::

Manual Header set-up

If the rapid-header component has not been implemented in your project, follow the steps below to add this micro front-end to your application.

1. Add @genesislcap/foundation-header as a dependency in your package.json file. Whenever you change the dependencies of your project, ensure you run the bootstrap command again. There is more information in the package.json basics page.

{
  ...
  "dependencies": {
    "@genesislcap/foundation-header": "latest"
  },
  ...
}

:::note This page assumes you're already using the Login and Routing systems that are part of foundation-ui for the logout and routing functionality.

It is possible for you to set up routing manually, but that won't be covered in this tutorial. :::

2. In the top-level class of your application, import the Navigation class and inject it as a dependency.

import { GenesisElement, customElement, inject } from '@genesislcap/web-core';
import { Navigation } from '@genesislcap/foundation-header';

@customElement({ name, template, styles })
export class MainApplication extends GenesisElement {
  @inject(MainRouterConfig) config!: MainRouterConfig;
  @inject(Navigation) navigation!: Navigation;

  //...

}

:::tip If you haven't used the inject annotation in your application yet, you'll need to get it from the @genesislcap/web-core package. :::

3. Set a reference to the navigation object on the foundation-router when you instantiate it; this enables you to set up navigation functionality from the navigation bar in the navigation items step.

const MainTemplate: ViewTemplate<MainApplication> = html`
  <foundation-router :navigation=${(x) => x.navigation}></foundation-router>
`;

4. Add the rapid-header tag as part of the html that you set as the markup for the defaultLayout in your router configuration.

export const defaultLayout = new GenesisElementLayout(html`
<div class="container">
  <!-- show-luminance-toggle-button boolean attribute added to show that button on the navigation bar -->
  <rapid-header show-luminance-toggle-button></rapid-header>
  <!-- Other markup -->
</div>`);

export class MainRouterConfig extends RouterConfiguration<LoginSettings> {
  //...

  public configure() {
    this.title = 'Example app';
    this.defaultLayout = defaultLayout;
    //...
  }
}

DOM API

Property and attribute binding examples for foundation-header micro-frontend.

Attributes

Attribute	Type	Use	Example
logo-src	any	Optional attribute which sets the source of the image in the navigation bar and flyout menu. The Genesis logo will be shown if this attribute is not provided.	<foundation-header logo-src="path/to/logo.png">
logo-alt-text	string	Optional attribute which controls the alt text of the logo. If this attribute is not set then the alt text is set to 'Corporate Logo'.	<foundation-header logo-alt-text="My Logo">
show-luminance-toggle-button	boolean	Boolean attribute which controls whether the navigation bar will display the luminance toggle icon.	<foundation-header show-luminance-toggle-button>
show-misc-toggle-button	boolean	Boolean attribute which controls whether the navigation bar will display the miscellaneous behaviour icon.	<foundation-header show-misc-toggle-button>
show-notification-button	boolean	Boolean attribute which controls whether the navigation bar will display the show notification icon.	<foundation-header show-notification-button>
show-connection-indicator	boolean	Boolean attribute which controls whether the navigation bar will display the connection indicator.	<foundation-header show-connection-indicator>
show-language-selector	boolean	Boolean attribute which controls whether the navigation bar will display the language selector.	<foundation-header show-language-selector>
hide-side-bar	boolean	Boolean attribute which controls whether the navigation bar will display the side bar.	<foundation-header hide-side-bar>

Properties

Property	Type	Use	Example
userName	string	Username of the logged in user.	<foundation-header ?userName="${(x) => x.userName}">
languageOptions	LanguageOptions	Object which defines the language options to be displayed in the language selector.	<foundation-header :languageOptions="${(x) => x.languageOptions}">
routeButtons	Array	Array of objects which define the route buttons to be displayed in the navigation bar.	<foundation-header :routeButtons="${(x) => x.routeButtons}">
routeNavItems	FoundationRouteNavItem[]	Array of FoundationRouteNavItems which define the route buttons to be displayed in the navigation bar.	<foundation-header :routeNavItems="${(x) => x.routeNavItems}">

Slots

Slot Name	Description
menu-contents	Slot for adding custom content to the flyout menu (side navigation).
routes	Slot for adding custom route buttons to the navigation bar.
routes-end	Slot for adding custom route buttons to the end of the navigation bar.

Parts

Part Name	Description
dynamic-template	The element representing the dynamic template content.

Methods

Method	Description
logout	Logs the user out of their session.
navigateTo	Changes the route of the current page.

Fired Events

Event	Type	Description	Example
luminance-icon-clicked	void	Dispatched when the user clicks on the luminance toggle icon in the navigation bar.	<foundation-header @luminance-icon-clicked="${(x) => x.handleLuminanceIconClick}">
misc-icon-clicked	void	Dispatched when the user clicks on the miscellaneous behaviour icon in the navigation bar.	<foundation-header @misc-icon-clicked="${(x) => x.handleMiscIconClick}">
notification-icon-clicked	void	Dispatched when the user clicks on the notification icon in the navigation bar.	<foundation-header @notification-icon-clicked="${(x) => x.handleNotificationIconClick}">
language-changed	void	Dispatched when the user changes the language in the language selector.	<foundation-header @language-changed="${(x) => x.handleLanguageChange}">

Listened Events

This component doesn't listen to any events.

License

Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact Genesis Global for more details.

Licensed components

Genesis low-code platform