Ultima Block

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.

    1. body
    2. head
    1. <html>
          <head>

              ...

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

          </head>
          <body>

              ...

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

          </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.

    1. implicit
    2. explicit
    1. $(target).block('U can\'t touch this!');

      - OR -

      $.UltimaBlock.block(target, '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:

    1. verbose (native)
    2. shorthand (resolved)
    3. changing defaults
    1. var options = {

          css: {

              message: {

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

              }

          }

      }
      ;
    behavior
    zIndexInctrueincrement the zIndex for every parallel existing block
    css
    overlay
    className''class added to the overlay element
    zIndex9001
    < css property >any CSS property, will be set as inline style
    message
    className''class added to the message element
    offset
    x0horizontal position offset of the message element, in px
    y0vertical 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
    onBlockingundefinedbefore locking the target
    (UltimaBlock) : return false to interrupt
    onUnblockingundefinedbefore unlocking the target
    (UltimaBlock) : return false to interrupt

    // Examples

    You can test UltimaBlock in your browser console as well.

    demo : lock & unlock


    1. lock element
    2. unlock element

    // License

    MIT, Copyright (c) 2014-2018 Alexander Kwaschny, kwaschny.net

    // Download