ngx‐core - IbenTesara/opensource GitHub Wiki

Introduction

This library provides several independent utilities that form the base of the Angular based @ibenvandeveire packages.

Installation

Install the package first:

npm install @ibenvandeveire/ngx-core

Versioning

This package will follow a semver-like format, major.minor.patch, in which:

major: Follows the Angular major version
minor: Introduces new features and (potential) breaking changes
patch: Introduces bugfixes and minor non-breaking changes

Content

NgxWindowService

This service uses the DOCUMENT injection-token to provide several methods to access both document and window and related information. It is convenient for using the document or window without breaking SSR.

Properties

width$

The window-service exposes a width$ observable to get the window-width. It defaults to 1200 when no window is defined.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	public windowWidth$: Observable<number>;

	constructor(private windowService: NgxWindowService) {
		this.windowWidth$ = this.windowService.width$;
	}
}

scrollingUp$

The window-service exposes a scrollingUp$ observable to know when the scroll has ended.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	public scrollingUp$: Observable<number>;

	constructor(private windowService: NgxWindowService) {
		this.scrollingUp$ = this.windowService.scrollingUp$;
	}
}

currentScrollPosition

The window-service exposes a currentScrollPosition property that contains the currentScrollPosition after handleContentScroll has been called.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	public currentScrollPosition: Observable<number>;

	constructor(private windowService: NgxWindowService) {
		this.currentScrollPosition = this.windowService.currentScrollPosition;
	}
}

window

The window-service exposes the window property which is a link to the Window object.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	public window: Observable<number>;

	constructor(private windowService: NgxWindowService) {
		this.window = this.windowService.window;
	}
}

document

The window-service also exposes the document property which is a link to the Document object.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	public window: Observable<number>;

	constructor(private windowService: NgxWindowService) {
		this.window = this.windowService.window;
	}
}

Methods

scrollTo

A scrollTo method is provided to scroll to a position on the page. When there is no window, it will do nothing.

The offset is set to 0 by default so triggering the method without a value will scroll to the top of the page.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	constructor(private windowService: NgxWindowService) {}

	public somethingHappened(): void {
		this.windowService.scrollTo(500);
	}
}

hasDocument

The hasDocument-method is provided to check if there is a document.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	constructor(private windowService: NgxWindowService) {}

	public aCoolMethod(): void {
		if (this.windowService.hasDocument()) {
			// do something that depends on the document.
		}
	}
}

isBrowser

The isBrowser-method is provided to check if the current platform is a browser.

It uses the isPlatformBrowser method with the PLATFORM_ID injection-token internally.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	constructor(private windowService: NgxWindowService) {}

	public aCoolMethod(): void {
		if (this.windowService.isBrowser()) {
			// do something that depends on the browser.
		}
	}
}

runInBrowser

The runInBrowser-method is provided to run a specific callback only when in the browser.

The callback has access to the window and the document elements provided in its parameters.

import { NgxWindowService } from '@ibenvandeveire/ngx-core';

export class YourComponent {
	constructor(private windowService: NgxWindowService) {}

	public aCoolMethod(): void {
		this.windowService.runInBrowser(({ browserWindow, browserDocument }) => {
			// Do something with the browser window or document
		});
	}
}