angular-block-ui

An elegant but advanced AngularJS module that allows you to block user interaction on AJAX requests.
5 people use it
Author: 2729829?v=2 McNull
Submitted by: 2729829?v=2 McNull

angular-block-ui

An AngularJS module that allows you to block user interaction on AJAX requests. Blocking is done automatically for each http request and/or manually via an injectable service.

Dependencies

Besides AngularJS (~1.2.4), none.

Demos

Live demos can be found on Plunker or by executing the website included in the GitHub project .

Installation

Either copy the contents of the dist directory of the Github project or install with bower from the command line (**recommended**):

Include both the JS and CSS file in your html:

Create a dependency on blockUI in your main Angular module:

Usage

By default the module will block the user interface on each pending request made from the browser. This behaviour can be modified in the configuration.

It's also possible to do the blocking manually. The blockUI module exposes a service by the same name. Access to the service is gained by injecting it into your controller or directive:

BlockUI service methods

start

The start method will start the user interface block. Because multiple user interface elements can request a user interface block at the same time, the service keeps track of the number of start calls. Each call to start() will increase the count and every call to stop() will decrease the value. Whenever the count reaches 0 the block will end.

Note: By default the block is immediately active after calling this method, but to prevent trashing the user interface each time a button is pressed, the block is visible after a short delay. This behaviour can be modified in the configuration.

Arguments:

  • message (string) Indicates the message to be shown in the overlay. If none is provided, the default message from the configuration is used.

stop

This will decrease the block count. The block will end if the count is 0.

reset

The reset will force an unblock by setting the block count to 0.

message

Allows the message shown in the overlay to be updated while to block is active.

done

Queues a callback function to be called when the block has finished. This can be useful whenever you wish to redirect the user to a different location while there are still pending AJAX requests.

Arguments:

  • callback (function) The callback function to queue.

Blocking individual elements

Instead of blocking the whole page, it's also possible to block individual elements. Just like the main blockUI service, this can be done either manually or automatically. Elements can be made block ui enabled by wrapping them in a block-ui element.

Manual blocking

The block-ui directive takes an optional value, which can be used to get an instance of the associated blockUI service.

Automatic blocking

Automatic blocking elements can be done by providing the block-ui directive a block-ui-pattern attribute. This attribute should contain a valid regular expression, which indicates the requests that are associated with the specific element.

BlockUI module configuration

The configuration of the BlockUI module can be modified via the blockUIConfig during the config phase of your Angular application:

Properties

message

Changes the default message to be used when no message has been provided to the start method of the service. Default value is 'Loading ...'.

delay

Specifies the amount in milliseconds before the block is visible to the user. By delaying a visible block your application will appear more responsive. The default value is 250.

template

Specifies a custom template to use as the overlay.

templateUrl

Specifies a url to retrieve the template from. The current release only works with pre-cached templates, which means that this url should be known in the $templateCache service of Angular. If you're using the grunt with html2js or angular-templates, which I highly recommend, you're already set.

autoBlock

By default the BlockUI module will start a block whenever the Angular $http service has an pending request. If you don't want this behaviour and want to do all the blocking manually you can change this value to false.

resetOnException

By default the BlockUI module will reset the block count and hide the overlay whenever an exception has occurred. You can set this value to false if you don't want this behaviour.

requestFilter

Allows you to specify a filter function to exclude certain ajax requests from blocking the user interface. The function is passed the Angular request config object. The blockUI service will ignore requests when the function returns false.

autoInjectBodyBlock

When the module is started it will inject the main block element by adding the block-ui directive to the body element.

This behaviour can be disabled if there no need for any fullscreen blocking or if there's more control required.

cssClass

A string containing the default css classes, separated by spaces, that should be applied to each block-ui element. The default value is 'block-ui block-ui-anim-fade'.

If this needs to be overridden for a certain element; set the desired classes on the element including the block-ui class. This way the directive will not apply the configured classes to the element.

comments powered by Disqus
This page was last updated over 2 years ago.