UI locking component for JavaScript and jQuery

Ultima Block is a simple yet advanced UI locking component written in JavaScript, using only jQuery core functionalities. Some of the features are:

easily lock and unlock areas you want or don't want the user to access
block message can be plain text or DOM elements (HTML)
offers easy-to-use shorthand options and methods
offers callbacks and interrupts
does not require you to add HTML, CSS or images
does not require additional JavaScript libraries other than jQuery 1.4+
is browser backwards compatible down to Internet Explorer 8

// Documentation

// Include

You can place the UltimaBlock script include basically wherever you want, just make sure that jQuery is loaded before. jQuery is required and must be at least version 1.4 to work with Ultima Tip. Remember to pick jQuery 1.x if you need support for Internet Explorer ≤ 8, otherwise pick 2.x or 3.x.

<html>
    <head>

        ...

        <script src="jquery.js"></script>

    </head>
    <body>

        ...

        <script src="jquery.ultima.block.js"></script>

    </body>
</html>
<html>
    <head>

        ...

        <script src="jquery.js"></script>
        <script src="jquery.ultima.block.js"></script>

    </head>
    <body>

        ...

    </body>
</html>

// Initialization

You can create an instance of the UltimaBlock class by using the native new operator (explicit) or the available jQuery wrapper methods (implicit). The lock will be placed on top of the element you want to block interaction with.

$(target).block('U can\'t touch this!');

- OR -

$.UltimaBlock.block(target, 'U can\'t touch this!');
var lock = new UltimaBlock(target);

lock.block('U can\'t touch this!');

// Constructors

Note: You can also use the $ alias instead of the fully qualified jQuery.

new UltimaBlock ( target, options ) : UltimaBlock
native object constructor, manual method invocation required
jQuery.block ( message, options ) : jQuery
e.g. $('#foo').block('U can\'t touch this!');
considers the preceding jQuery object as target to lock and passes it to a newly created instance of UltimaBlock, invokes the block() method
jQuery.UltimaBlock.block ( target, message, options ) : UltimaBlock
creates an instance of UltimaBlock and invokes the block() method

// Methods

Note: The highlighted UltimaBlock refers to an instance of UltimaBlock while the non-highlighted refers to the static namespace.

UltimaBlock.block ( message )
locks the target and shows the message
UltimaBlock.unblock ( )
unlocks the target and hides the message
jQuery.UltimaBlock.unblock ( target, options ) : UltimaBlock
unlocks the target (if any lock is present)
jQuery.block ( message, options ) : jQuery
e.g. $('#foo').block();
locks the preceding jQuery object, invokes the block() method
jQuery.unblock ( options ) : jQuery
e.g. $('#foo').unblock();
unlocks the preceding jQuery object, invokes the unblock() method

// Options

Note: The options object is deeply structured, consisting of several sub-objects (nested objects). There are two notations available:

var options = {

    css: {

        message: {

            x: '50%',
            y: '50%'

        }

    }

};
var options = {

'->css.message.x': '50%',
'->css.message.y': '50%'

};
// setting the following options...

    UltimaBlock.options = {

        '->css.overlay.className':  'myOverlay'

    };

// ...will override the defaults with the specified properties for all future method calls

// setting the following options using the jQuery prefix...

    $.UltimaBlock.options = {

        '->css.message.className':  'myMessage'

    };

// ...will additionally override defaults for all future jQuery wrapped method calls

− behavior
zIndexInc	true	increment the zIndex for every parallel existing block
− css
overlay
className	''	class added to the overlay element
zIndex	9001
< css property >		any CSS property, will be set as inline style
message
className	''	class added to the message element
offset
x	0	horizontal position offset of the message element, in px
y	0	vertical position offset of the message element, in px
viewport	'auto'	viewport to base the positioning on
x	'50%'	horizontal position of the message, either in px or in %
y	'50%'	vertical position of the message, either in px or in %
< css property >		any CSS property, will be set as inline style
− callbacks
onBlocking	undefined	before locking the target (UltimaBlock) : return false to interrupt
onUnblocking	undefined	before unlocking the target (UltimaBlock) : return false to interrupt

// Examples

You can test UltimaBlock in your browser console as well.

demo : lock & unlock

$('#target').block('click on "unlock element" to unlock');
$('#target').unblock();

// License

// Download

Ultima Block 0.3.6 7 KB