Skip to content

CodeCoupler Professional UI Boilerplate 🔒

This boilerplate uses the component provided by the @codecoupler/header-sidebar package as its root component. Further details on the structure of this component can be found at.

The boilerplate does not load the component directly. Instead, it loads the component src/root.js as the root component. This component is derived from the aforementioned package. This allows you to override and customise all properties and methods in src/root.js to meet your own requirements.

Configuration

The boilerplate provides configuration options in the files src/config.js and static/env.js. Each file exports an object. Within this object, you can define the rootComponent property, which is used for the options of the @codecoupler/header-sidebar component.

1
2
3
4
5
{
  rootComponent: {
    // Put here your root component options
  }
}

Attention! Please read below for more details about the individual options and how to use them in this boilerplate. Some of these can take on other values or are handled differently. In addition, there are other options available to simplify tasks.

Both files are merged and used as the overall configuration. The env.js file has higher priority and can override values from config.js.

Differences between env.js and config.js

The env.js file is loaded at runtime and its contents may vary depending on the environment. It is not included in the final package and will not be pushed into the Git repository. It must be created individually in each deployment environment.

The config.js file, however, is statically compiled into the build output. Unlike the env.js file, the config.js file can use dynamic content, for example by importing and using other modules. The env.js file cannot do this.

This means that all configuration options can be present in both files. However, it is recommended to define the entire configuration in config.js and to use env.js only in deployment environments.

Since the env.js file is not part of either the repository or the deployment package, it is recommended that you save a configuration template in the env.default.js file, if this is important for the deployment. This can then be used as a template to create an env.js file during the initial deployment.

Languages

The boilerplate defines a default token loader that loads the language files at runtime. Language files for each component can be placed in the directory locales according to the following schema:

<namespace (including @char at beginning)>.<language code>.js

The default language code will be set according to the user's browser settings. Only the primary subtag (e.g. "en", "de") will be used.

Also note that the default language code for the Costa Framework is "en". This code is used if no matching language file is found. Therefore, it is advisable to provide at least one language file with the language code "en".

The files must export the object with the tokens that you will use:

1
2
3
export default {
  "any-message-token": "This is the translated string"
};

In your component you can use language tokens instead of fixed strings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { Component } from "@codecoupler/costa-core";

let namespace = "@demo.component";

export default class extends Component {
  // Define here the supported languages:
  static defaults = {
    $i18n: {
      [namespace]: {
        languages: ["en", "de"]
      }
    }
  };

  // Use this helper to make your code shorter:
  #i18n(token, language = undefined) {
    return this.i18n(token, namespace, language);
  }

  // Use this pattern whenever you need a translated string:
  async start() {
    console.info(this.#i18n("any-message-token"));
  }
}

Styling

The following stylesheets are loaded in this order:

  • src/styles/variables.css
  • src/styles/bootstrap.css
  • src/styles/root.module.css
  • src/styles/components.module.css

In variables.css, you can define global variables that can be used by all other stylesheets. At the beginning, a few colors are defined there to be used for icons, borders, backgrounds, and popovers. These variables always begin with --color.

In bootstrap.css The boilerplate imports the Bootstrap stylesheet definitions via SCSS. You will find there the line @import "bootstrap/scss/bootstrap";. After this line, you can redefine all Bootstrap variables. At the beginning, only the Bootstrap default text color is set to the color previously specified in the “--color-text” variable.

The root.module.css defines all local stylesheet classes used for the root component. These include classes for elements rendered at the body level (popovers, tooltips, dropdowns) as well as a class for the root component itself, containing all paths to the individual stages. To begin with, colors are assigned here to several elements that have been defined as variables.

The components.module.css defines all local stylesheet classes used for CodeCoupler components like Panel, Grid etc. To begin with, colors are assigned here to several elements that have been defined as variables.

Configuration Reference

swLoader (Service Worker)

The boilerplate includes a service worker that handles OIDC authentication, among other things.

Instead of specifying a ServiceWorkerLoader instance using the swLoader option, you can simply set the option to true. The boilerplate then takes care of all aspects of the service worker.

Warning! If you use your own ServiceWorkerLoader instance, the boilerplate code does not handle any special actions following a service worker update, and the oidc authentication module template cannot be used.

You can also specify a path to the boilerplate's Service Worker in swLoader if it differs from the default path (/sw.js).

pwa (PWA Features)

To enable all PWA features, simply set the pwa option to true instead of a PWA instance.

auth and authTemplate (Authentication Modules)

Instead of defining an authentication module for the auth option yourself, you can use the additional authTemplate option in your configuration to take advantage of predefined templates. These templates not only create an authentication module but also perform all the necessary steps required for that module.

Attention! If both options are defined, the authTemplate option takes precedence!

The boilerplate contains the following authentication module templates from which you can choose:

OIDC:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  authTemplate: {
    // You must set this to "oidc"
    type: "oidc",
    // Set here the URL to the authority server
    authority: "https://demo.duendesoftware.com",
    // Set client ID and scope you request
    client_id: "interactive.public",
    scope: "openid offline_access profile email"
  }
};

You can use any other properties here that the @codecoupler-pro/auth-oidc module accepts.

Here an example for Keycloak including the roles in the ID token:

1
2
3
4
5
6
7
8
{
  authTemplate: {
    type: "oidc",
    authority: "https://keycloak-server/realms/your-realm-name",
    client_id: "your-client-id",
    scope: "openid offline_access profile email roles"
  }
};

Mockup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  authTemplate: {
    // You must set this to "mockup"
    type: "mockup",
    // Set here all or some properties of your dummy user (optional)
    // Here an example:
    identity: { username: "admin", roles: ["example"] },
    // Set this to true if you want to be initially logedin
    authenticated: false
    // Set this to true or to a string (representing the error message) to throw an error on initializing
    // errorInit: true
    // Set here the delay before init in milliseconds
    // delayInit: 5000
  }
};

You can use any other properties here that the @codecoupler/auth-mockup module accepts.

apps (Applications)

The following files are provided in the src/apps folder to define the application components that are displayed in the launcher: index-dynamic.js, index-static.js, index-example-dynamic.js, index-example-static-overrides.js, index-example-static.js and index-example-static-auth.js. These can be combined as required using the mergeObjects function. The files with the index-example prefix define a set of sample applications:

  • index-example-dynamic.js: Adds all application components found in the Apps folder. They consist of a folder starting with example that contains an index.js file.
  • index-example-overrides.js: This is best used in combination with index-example-dynamic.js, since it tests static overrides of dynamic definitions.
  • index-example-static.js: Adds a set of statically defined applications and groups that cover several test cases.
  • index-example-auth.js: When used on its own, this set is ideal for testing an empty sidebar when the user is not logged in.

For development, you should use the files without the index-example prefix:

  • index-dynamic.js: Put your application components into the local subfolder src/apps. Create a subdirectory with the component id and put there an index.js file which will be loaded as an application component. Do not use the prefix example for your subfolder name. Because the directory name will be used as id, the component will not be started multiple times.
  • index-static.js: You can either override the defaults or define additional application components statically.

Debuging Options

You can override some options by adding a hash #dbg- to the start of your URL. The suffix can be:

  • apps-examples: Load only example apps into launcher.
  • apps-examples-auth: Load only example apps into launcher, which require authentication.
  • apps-examples-fullsize and apps-examples-auth-fullsize: Same as above, just fullsized (not in a panel)
  • sw-error: Simulate an error when loading the service worker.
  • sw-update: Simulate an available service worker update.
  • sw-update-text: Simulate an available service worker update and use a notification text that is very long.
  • auth-mockup: Replace the authentication module in use with the mockup module.
  • auth-mockup-authenticated: Replace the authentication module in use with the mockup module and start in authenticated mode.
  • auth-mockup-delay: Override the authentication module in use with the mockup module and introduce a long delay in the initialisation process.
  • auth-mockup-error: Override the authentication module in use with the mockup module, which will throw an error during initialisation.
  • auth-mockup-error-text: Override the authentication module in use with the mockup module, which will throw an error during initialisation and display a very long error message.
  • launcher: Open tooltips by click, not hover. Leave all the launcher's tooltips and popovers open.
  • pwa: Display the WCO header in normal browser mode. However, note that the height of the header does not correspond to the final result.
  • icons: Display all icons of all status buttons.
  • sw-icon-error, sw-icon-loading, sw-icon-ok, sw-icon-update, sw-icon-all: Show either specific icons or all icons for the service worker status button.
  • auth-icon-login, auth-icon-loading, auth-icon-user, auth-icon-error, auth-icon-all: Show either specific icons or all icons for the authentication status button.
  • pwa-icon-mobile, pwa-icon-desktop, pwa-icon-all: Show either specific icons or all icons for the PWA status button.