Local UI Blockers for CDF

README.md

Local UI Blockers for CDF

Description

This proto-module adds the possibility of blocking certain UI regions from the user, by adding an overlay and a spinning wheel on top of them. It allows several blockers to be registered and maintains separate counters for each of them.

Dependencies

• jQuery
• jQueryUI (particularly blockUI)
• Underscore
• Dashboards object

All of these are bundled with CDF.

Usage

The basic interface is

Registering blockers

	moduleName.addBlocker( name, selector);

If selector is not passed, the 1st argument will be used as name and selector.

Increment Running Calls

This activates the blocker.

	moduleName.incrementRunningCalls( name );

Increment Running Calls

This de-activates the blocker but only when the running calls get to 0.

	moduleName.decrementRunningCalls( name );

The increment and decrement functions, when called without an argument, will use the default CDF blocker.

Overriding component block and unblock methods

The module methods getBlock and getUnblock return functions that can be used directly to override the base ones provided by CDF UnmanagedComponent. They will be bound to the registered blocker whose name is passed on function creation.

uiBlockers.js

/*
 * uiBlockers
 * Description: adds the possibility of blocking the UI on specific regions, mantaining separate 
 *   runningCalls counters for each of the registered regions.
 *
 */

function uiBlockers ( config ){

    // Utils
    var isString = _.isString,
        isEmpty = _.isEmpty,
        bind = _.bind;


    var blockers = {
        '': { calls: 0, selector: 'body' }
    };


    function normalizeSelector ( selector ){
        return ( isString( selector ) && !isEmpty( selector ) ) ? selector : 'body';
    }

    function hasBlocker ( name ){
        return !!blockers[name];
    }

    function addBlocker ( name, selector ){
        if ( _.isUndefined( selector ) ){
            selector = name;
        }
        var out = false;
        if ( !hasBlocker( name ) ){
            out = blockers[name] = { calls: 0, selector: normalizeSelector( selector ) };
        }
        return out;
    }

    function getSelector ( name ){
        return ( blockers[name] && blockers[name].selector );
    }

    function incCalls ( name ){
        if ( hasBlocker(name) ){
            blockers[name].calls = ( blockers[name].calls || 0 ) + 1;
        }
    }
    function decCalls ( name ){
        if ( hasBlocker(name) ){
            blockers[name].calls = Math.max( ( blockers[name].calls || 0 ) - 1, 0 );
        }
    }
    function resetCalls( name ){
        if ( hasBlocker(name) ){
            blockers[name].calls = 0;
        }   
    }
    function getCalls( name ){
        return ( blockers[name] && blockers[name].calls );
    }

    function showProgressIndicator ( name ) {
        if( $.blockUI ){
            var selector = getSelector( name );
            if ( selector == 'body'){
                Dashboards.blockUIwithDrag();
            } else {
                $(selector).block();
            }
        }
    }

    function hideProgressIndicator ( name ) {
        if( $.unblockUI ){
            var selector = getSelector( name );
            if ( selector == 'body'){
                $.unblockUI();
            } else {
                $(selector).unblock();
            }
        }
        Dashboards.showErrorTooltip();
    }

    function resetRunningCalls ( name ){
        resetCalls( name );
        setTimeout( function(){
            hideProgressIndicator( name );
        }, 10);
    }

    function incrementRunningCalls ( name ) {
      incCalls( name ) ;
      showProgressIndicator( name );
    }

    function decrementRunningCalls ( name ) {
      decCalls( name ) ;
      setTimeout( function(){
        if( getCalls( name ) <= 0 ){
          hideProgressIndicator( name );
          resetCalls( name ); // Just in case
        }
      },10);
    }


    function getBlock ( comp, name ) {
        return bind(function() {
            if(!this.isRunning){
              incrementRunningCalls( name );
              this.isRunning = true;
            }
        }, comp);
    }

    function getUnblock ( comp, name ) {
        return bind(function(){
            if(this.isRunning){
                decrementRunningCalls( name );
                this.isRunning = false;
            }
        }, comp);
    }


    return {
        addBlocker: addBlocker,
        showProgressIndicator: showProgressIndicator,
        hideProgressIndicator: hideProgressIndicator,
        resetRunningCalls: resetRunningCalls,
        getRunningCalls: getCalls,
        incrementRunningCalls: incrementRunningCalls,
        decrementRunningCalls: decrementRunningCalls,
        getBlock: getBlock,
        getUnblock: getUnblock

    };

}