Skip to content

CodeCoupler Costa Components Header & Sidebar 🔒

This component is ideal for use as a root application component. It creates a Flexbox-based layout with a sidebar and header. The layout is suitable for both PWA applications and applications that require authentication.

The following stages (id's and classnames) are provided:

Header & Sidebar Overview

Get Started

Here is an example of how this component could be loaded into the root stage and which properties of the Start Definition Object should be set:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
import { HeaderSidebar } from "@codecoupler/costa-header-sidebar"
import { ComponentInitError, Stage } from "@codecoupler/costa-core";

// Import your stylesheet including special styles for popovers, dropdowns and tooltips
import RootStyles from "./root.module.css";

// Import your background banner image and your logo
import logoIcon from "./images/logo-icon.png";
import logoBackground from "./images/logo-banner.png";

// Define your applications as a component registry configuration that will be used in the sidebar:
import Example from "./example-app";
let apps = {
  "example-app": {
    id: "example-app",
    component: Example
  }
};

// If you want to load a service worker you should use a ServiceWorkerLoader instance and handle 
// some specific cases:
import { ServiceWorkerLoader } from "@codecoupler-pro/app-service-worker";
import { Interceptors } from "@codecoupler/costa-core";
let swLoader = new ServiceWorkerLoader({
  serviceWorkerUrl: "/sw.js"
});
// Handle after update
let url = new URL(window.location);
if (url.hash === "#sw-update") {
  window.history.replaceState({}, document.title, "/");
}
// Handle after forced update
if (url.hash === "#sw-update-forced") {
  Interceptors.register("sw-update-forced", () => new Promise(() => true));
  if (auth) auth.loginReload();
}

// If you want to use PWA features use a PWA instance:
import { PWA } from "@codecoupler-pro/app-pwa";
let pwa = new PWA();

// If you want to use authentication define your authentication module:
import { AuthMockup } from "@codecoupler/auth-bundle";
auth = new AuthMockup();

let startRoot = () => {
  new Stage()
    .load({
      component: HeaderSidebar,
      options: {
        apps: apps,
        auth: auth,
        authStatusVue: {},
        pwa: pwa,
        pwaVue: {},
        swLoader: swLoader,
        swLoaderVue: {}
        launcher: {},
        logoIcon,
        logoBackground
      }
    })
    .then((rootComponent) => {
      console.info("Root Component Ready", rootComponent.id);
    })
    .catch((e) => {
      if (e instanceof ComponentInitError) {
        console.info("Error was thrown from component", e.component.id);
      }
      console.error(e);
    });
};

// Smart replacement for `window.addEventListener("load", callback)`
// See: https://stackoverflow.com/q/13364613 and https://stackoverflow.com/a/53525488
if (performance.getEntriesByType("navigation").every((e) => e.loadEventEnd))
  startRoot();
else window.addEventListener("load", startRoot);

Options

apps: Object

Applications registry of the root component and used by the sidebar. The @codecoupler/launcher component is loaded into the stage sidebar which will display n application start menu-

auth: AuthenticationModule and authStatusVue: Object

Define an authentication module in the option auth that applies to components loaded in the custom header and main stage.

If an authentication module is configured, the @codecoupler/auth-status-vue component is used to display a login/logout button and status information. You can find all the configuration options (Vue props) for this component here: Authentication Status Vue

All the configuration options described there can be set using the authStatusVue property, except for the auth property, which is set automatically.

pwa: PWA and pwaVue: Object

To configure the use of PWA features, use the pwa option and assign a @codecoupler-pro/pwa instance.

If PWA features have been enabled, the @codecoupler-pro/app-pwa-vue component is loaded into the stage pwa-status and is used to display a button for installing a PWA. You can find all the configuration options (Vue props) for this component here: PWA Handling Vue

Hint: Handling the installation prompt works only in chromium based browsers!

All the configuration options described there can be set using the pwaVue property, except for the pwa property, which is set automatically.

swLoader: ServiceWorkerLoader and swLoaderVue: Object

To configure the loading of a service worker, use the swLoader option and assign a @codecoupler-pro/app-service-worker instance.

If a service worker is used, the @codecoupler-pro/app-service-worker-vue component is loaded into the stage status-sw and is used to display a button for updating the service worker if needed and display status information. You can find all the configuration options (Vue props) for this component here: Service Worker Loader Vue

All the configuration options described there can be set using the swLoaderVue option, except for the swLoader property, which is set automatically.

launcher: Object

Configuration options for the launcher component loaded into the sidebar stage. You can find all the configuration options for this component here: Launcher

You should not set the following options as they will be set automatically: registry, identity, popoverClasses, tooltipClasses.

logoIcon and logoBackground

These images will be used as background and in the header section.

Styling

When using this component, it is essential to assign a unique class (via the class property of the start definition object). This class is also used for elements rendered in the body of the document (popovers, tooltips, dropdowns). Without this class, these elements cannot be styled accurately.

This class is referred to as root in the following examples and should, of course, be given a locally unique name, which is defined using the CSS Modules mechanism as :local(.root).

To style all popovers, tooltips, and dropdowns for all components used, you can use the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
:local(.root) {
  &.popover {
    /* Style all popovers here */
  }
  &.tooltip {
    /* Style all tooltips here */
  }
  &.dropdown-menu {
    /* Style all dropdowns here */
  }
}

Every stage where a component is loaded (all except header), the component has the class component and all stages also use their id as class name:

1
2
3
4
5
6
7
:local(.root) {
  & .id-of-stage {
    & .component {
      /* Style here the component */
    }
  }
}

The specific ways in which the individual elements of a stage can be styled are explained in the sections on each stage in the next chapter.

Stages

Stage wco-header

This stage is hidden by default and is displayed only if PWA features are enabled and the site runs as standalone PWA application in windows control overlay mode; it represents the title bar of the PWA application.

It is a simple line of text containing the image from the passed via logoIcon option and the current title from document.title. You can access the internal HTML structure using CSS as follows:

1
2
3
4
5
6
7
8
:local(.root) {
  & .wco-header {
    & .component {
      & img {}
      & span {}
    }
  }
}

More details about the classes that will be used to handle the window controls overlay feature: CodeCoupler Application Basics PWA Handling.

Just an img element which loads the image passed via the logoIcon option. You can access the internal HTML structure using CSS as follows:

1
2
3
4
5
6
7
:local(.root) {
  & .logo {
    & .component {
      & img {}
    }
  }
}

Stage sidebar

The @codecoupler/launcher component is loaded into this stage. You can configure the component with the option launcher. Read more about this in the description of the launcher option.

The stage will be configured as scrollable:

1
2
3
4
5
6
7
{
  levels: {
    base: {
      scrollable: true
    }
  }
}

All SVG icons scale relative to the font size. Adjusting the font size causes the icons to adjust accordingly.

You can access the internal HTML structure using CSS as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
:local(.root) {
  & .sidebar {
    & .component {
      /* Style launcher here */
    }
  }
  &.sidebar.tooltip {
    /* Style launcher tooltips here */
  }
  &.sidebar.popover {
    /* Style launcher popvers here */
  }
}

The boilerplate already includes a basic style that displays the launcher as a vertical list. For more details on the internal structure of the launcher component, see here: Launcher

Stage main

We load components into the main stage, which may require authentication. If the user is not authenticated or has logged out, these components should be destroyed. However, we make an exception for the background layer.

Therefore, we set the following options for the main stage:

{
  start: {
    settings: {
      $auth: {
        module: this.#options.auth,
        controller: AuthControllerDestroy
      }
    }
  },
  levels: {
    background: {
      class: "background",
      start: { settings: { $auth: { restrictions: { required: false } } } }
    }
  }
}

We load a centered image into the background layer that was passed via logoBackground option.

We will assign a background class to the background layer element to enable more specific styling. You can access the internal HTML structure using CSS as follows:

1
2
3
4
5
6
7
8
9
:local(.root) {
  & .main {
    & .background {
      & .component {
        & img {}
      }
    }
  }
}

Stage custom-header

We do not load any additional components into the custom-header stage. This stage is intended for custom components. However, components are not destroyed but merely hidden when authentication is not present. For this purpose, we use a special controller that does not block the initialization phase. This means the components can be loaded as early as possible. Therefore, we set the following options:

{
  start: {
    settings: {
      $auth: {
        module: this.#options.auth,
        restrictions: { disabled: true },
        controller: AuthControllerHide
      }
    }
  }
}

Stages status-pwa, status-sw and status-auth

This is where the status button components are loaded. All stages with status buttons also have an individual class, as well as a general class, status-button. This allows all status buttons to be styled centrally, if necessary:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
:local(.root) {
  & .status-button {
    & .component {
      /* Style all buttons here */
    }
  }
  &.status-button.popover {
    /* Style all popovers of all buttons here */
  }
  &.status-button.tooltip {
    /* Style all tooltips of all buttons here */
  }
  &.status-button.dropdown-menu {
    /* Style all dropdowns of all buttons here */
  }
}

All SVG icons scale relative to the font size. Adjusting the font size causes the icons to adjust accordingly.

Stage status-sw

The @codecoupler-pro/app-service-worker-loader-vue component is loaded into this stage. You can configure the component with the option swLoaderVue. Read more about this in the description of the swLoaderVue option.

You can access the internal HTML structure using CSS as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
:local(.root) {
  & .status-sw {
    & .component {
      /* Style sw button here */
    }
  }
  &.status-sw.popover {
    /* Style sw popovers here */
  }
  &.status-sw.dropdown-menu {
    /* Style sw dropdowns here */
  }
}

Details about the internal structure of the service worker status button can be found here: Service Worker Loader Vue

Stage status-pwa

The @codecoupler-pro/app-pwa-vue component is loaded into this stage. You can configure the component with the option pwaVue. Read more about this in the description of the pwaVue option.

You can access the internal HTML structure using CSS as follows:

1
2
3
4
5
6
7
:local(.root) {
  & .status-pwa {
    & .component {
      /* Style pwa button here */
    }
  }
}

Details about the internal structure of the PWA status buttons can be found here: PWA Handling Vue

Stage status-auth

The @codecoupler/auth-status-vue component is loaded into this stage. You can configure the component with the option authStatusVue. Read more about this in the description of the authStatusVue option.

You can access the internal HTML structure using CSS as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
:local(.root) {
  & .status-auth {
    & .component {
      /* Style auth button here */
    }
  }
  &.status-auth.dropdown-menu {
    /* Style auth dropdowns here */
  }
}

Details about the internal structure of the authentication status buttons can be found here: Authentication Status Vue