plain-overlay

v1.4.17

Published

2 years ago

The simple library for customizable overlay which covers a page, elements or iframe-windows.

Downloads

497

0High
0Medium
0Low

anseki

overlay busy loading form input progress ui simple customizable iframe window

PlainOverlay

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

Document and Examples https://anseki.github.io/plain-overlay/

Features:

Cover all or part of a web page with an overlay.
Block scrolling anything under the overlay by a mouse or keys.
Block focusing anything under the overlay by a mouse or Tab key or access-keys.
Show something like a loading-animation on the overlay.
No dependency.
Single file.
Modern browsers are supported. (If you want to support legacy browsers such as IE 9-, see jQuery-plainOverlay.)

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

A current window
An element that has a bounding-box
Another window (i.e. child window such as <iframe>)
An element in another window

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});

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();

`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')});

For example, an image:

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

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

For example, an inline SVG:

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

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

`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)'}});

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:

onBeforeShow is called when the overlay is about to be shown. If false is returned, the showing is canceled.
onShow is called when a showing effect of the overlay is finished.
onBeforeHide is called when the overlay is about to be hidden. If false is returned, the hiding is canceled.
onHide is called when a hiding effect of the overlay is finished.

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:

PlainOverlay.STATE_HIDDEN (0): The overlay is being hiding fully.
PlainOverlay.STATE_SHOWING (1): A showing effect of the overlay is running.
PlainOverlay.STATE_SHOWN (2): The overlay is being showing fully.
PlainOverlay.STATE_HIDING (3): A hiding effect of the overlay is running.

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)';

`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);
  }
});

`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()

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PlainOverlay

Usage

Constructor

Methods

show

hide

setOptions

scrollLeft, scrollTop

position

Options

face

duration

blur

style

onShow, onHide, onBeforeShow, onBeforeHide

onPosition

Properties

state

style

blockingDisabled

face

duration

blur

onShow, onHide, onBeforeShow, onBeforeHide, onPosition

PlainOverlay.show

See Also

`show`

`hide`

`setOptions`

`scrollLeft`, `scrollTop`

`position`

`face`

`duration`

`blur`

`style`

`onShow`, `onHide`, `onBeforeShow`, `onBeforeHide`

`onPosition`

`state`

`style`

`blockingDisabled`

`face`

`duration`

`blur`

`onShow`, `onHide`, `onBeforeShow`, `onBeforeHide`, `onPosition`

`PlainOverlay.show`