# @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

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

## Install dependencies

TL;DR:

`package.json`:
```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:YOUR_ACCESS_TOKEN@git.mdbootstrap.com/mdb/angular/ng-uikit-pro-standard.git",
    "font-awesome": "^4.7.0"
}
```

### Angular Material (optional)

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

### MDBootstrap (optional)

1. Go to [git.mdbootstrap.com](https://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](https://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:

```bash
$ npm i --save git+https://oauth2:YOUR_ACCESS_TOKEN@git.mdbootstrap.com/mdb/angular/ng-uikit-pro-standard.git#7.4.1
```

6. Install 3rd party libraries

```bash
# Attention: Check outdated versions!!
$ npm i --save chart.js@2.5.0 @types/chart.js easy-pie-chart@2.1.7 hammerjs@2.0.8 screenfull@3.3.0 font-awesome angular5-csv@0.2.10
```

### loaders.css (optional) [WIP]

```bash
$ npm i --save loaders.css
```

### ngx-datatable (optional) [WIP]

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

## Create theme

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

``_variables.scss``
```scss
// Theme variable overrides
$theme-color-primary: purple;
$theme-color-success: chartreuse;

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

``_application.scss``
```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](https://gitlab.dev-mc.de/mediacologne/internal/angular-modules/ng-theme-lib/blob/master/src/resources/theme/theme-all.scss) (whole theme)
- [theme-mdb.scss](https://gitlab.dev-mc.de/mediacologne/internal/angular-modules/ng-theme-lib/blob/master/src/resources/theme/theme-mdb.scss) (MDB only)
- [theme-md.scss](https://gitlab.dev-mc.de/mediacologne/internal/angular-modules/ng-theme-lib/blob/master/src/resources/theme/theme-md.scss) (MD only)
- [theme-custom.scss](https://gitlab.dev-mc.de/mediacologne/internal/angular-modules/ng-theme-lib/blob/master/src/resources/theme/theme-custom.scss) (custom, example below)

``theme.scss`` example:
```scss
// 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:
```scss
$import-md-font: true !default;
$import-md-icons: true !default;
```



## Add styles and scripts

Add to `angular.json`:

```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:

```typescript
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](https://gitlab.dev-mc.de/mediacologne/internal/angular-modules/ng-theme-lib/blob/master/projects/ng-theme-module/assets/theme/scss/core/_variables.scss) 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:

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