jQuery-plainOverlay

npm GitHub issues David license

Recommend: PlainOverlay instead of "jQuery-plainOverlay"
No dependency, Modern browsers supported, Lightweight & Single file, and more features

The simple jQuery Plugin for customizable overlay which covers a page, the elements or the iframe-windows that is specified. jQuery-plainOverlay has basic functions only, and it has no image files and no CSS files. Just one small file.

jQuery.plainOverlay

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

CSS Animations (or JavaScript)

jQuery.plainOverlay

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

SVG Animations via progress option

This is used for making the users wait until the your application is ready.
The elements under the overlay don't accept access via mouse or keyboard. And the scrollable elements (e.g. <body>, <div style="overflow:scroll"> or <iframe>) which are specified can't scroll.

<iframe>

<body>

The your progress-element (messages or images that means "Please wait...") can be shown to the users on the overlay. You can free style it to perfect match for your web site. Or jQuery-plainOverlay has a simple builtin progress-element.

jQuery-plainOverlay does:

// Cover an element with overlay.
$('#post-form').plainOverlay('show');
// Hide overlay.
$('#post-form').plainOverlay('hide');

// Cover all of a page.
$('body').plainOverlay('show'); // Or, $(document), $(window)

Getting Started

Load after jQuery.

<script src="jquery-1.11.0.min.js"></script>
<script src="jquery.plainoverlay.min.js"></script>

Methods

show

element = element.plainOverlay('show'[, options])

Cover the specified element with the overlay. This element may be <body>, <iframe> or a box-element like <div>. $(document) and $(window) are same as $('body').
If options (see Options) is specified, the element is initialized with specified options before the overlay is shown. If the element is not initialized yet, it is initialized even if options is not specified (with the default options).
The element can be initialized by new options any number of times.

hide

element = element.plainOverlay('hide'[, ignoreComplete])

Hide the overlay.

By default, behavior restrictions of the element (e.g. scrolling) are removed after the fading effect took options.duration to complete. (i.e. after the overlay was hidden completely.)
If true is specified to ignoreComplete, the restrictions are removed when hide method is called, and plainoverlayhide event is triggered.
For example, this is used to do something about the element (e.g. changing scroll position) while the overlay is shown.

Initialize

element = element.plainOverlay([options])

Initialize the specified element. (preparation the overlay)
The show method too, can initialize. This is used to initialize without showing the overlay at voluntary time.
You can specify options to every show method. But, if options of an element isn't changed, re-initializing it isn't needed. Then, you specify options to only first show method, or use this method for initializing it only once.
If you don't customize any options (using default all), this method isn't needed because options isn't specified to show method, and the element is initialized at only first time.

In this code, it is initialized meaninglessly again, again, and again:

$('#show-button').click(function() {
  // Same initializing per every showing
  $('#list').plainOverlay('show', {duration: 500});
});

In this code, it is initialized at once:

// Initialize without showing
var list = $('#list').plainOverlay({duration: 500});
$('#show-button').click(function() {
  // Show without initializing
  list.plainOverlay('show');
});

In this code, it is initialized at once:

$('#show-button').click(function() {
  // Initialize at only first time
  list.plainOverlay('show');
});

option

currentValue = element.plainOverlay('option', optionName[, newValue])

Return the current option value (see Options) as optionName. If newValue is specified, it is set before returning.

NOTE: The current version of the jQuery-plainOverlay can change option value of duration and opacity options. Use Initialize method to update option value of others.

scrollLeft, scrollTop

element = element.plainOverlay('scrollLeft', scrollLen)

element = element.plainOverlay('scrollTop', scrollLen)

jQuery-plainOverlay avoid scrolling the element. These methods are used instead of element.scrollLeft and element.scrollTop methods to scroll the element while the overlay is shown.

For example:

$('body').plainOverlay('show', {
  show: function(event) {
    // Now, the overlay is shown. The user can't scroll the page.
    // Do something...
    // Scroll the page to show something.
    $('body').plainOverlay('scrollLeft', 100).plainOverlay('scrollTop', 400)
      // And hide the overlay.
      .plainOverlay('hide');
  }
});

Options

An options Object can be specified to show or Initialize method. It can have following properties.

duration

Type: Number
Default: 200

A number determining how long (milliseconds) the effect animation for showing and hiding the overlay will run.

fillColor

Type: String
Default: '#888'

A fill-color of the overlay.

$('#list').plainOverlay({fillColor: 'red'});

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

color is an alias for fillColor.

opacity

Type: Number
Default: 0.6

A number in the range 0.0 (invisible) to 1.0 (solid).

$('#list').plainOverlay({opacity: 0.3});

If you want to style the overlay more, add style to plainoverlay class.

.plainoverlay {
  background-image: url('bg.png');
}

progress

Type: Function or Boolean
Default: Builtin Element

The jQuery-Element that is returned by specified Function is shown to the users as the progress-element on the overlay. This is usually the messages or images that means "Please wait...".
If false is specified, nothing is shown on the overlay.
The builtin element (default) is shown via CSS Animations in modern browsers (e.g. Firefox, Chrome, etc.), and it is shown via simple effect in legacy browsers (IE9, IE8, etc.). This choice is automatic.

$('#list').plainOverlay({
  progress: function() { return $('<div>I am busy...</div>'); }
});

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Of course your image files, some CSS codes which are distributed free in the internet, or any elements can be used. (e.g. SVG Animations jxnblk/loading)

If you want to change the color of shapes in the builtin progress-element, use CSS below.

/* Change to red */
.jQuery-plainOverlay-progress {
  border-color: red !important;
}
.jQuery-plainOverlay-progress-legacy div {
  background-color: red !important;
}

zIndex

Type: Number
Default: 9000

A z-index CSS property of the overlay.

show, hide

Type: Function
Default: undefined

The plainoverlayshow and plainoverlayhide event handlers. This is convenient way to do on(type, handler) method. (see Events)

$('#form1').plainOverlay({show: function(event) { console.log(event); } });

NOTE: If this option is specified in the show method, declared Function or the variable the Function is assigned should be specified (Don't specify the function expression). Because the show method may be called again, and the function expression generates the new Function every time.
The "function statement" and the "function operator" are different.
See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions#Defining_functions
For example, this code is OK:

function handler(event) { console.log(event); }
$('#show-button').click(function() {
  $('#form1').plainOverlay('show', {show: handler});
});

This code registers event handler repeatedly when the show method is called:

$('#show-button').click(function() {
  $('#form1').plainOverlay('show', {show: function(event) { console.log(event); } });
});

Events

plainoverlayshow

Triggered when the overlay is shown. (after the fading effect took options.duration to complete.)
An event handler can be attached when initializing via options.show as well.

$('#form1').on('plainoverlayshow', function(event) {
  $('#loading', event.target).text(size + ' Bytes Downloading');
});

plainoverlayhide

Triggered when the overlay is hidden.
By default, it is triggered after the fading effect took options.duration to complete. If hide method is called with ignoreComplete argument, it is triggered when hide method is called.
An event handler can be attached when initializing via options.hide as well.

$('#form1').on('plainoverlayhide', function(event) {
  $('#complete-message').show();
});

Note

See Also