npm package: @kaosnoff/ng-materializecss
Description: Angular support for Materialize CSS framework
Author: Vitor Freire
Latest version: 1.0.3

# @kaosnoff/ng-materializecss

This project is loosely based on [**angular2-materialize**](https://www.npmjs.com/package/angular2-materialize), and adds Angular support for [MaterializeCSS framework](http://materializecss.com/).

This library is needed to add dynamic behaviors of MaterializeCSS that uses JavaScript in addition to plain CSS.

[View a demo (yet from angulat2-materialize) of MaterializeCSS in action.](https://infomedialtd.github.io/angular2-materialize/)

To use the library you need to import it once per project and then use its MaterializeDirective directive for binding it to any component that needs a dynamic behavior, like collapsible panels, tooltips, etc.

## Using ng-materializecss

Start by following the Angular CLI or webpack instructions below to add the required dependencies to your project.

Add the NgMaterializecssModule to your NgModule:

```javascript
import { NgMaterializecssModule } from "@kaosnoff/ng-materializecss";
 
@NgModule({
  imports: [
    //...
    NgMaterializecssModule,
  ],
  //...
})
```

In your component, use it for dynamic behavior. For example, for collapsible panels:

```html
<ul materialize="collapsible" class="collapsible" data-collapsible="accordion">
  <li>
    <div class="collapsible-header"><i class="material-icons">filter_drama</i>First</div>
    <div class="collapsible-body"><p>Lorem ipsum dolor sit amet.</p></div>
  </li>
  <li>
    <div class="collapsible-header"><i class="material-icons">place</i>Second</div>
    <div class="collapsible-body"><p>Lorem ipsum dolor sit amet.</p></div>
  </li>
  <li>
    <div class="collapsible-header"><i class="material-icons">whatshot</i>Third</div>
    <div class="collapsible-body"><p>Lorem ipsum dolor sit amet.</p></div>
  </li>
</ul>
```
Apply an empty [MaterializeDirective](https://github.com/kaosnoff/ng-materializecss/blob/master/projects/ng-materializecss/src/lib/ng-materializecss.directive.ts) attribute directive for top level components, like forms:

```html
<form materialize class="col s12">
  <div class="row">
    <div class="input-field col s6">
      <input placeholder="Placeholder" id="first_name" type="text" class="validate">
      <label for="first_name">First Name</label>
    </div>
  </div>
</form>
```

The MaterializeDirective attribute directive (materialize) accepts any MaterializeCSS initialization call to apply to the element. The list of supported functions are provided by MaterializeCSS. Examples: collapsible, modal, tooltip, dropdown, tabs, material_select, sideNav, etc.

For example, to apply tooltip:

```html
<a materialize="tooltip" class="btn tooltipped" data-position="bottom" data-delay="50" data-tooltip="I am tooltip">Hover me!</a>
```

The `materialize` attribute directive also allows specifying parameters to be passed to the function, but providing a `materializeParams` attribute returning an array of params. Use it with a function call or even by inlining the params in the HTML.

Another useful option is emitting actions on an element. You may want to do that for calling Materialize functions, like closing a modal dialog or triggering a toast. You can do that by setting the `materializeActions` attribute, which accepts an EventEmitter. The emitted events can either be a "string" type action (Materialize function call) or a structure with action and parameters:

The example below shows how you'd create a modal dialog and use the actions to open or close it.

```html
<!-- Modal Trigger -->
<a href="#modal1" class="waves-effect waves-light btn modal-trigger" (click)="openModal()">Modal</a>
 
<!-- Modal Structure -->
<div id="modal1" class="modal bottom-sheet" materialize="modal" [materializeParams]="[{dismissible: false}]" [materializeActions]="modalActions">
  <div class="modal-content">
    <h4>Modal Header</h4>
    <p>A bunch of text</p>
  </div>
  <div class="modal-footer">
    <a class="waves-effect waves-green btn-flat" (click)="closeModal()">Close</a>
    <a class="modal-action modal-close waves-effect waves-green btn-flat">Agree</a>
  </div>
</div>
```

```javascript
import {MaterializeAction} from "@kaosnoff/ng-materializecss";
  //...
  modalActions = new EventEmitter<string|MaterializeAction>();
  openModal() {
    this.modalActions.emit({action:"modal",params:['open']});
  }
  closeModal() {
    this.modalActions.emit({action:"modal",params:['close']});
  }
```

For dynamic select elements apply the `materializeSelectOptions` directive to trigger element updates when the options list changes:

```html
<select materialize="material_select" [materializeSelectOptions]="selectOptions">
  <option *ngFor="let option of selectOptions" [value]="option.value">{{option.name}}</option>
</select>
```

## Installing & configuring `ng-materializecss` in projects created with the Angular CLI

Install **MaterializeCSS** and `@kaosnoff/ng-materializecss` from npm

```console
npm install --save materialize-css@next
npm install --save @kaosnoff/ng-materializecss
```
or
```console
yarn add materialize-css@next
yarn add @kaosnoff/ng-materializecss
```

jQuery and Hammer.JS are required (working to drop this requirements)

```console
npm install jquery --save
npm install hammerjs --save
```
or
```console
yarn add jquery hammerjs
```

Edit the `angular.json`:

- Go to section `projects` and find `styles` array inside it (with only `styles.css` value by default), add the following line inside array before any styles:

```
  "./node_modules/materialize-css/dist/css/materialize.css"
```
- Go to section `projects` and find `scripts` array inside it, and add the following lines inside array
```
  "./node_modules/jquery/dist/jquery.js",
  "./node_modules/hammerjs/hammer.js",
  "./node_modules/materialize-css/dist/js/materialize.js"
```

Add to the top of `app.module.ts`
```javascript
import { NgMaterializecssModule } from "@kaosnoff/ng-materializecss";
```
Add `NgMaterializecssModule` inside `imports` array of `@NgModule` decorator in `app.module.ts`.

Add this line to header of `index.html`
```html
<link href="http://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
```

## About the library

This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 13.2.2.

## Development server

Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.

## Code scaffolding

Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.

## Build

Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.

## Running unit tests

Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).

## Running end-to-end tests

Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.

## Publishing

Go to `dist/ng-materializecss` and run `npm publish`.

## Further help

To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.