A library that provides helpers for your Angular projects that speed up the development or solve tricky problems.

Table of contents:

• Installation
• Package
  • Fragment component
    • Usage
  • Let directive
    • Usage
  • Media
    • Usage
    • Media service
    • Media component
    • Media directive
    • Common media queries
• License

Installation

npm install --save ng-helpers

Package

This package consists of the following helpers:

• Fragment component
• Media

Fragment component

The Fragment component provides the solution for cases when you don't want your component template to be wrapped in a named tag. Such cases include:

• having multiple root nodes
• having a native element as a root node

An angular component gets wrapped in a single named tag, provided by the selector property. Each component must therefore have a single root DOM note wrapping an entire body. There are, however, situations when we would like to have multiple root nodes, for example, if our component is to render li elements in the ul:

With parent template defined as:

<ul>
  <my-list/>
</ul>

And component defined as:

@Component({
  selector: 'my-list',
  template: `
    <li>Apple</li>
    <li>Banana</li>
    <li>Orange</li>
  `
})
export class MyList {}

renders as

<ul>
  <my-list>
    <li>Apple</li>
    <li>Banana</li>
    <li>Orange</li>
  </my-list>
</ul>

which is, of course, invalid HTML and might additionally break our styles. What we would like is for it to render as:

<ul>
  <li>Apple</li>
  <li>Banana</li>
  <li>Orange</li>
</ul>

Usage

The Fragment component replaces the root element with the contents of the template defined as the first child element.

@Component({
  selector: 'my-list',
  template: `
    <ng-template>
      <li>Apple</li>
      <li>Banana</li>
      <li>Orange</li>
    </ng-template>
  `
})
export class MyList extends FragmentComponent implements OnInit {
  constructor(vcRef: ViewContainerRef) {
    super(vcRef);
  }

  ngOnInit(): void {
    this.appendDOM();
  }
}

and given parent template:

<ul>
  <my-list/>
</ul>

will render as:

<ul>
  <li>Apple</li>
  <li>Banana</li>
  <li>Orange</li>
</ul>

Possible usages are rendering partial li lists, table rows or columns or any other parts of DOM that require the specific parent DOM element.

Let directive

The angular template is often using deep nested object values or observables in multiple places. The common pattern is to use the ngIf structural directive to extract the value:

<div *ngIf="loadingState$ | async as loadingState">
  <my-table 
    [loading]="loadingState" 
    [rows]="rows"
    [columns]="columns">
  </my-table>
  <button 
    (click)="addRow()"
    [disabled]="loadingState === LoadingState.Loading"
  >Add row</button>
</div>

The non-so-obvious flaw of the above approach is that whenever the loadingState has a falsy value (0, null, false, etc.) the entire block will not be rendered. The ngLet solves this by always rendering the inner content and passing the value no matter if falsy or truthy.

Usage

Before using the directive we need to include the module.

import { LetModule } from 'ng-helpers';

@NgModule({
  imports: [
    LetModule
  ]
})
export class AppModule { }

Now we can use it in our component templates

<div *ngLet="loadingState$ | async as loadingState">
  The {{ loadingState }} will be available here
</div>

We can also use it to put deep nested values in variables for better readability:

<form [formGroup]="myForm">
  <input formControlName="name" required />
  <ng-container *ngLet="myForm.controls.name as name">
    <div *ngIf="name.invalid && (name.dirty || name.touched)"
        class="alert alert-danger">

      <div *ngIf="name.errors.required">
        Name is required.
      </div>
      <div *ngIf="name.errors.minlength">
        Name must be at least 4 characters long.
      </div>
      <div *ngIf="name.errors.forbiddenName">
        Name cannot be Bob.
      </div>
    </div>
  </ng-container>
</form>

Media

The Media package consists several utilities used to responsive content handling in Angular. Those utilities include:

• Media service
• Media component
• Media directive

You can read more about the motivation in my blog post Responsive Angular Components. It's an upgrade from CSS based responsive design by media queries as it allows us to manipulate the actual content of the DOM instead of just it's visibility. By having too many differences between responsive states we are polluting the DOM by keeping there elements that are not visible.

This can be avoided in Angular by using services, directives or components that will not be rendered unless the certain media query is matched. For example we could use the service to fetch data from different endpoints depending on media or use a component to optionally render a certain DOM block.

Usage

In order to use any of the utility parts of the media package we need to include the MediaModule:

import { MediaModule } from 'ng-helpers';

@NgModule({
  imports: [
    MediaModule
  ]
})
export class AppModule { }

Media service

The Media service is a service that exposes an Observable returning matched state of the given media queries.

Usage:

@Component({
  selector: 'foo-bar',
  template: `
    <div *ngIf="mediaService.match$ | async">
      I am shown only in the portrait mode
    </div>
  `
})
class FooBarComponent { 
  private sub: Subscription<boolean>;

  constructor(private readonly mediaService: MediaService) {};

  ngOnInit() {
    // initialize listener
    this.mediaService.setQuery('(orientation: portrait)');
    // subscribe to changes programatically or via template
    this.mediaService.match$
      .pipe(
        distinctUntilChanged(),
        map(isPortrait => isPortrait ? 'Potrait' : 'Landscape')
      )
      .subscribe(orientation => console.log(`Orientation changed! New: ${orientation}`));
  }
}

In order to avoid memory leaks don't forget to unsubscribe all the listeners! The observable will be automatically closed when service is destroyed.

Media component

The Media component is an angular wrapper component for manipulating the rendering of the content based on the matched media queries.

Usage:

@Component({
  selector: 'foo-bar',
  template: `
    <use-media query="(min-width: 768px)">
      I am visible only on desktop
    </use-media>
    <use-media query="(orientation: portrait)">
      I am visible only on portrait mode
    </use-media>
  `
})
class FooBarComponent { }

Media directive

The Media directive is a structural directive for manipulating the content of the template based on the matched media queries.

Usage:

<div *media="'(min-width: 768px)'">I will be shown only on desktop</div>
<my-portait-component *media="'(orientation: portrait)'"></my-portait-component>

Common media queries

Some of the most common media queries:

| Query | Result | | - | - | | (max-width: 768px) | Used for mobile views | | (min-width: 769px) and (max-width: 1200px) | Standard browsers size | | (min-width: 1201px) and (max-width: 1400px) | Wide browsers | | (min-width: 1401px) | Ultra-wide browser | | (orientation: landscape) | Landscape mode on handheld device or if width > height | | (orientation: portrait) | Portrait mode on handheld device or height > width |

You can find more on CSS Tricks post.

License

MIT

Copyright (c) 2019-present, Miroslav Jonas