@mediacologne/ng-theme

Angular library that bundles application styles, Angular Material and MDBootstrap component styles up to provide one centrally customizable theme.

News

• This is an Angular >= 7 Library!

Installation

Install the NPM Module

$ npm i --save @mediacologne/ng-theme

Install dependencies

TL;DR:

package.json:

"dependencies": {    
    "@angular/animations": "^8.0.0",
    "@angular/cdk": "^8.0.0",
    "@angular/common": "^8.0.0",
    "@angular/core": "^8.0.0",
    "@angular/material": "^8.0.0",
	"ng-uikit-pro-standard": "git+https://oauth2:[email protected]/mdb/angular/ng-uikit-pro-standard.git",
    "font-awesome": "^4.7.0"
}

Angular Material (optional)

$ npm i --save @angular/material @angular/cdk @angular/animations

MDBootstrap (optional)

1. Go to git.mdbootstrap.com and log in with Media Cologne credentials.
2. From top right corner click on your avatar and choose "Setting → Access Tokens" or navigate directly to: git.mdbootstrap.com/profile/personal_access_tokens
3. Provide a name (usually your project name) for your token and choose "api" from scopes. Then click "Create personal access token"
4. Once your token will be generated make sure to copy it and store in safe place. You won't be able to access it again. In case of lose you will have to generate new token again.
5. Copy the HTTP MDB repository link, adjust the link with YOUR_ACCESS_TOKEN as shown below and install the module:

$ npm i --save git+https://oauth2:[email protected]/mdb/angular/ng-uikit-pro-standard.git#7.4.1

6. Install 3rd party libraries

# Attention: Check outdated versions!!
$ npm i --save [email protected] @types/chart.js [email protected] [email protected] [email protected] font-awesome [email protected]

loaders.css (optional) [WIP]

$ npm i --save loaders.css

ngx-datatable (optional) [WIP]

$ npm i --save @swimlane/ngx-datatable

Create theme

Create the following files with example contents in ./src/resources/theme.

_variables.scss

// Theme variable overrides
$theme-color-primary: purple;
$theme-color-success: chartreuse;

// Custom variables
$app-color-special: darkblue;

_application.scss

// Custom definitions
.special {
  color: $app-color-special;
}

There are multiple ways to include the theme and its components. You can either include the whole theme or each component individually. For more comfortable usage take a look at the ready-to-use theme templates:

• theme-all.scss (whole theme)
• theme-mdb.scss (MDB only)
• theme-md.scss (MD only)
• theme-custom.scss (custom, example below)

theme.scss example:

// Application specific variable overrides
@import 'variables';

// Import everything quick-start-like
@import 'theme/scss/all';

// Application styles
@import 'application';

Roboto Font and Material Icons locally vs. cdn

As per default the Roboto font and the Material icons are imported and loaded from Google. If you want to manage the import yourself, you can override the following variables:

$import-md-font: true !default;
$import-md-icons: true !default;

Add styles and scripts

Add to angular.json:

"styles": [
  "node_modules/font-awesome/scss/font-awesome.scss",
  "node_modules/loaders.css/src/loaders.scss", // Only if using loaders.css
  "node_modules/@swimlane/ngx-datatable/release/themes/material.css", // Only if using ngx-datatable
  "node_modules/@swimlane/ngx-datatable/release/assets/icons.css", // Only if using ngx-datatable
  "src/resources/theme/theme.scss"
],
"stylePreprocessorOptions": {
  "includePaths": [
    "./node_modules",
    "./node_modules/@mediacologne/ng-theme/assets",
    "./src/resources/theme"
  ]
},
"scripts": [
  "node_modules/chart.js/dist/Chart.js",
  "node_modules/hammerjs/hammer.min.js",
  "node_modules/easy-pie-chart/dist/easypiechart.js",
  "node_modules/screenfull/dist/screenfull.js",
  "node_modules/loaders.css/loaders.css.js" // Only if using ngx-datatable together with jQuery!
]

Using the Library

Add following imports and providers to app.module.ts, depending on whether you want Angular Material and/or MDBootstrap:

import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
import {MatButtonModule} from '@angular/material';
import {MDBBootstrapModulesPro, MDBSpinningPreloader} from 'ng-uikit-pro-standard';

@NgModule({
  imports: [
    BrowserAnimationsModule,
    MatButtonModule, // Example
    MDBBootstrapModulesPro.forRoot() // Example
  ],
  providers: [
    MDBSpinningPreloader // Example
  ]
})

Customization

Theme

The main theme file is theme.scss. Here you can include or exclude specific theme components by commenting them in or out, e.g. Angular Material and MDBootstrap.

Application-specific customization can be done in _variables.scss. Here you can adjust brand colors, typography etc. to fit your application needs. Check Theme variables for all available overrides.

Application

Put custom styles into _application.scss.

Documentation

Concepts

The idea of this Angular library is an easy-to-use theme wrapper module that modifies the component styles of Angular Material and MDBootstrap and provides a centrally customizable theme.

Developing the Library

Testing

tbw;

Updating MDBootstrap

This library relies on the original MDBootstrap styles. Running npm run update-mdb updates the npm package and copies the new files into the library. Don't forget to update all version specifications related to MDBootstrap in this readme.

Building

Build the library by running npm run lib-build in ./. Destination is ./dist/ng-theme-module

Publishing

Increment the version number in ./projects/app/package.json and trigger a new build to auto-publish the library via GitLab CI:

{
  "name": "@mediacologne/ng-theme",
  "version": "X.X.X",
  ...
}