Dwhfe-ui NPM | npm.io

DWH Frontend UI Library

This library seeks to provide standard components to build web UI's. It is built with Angular 10 and supports the Material Design. You can also implement your own UI layer (e.g. bootstrap) by providing all components/directives that the material library provides.

Philosophy/Concept of the lib

The lib is intended as frontend library that can adapt to new css/frontend frameworks easily. The idea is that all implementations of the base library share the same signatures and interfaces and through that can be reimplemented in any framework you want.

Right now (Apr. 2020) there is only one implementation: @dser/dwhfe-lib/material. The material implementation implements the base framework using the @angular/material library.

Requirements

Node
Angular 10+

Local lib development

Install needed npm dependencies:

npm install

The folder src/app contains an example app which shows many of the available components. Run it by using npm start.

Installation

npm install @dser/dwhfe-lib

Usage in your project

After you've installed the library you have to import UiModule. This provides the base classes and the basic frameworks that all UiModule's use. Right now, we only provide the MaterialUiModule.

// an example how to import the ui framework

import { NgModule } from "@angular/core";
import { UiMaterialModule, UiModule } from "@dser/dwhfe-lib";

@NgModule({
  imports: [
    UiModule,
    UiMaterialModule, // this could be later switched to UiBootstrapModule for example.
    MaterialDatepickerModule,
    MaterialDataTableModule,
    // ...
    // add more component modules as needed
  ]
})
export class AppUiModule {
}

You can now import the AppUiModule in your AppModule or feature and will have access to all the UI libraries components.

Theming and SASS

The UI Framework provides the most basic styles itself. However, you can overwrite them as you please.

Here is an example styles.scss which shows how to generate the css for when you use the material ui module.

// the main ui module
@import "~@angular/material/theming";

// adjust the path so it points to the installed dwhfe ui library (dwhfe-lib)
@import "../node_modules/@dser/dwhfe-lib/lib/ui-material/scss/dwh-material-theme";

// Include non-theme styles for core.
@include mat-core();

// Define your application's custom theme.
$primary: mat-palette($mat-indigo);
$accent: mat-palette($mat-pink, A200, A100, A400);
$theme-dark: mat-dark-theme($primary, $accent);
$theme-light: mat-light-theme($primary, $accent);

$typography: mat-typography-config(
  $font-family:   '"Gidole Regular", "Source Sans Pro", "Open Sans", "Helvetica Neue", sans-serif',
  $body-1:        mat-typography-level(18px, 28px, 500),
  $body-2:        mat-typography-level(14px, 24px, 500),
  ...
);

// Include theme styles for Angular Material components.
@include angular-material-theme($theme-dark);

// Include theme styles for your custom components.
@include dwh-theme($theme-dark, $theme-light, $typography);
@include dwh-typography($typography, "/assets/fonts");
...

Loading fonts from the @dser/dwhfe-lib node_modules folder

In addition, you have to load the assets from within the @dser/dwhfe-lib package. To do so, change your assets configuration inside your angular.json:

"assets": [
    ...
    {
        "glob": "**/*",
        "input": "@dser/dwhfe-lib/assets",
        "output": "./assets"
    }
]

Internationalization

To translate the dwhfe-lib library, provide the correct locale id via the LOCALE_ID injection token. More information is here https://angular.io/guide/i18n#setting-up-the-locale-of-your-app

Translating Material components

Also, you have to provide MATERIAL_TRANSLATIONS to translate certain components. For example:

        {
            provide: MATERIAL_TRANSLATIONS,
            useValue: {
                pagination: {
                    lastPage: "Letzte Seite",
                    firstPage: "Erste Seite",
                    next: "Weiter",
                    prev: "Zurück",
                    itemsPerPageLabel: "Einträge pro Seite",
                    getRangeLabel: function (page: number, pageSize: number, length: number) {
                        return `Seite ${page + 1} von ${Math.ceil(length / pageSize)} (${length} insgesamt)`;
                    },
                }
            }
        }

Adding components

To add a component first think about what the component should be able to do and what its properties are. Then, define an interface in the projects/dwhfe-lib/src/lib/ui-base project according to your interface definition.

For example if you wanted to create an emoji component the interface could look like this:

export interface EmojiComponent {
  /**
   * The emoji implementation will expose a emoji @Input()
   */
  emoji: string;
}

This interface would be placed inside projects/dwhfe-lib/src/lib/ui-base/components. After that you must implement the interface in your project. For this example you would place your implementation here: projects/dwhfe-lib/example/src/lib/components/emoji/emoji.component.ts (use the angular generator).

The implementation would look like this:

@Component({
    selector: "dwh-emoji-input", // it is important to always prefix your component with dwh-*
    templateUrl: "./example-emoji.component.html",
    styleUrls: ["./example-emoji.component.scss"]
})
export class ExampleEmojiComponent implements EmojiComponent {
    // implement the members of your defined interface
    @Input()
    emoji: string;
}

At last, you have to expose your component to the public api. The public api defines all public members of a library. Only exposed members can be used when installing the lib later via npm install @dser/dwhfe-lib. To do so, add the line export * from './components/emoji/emoji.component'; to your public_api.ts.

You are done. Now create a new version when you are done implementing your component. Don't forget unit tests! In the next build your component should be visible to everyone who installed the lib with the new version.

Creating a new implementation

Follow these steps to add a new DWH FE lib implementation.

Copy the projects/dwhfe-lib/example folder into your project folder at projects/dwhfe-lib It contains the following files:

example (your project name)
├── package.json (needed for ng-packagr to recognize the folder as a submodule.)
└── src
    ├── lib (contains your libs source code)
    └── public_api.ts (defines the interfaces/classes that your lib exports)

Now when you run npm run build the dist folder will contain your module.

When re-implementing components make sure the name is always the same as in other libraries when they implement a base component. E.g. dwh-select should always be named dwh-select in other implementations.

The next step is to implement all components, define your public_api and you are done. Others can now use your new implementation by importing @dser/dwhfe-lib/example.

Creating a link for local testing in parent project

If you make changes in the lib and you want to see this change directly in the parent project, you have to create a local link for the lib.

https://dev.to/erinbush/npm-linking-and-unlinking-2h1g

create local link

in dwhfe-ui

dwhfe-ui$ cd dist/dwhfe-lib
dwhfe-ui/dist/dwhfe-lib$ npm link

in dwh.parent

de.dser.dwh.parent/de.dser.dwh.fenext/angular$ npm link @dser/dwhfe-lib

remove local link

don't forget to unlink when you are done

de.dser.dwh.parent/de.dser.dwh.fenext/angular$ npm unlink @dser/dwhfe-lib 
dwhfe-ui/dist/dwhfe-lib$ npm unlink

Versioning

While you are working on a feature/fix its sometimes necessary to publish a pre-release/alpha version of the UI lib.

We agreed to use the pattern 6.0.0-alpha.0, 6.0.0-alpha.1, ... therefore.

RULE The development branch and any feature branch can contain pre-release versions in their package.json. The master and release branch shall only have valid semver versions (e.g. 6.0.1) set.

At the time of writing, build and publishing of new versions are done locally. See the next section ("Creating a new version") for details.

The publishing of pre-releases needs the additional param --preid. Example:

$ npm version prerelease --preid=alpha
v0.1.1-alpha.0
$ npm version prerelease --preid=alpha
v0.1.1-alpha.1
$ npm version prerelease --preid=alpha
v0.1.1-alpha.2

The branch naming-schema is defined in:

development: *-alpha.*
release: *-beta.*
master: *

To create a new version in development branch, you need to use one of those command lines:

// Patch-Version
npm version prepatch --preid=alpha

// Minor-Version
npm version preminor --preid=alpha

// Major-Version
npm version premajor --preid=alpha

Creating a new productive version

First: Add a new entry on top of the CHANGELOG.md file using the version you will generate/publish.

To be able to publish the new version to our local npm registry (https://npm-registry.dser.local/) use the npm login command. Otherwise, publishing would fail, and you will have to create a new (increased) version (see below).

To create a new version, first think about what the changes are and respect the semver paradigm:

Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

If you decided which version to increase, just run:

npm version <major|minor|patch>

This will run the unit tests, create a build, increase the package.json version, create a git tag with the version number and push the changes to the upstream branch.

The build result in the dist folder is published to our local npm registry. Use npm publish to publish the new version.