@code-workers-io/ngx-block-ui

> Important Note
> This library has its origin in the awesome ng-block-ui library
> from kuuurt13. We are very thankful for his work.
> Why did we release it as a new library? Mainly to support Ivy, a modern Angular environment and of course
> to ship new features and improvements.

A Block UI implementation for Angular


Installation

Add to your project via npm:

``bash
npm install @code-workers.io/ngx-block-ui --save
`

Include the NgxBlockUIModule in your main app module.

`ts
// All other imports
import { NgxBlockUIModule } from '@code-workers.io/ngx-block-ui';

@NgModule({
imports: [
NgxBlockUIModule.forRoot()
],
...
})
export class AppModule { }
`

Quick Start

Wrap your main components in your app root template with a block-ui component.

Import the BlockUI decorator into your component and declare a property with the decorator.
This decorator will auto wire this property to the main Block UI instance of your app.

To start blocking your app, simply invoke the start method.
This method also can take a custom message to display while blocking.
Once finished call the stop method to stop blocking the app.

`ts
import { Component } from '@angular/core';

// Import BlockUI decorator & optional NgBlockUI type
import { BlockUI, NgBlockUI } from 'ng-block-ui';

@Component({
selector: 'app-root',
template:




})
export class AppComponent {
// Decorator wires up blockUI instance
@BlockUI() blockUI: NgBlockUI;

constructor() {
this.blockUI.start('Loading...'); // Start blocking

setTimeout(() => {
this.blockUI.stop(); // Stop blocking
}, 2000);
}
`

$3

For more information and/or migrating to the newest version see Releases.

Settings

Settings can be changed on the module level and component/directive level. Also, in some cases settings can be overwritten via the method level.

$3

A default message can be configured to be shown instead of passing a message each time to the start method. The default message will be shown any time blocking is activated.

| Setting | Type | Description |
| --------- | -------- | ---------------------------------------------- |
| message | string | Custom message to be displayed while blocking. |

#### Module Level

`ts
@NgModule({
imports: [
NgxBlockUIModule.forRoot({
message: 'Default Message'
})
],
...
})
export class AppModule { }
`

#### Component Level

`html



`

#### Method Level

`ts
@Component({
...,
template:




})
export class Cmp {
@BlockUI() blockUI: NgBlockUI;

defaultMessage() {
this.blockUI.start(); // "Default Message" will display
}

customMessage() {
this.blockUI.start('Updating...'); // "Updating..." will display
}
}
`

$3

When blocking with fast service calls the block overlay can flicker for a small amount of time.
To prevent this a delayStart and a delayStop can be configured to prevent this scenario.

| Setting | Type | Description |
| ------------ | -------- | ----------------------------------------------------------------- |
| delayStart | number | Waits given amount of milliseconds before starting to block. |
| delayStop | number | Waits given amount of milliseconds before stopping current block. |

#### Module Level

`ts
@NgModule({
imports: [
NgxBlockUIModule.forRoot({
delayStart: 500,
delayStop: 500
})
],
...
})
export class AppModule { }
`

#### Component Level

`html



`

$3

If you want to display other markup than the default spinner and message then you can provide a custom template.
Custom templates can be provided as a Component or TemplateRef. The template will then be used instead of the default template whenever blocking.

| Setting | Type | Description |
| ---------- | ----------------------------------------- | ---------------------------------------- |
| template | Component | TemplateRef | Custom template to be used when blocking |

#### Component Custom Template

Create a component and declare it in your app module.
The component also will need to be added to the entryComponents property of the module.

_Example Component:_

_Note: When providing a Component as a template just add the {{message}}
interpolation to your template and it will display your default message or the message passed to the start method._

`ts
// Template component
// Use block-ui-template class to center div if desired
@Component({
template:

{{ message }}

`ts
@NgModule({
imports: [
NgxBlockUIModule.forRoot({
template: BlockTemplateCmp
})
],
declarations: [
...,
BlockTemplateCmp // Declare template component
],
entryComponents: [ BlockTemplateCmp ]
})
export class AppModule { }
`

##### Component Level

`ts
@Component({
selector: "app-root",
template:



,
})
export class AppComponent {
// Declare template component
blockTemplate: BlockTemplateCmp = BlockTemplateCmp;
}
`

#### TemplateRef Custom Template

Add a with a template reference variable to the view. Then pass the template reference variable to the blockUI component using the [template] property.

_Note: TemplateRef templates can only be set on a Component level._

##### Component Level

`ts
@Component({
selector: "cmp",
template:

,
})
export class Cmp {}
`

Block UI Directive

Sometimes you want to only apply blocking to a certain element in your app.
The Block UI directive can be added to an element to apply blocking only to that specific element.

Add the *blockUI structural directive to any element
and pass it an instance name *blockUI="'contact-list'".

Then in a component create a class property using the Block UI decorator with the instance name @BlockUI('contact-list'). This will then take care of wiring up that property to point to that specific instance in your app.

`ts
@Component({
selector: 'app-cmp',
template:

constructor() {
this.blockUIList.start('Loading...'); // Start blocking element only
this.blockUIList.stop(); // Stop blocking
}
`

$3

Angular has a specific syntax for passing properties to structural directives. Properties are passed in key: value; pair. To pass settings to a Block UI directive they must be passed as shown below.

`html
*blockUI="'instance-name'; message: 'Loading'; template: blockTemplate"
>