PlainOverlay

npm GitHub issues dependencies license

The simple library for customizable overlay which covers all or part of a web page.

Features:

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

<div>

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

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

window
(5s)
window Customize with LeaderLine
(5s)
The button you clicked

One of the following can be specified as the target that is covered:

<form>
<textarea>
<img>
ex-020.jpg
<table>
<td>
<td>
inner <p>

Usage

Load PlainOverlay into your web page.

<script src="plain-overlay.min.js"></script>

This is simplest case:

PlainOverlay.show(); // Static method

Now, new overlay is shown and all of the page are covered with it.
You can specify an element as the target that is covered.

PlainOverlay.show(element); // element is covered

Use an instance method to hide the overlay.

var overlay = PlainOverlay.show();
// Now, new overlay is shown.
// Do something ...
overlay.hide();
// Now, the overlay is hidden.

For options and more details, refer to the following.

Constructor

overlay = new PlainOverlay([target][, options])

The target argument is an element that will be covered with the overlay, or window (or document or <html> or <body>) that means all of the web page.
Any element that has a bounding-box is accepted. It can be an element in another window (i.e. <iframe>). <iframe> is regarded as window of that <iframe>.
The default of target argument is current window.

The options argument is an Object that can have properties as options. You can also change the options by setOptions or show methods or properties of the PlainOverlay instance.

For example:

// Cover all of the web page, with `duration` option
var overlay = new PlainOverlay({duration: 400});

// Cover a part of the web page, with `face` option
var overlay = new PlainOverlay(document.getElementById('form'), {face: false});

See also: PlainOverlay.show

When you will do something about HTML document regardless of the PlainOverlay, you typically do that after the HTML document is ready (i.e. the HTML document has been loaded and parsed by web browser).
For example:

// Wait for HTML document to get ready
window.addEventListener('load', function() { // NOT `DOMContentLoaded`
  // Do something about HTML document
  var overlay = new PlainOverlay(document.getElementById('form'));
});

If you don't wait for HTML document to be ready, you might not be able to get a target element yet, or problems with incomplete layout may occur. Also, you should do so asynchronous like the above for the performance because synchronous code blocks parsing HTML.

Methods

show

self = overlay.show([force][, options])

Show the overlay.
If true is specified for force argument, show it immediately without an effect. (As to the effect, see duration option.)
If options argument is specified, call setOptions method and show the overlay. It works the same as:

overlay.setOptions(options).show();

See also: PlainOverlay.show

hide

self = overlay.hide([force])

Hide the overlay.
If true is specified for force argument, hide it immediately without an effect. (As to the effect, see duration option.)

setOptions

self = overlay.setOptions(options)

Set one or more options.
The options argument is an Object that can have properties as options.

scrollLeft, scrollTop

currentLeft = overlay.scrollLeft([newLeft[, scrollTarget]])

currentTop = overlay.scrollTop([newTop[, scrollTarget]])

Scrolling a window or element is blocked while it is covered with the overlay. scrollLeft and scrollTop methods allow it scroll, and return current value.
The value is a number of pixels that a content is scrolled to the left or upward.
The default of scrollTarget is a target of the overlay.

position

self = overlay.position()

Update the position of the overlay that covers a part of a web page.
If target is a part of a web page, the overlay is shown at the same position as the target, and it is re-positioned (and resized) as needed automatically when a window that contains the target is resized.
You should call position method if you moved or resized the target without resizing the window.

Options

face

Type: Element, boolean or undefined
Default: undefined (Builtin Face)

Something that is shown on the overlay. This is usually a message or image that means "Please wait...".
If false is specified, nothing is shown on the overlay.

For example, a message:

<div id="message">Please wait...</div>

var overlay = new PlainOverlay({face: document.getElementById('message')});
(5s)
Please wait...

For example, an image:

<img id="image" src="loading.svg">

var overlay = new PlainOverlay({face: document.getElementById('image')});
(5s)

For example, an inline SVG:

<svg id="svg" version="1.1">
  <!-- ... -->
</svg>

var overlay = new PlainOverlay({face: document.getElementById('svg')});
(10s)

duration

Type: number
Default: 200

A number determining how long (milliseconds) the effect (fade-in/out) animation for showing and hiding the overlay will run.

blur

Type: number or boolean
Default: false

Applies a Gaussian blur to the target while the overlay is shown. Note that the current browser might not support it.
It is not applied if false is specified.

For example:

overlay.blur = 3;

style

Type: Object or undefined
Default: undefined

An Object that can have CSS properties that are added to the overlay.

Major properties of default style:

{
  backgroundColor: 'rgba(136, 136, 136, 0.6)',
  cursor: 'wait',
  zIndex: 9000
}

For example, whity overlay:

var overlay = new PlainOverlay({style: {backgroundColor: 'rgba(255, 255, 255, 0.6)'}});
(5s)

Note that some properties that affect the layout (e.g. width, border, etc.) might not work or those might break the overlay.

If you want to change the default style (i.e. style of all overlay in the web page), you can define style rules with .plainoverlay class in your style-sheet.

For example, CSS rule-definition:

.plainoverlay {
  background-color: rgba(255, 255, 255, 0.6);
}

onShow, onHide, onBeforeShow, onBeforeHide

Type: function or undefined
Default: undefined

Event listeners:

In the functions, this refers to the current PlainOverlay instance.

For example:

var overlay = new PlainOverlay({
  onBeforeShow: function() {
    if (name.value) {
      this.face.className = 'anim'; // Start animation
    } else {
      alert('Please input your name');
      return false; // Cancel the showing the overlay.
    }
  },
  onHide: function() {
    this.face.className = ''; // Stop animation
  }
});

onPosition

Type: function or undefined
Default: undefined

A position event listener that is called when the overlay is shown (before a showing effect starts), a window that contains the target is resized, and position method is called.
In the function, this refers to the current PlainOverlay instance.

This is used to adjust your custom face that depends on a layout of the overlay.

Properties

state

Type: number
Read-only

A number to indicate current state of the overlay.
It is one of the following static constant values:

For example:

toggleButton.addEventListener('click', function() {
  if (overlay.state === PlainOverlay.STATE_HIDDEN ||
      overlay.state === PlainOverlay.STATE_HIDING) {
    overlay.show();
  } else {
    overlay.hide();
  }
}, false);

style

Type: CSSStyleDeclaration
Read-only

A CSSStyleDeclaration object of the overlay to get or set the CSS properties.

For example:

overlay.style.backgroundImage = 'url(bg.png)';
(5s)

blockingDisabled

Type: boolean
Default: false

By default, user operation such as scrolling, focusing and selecting text is blocked.
If you want, set true for this property to disable this behavior.

face

Get or set face option.

For example, change it while the overlay is shown:

overlay.show({
  face: progressBar,
  onShow: function() {
    setTimeout(function() {
      overlay.face = countDown;
    }, 3000);
  }
});
(5s)

duration

Get or set duration option.

blur

Get or set blur option.

onShow, onHide, onBeforeShow, onBeforeHide, onPosition

Get or set onShow, onHide, onBeforeShow, onBeforeHide, and onPosition options.

PlainOverlay.show

overlay = PlainOverlay.show([target][, options])

This static method is a shorthand for:

(new PlainOverlay(target, options)).show()

See Also

Thanks for images: arian.suresh, jxnblk/loading, The Pattern Library, tobiasahlin/SpinKit