{"id":18389615,"url":"https://github.com/anseki/jquery-plainoverlay","last_synced_at":"2025-04-07T02:34:36.655Z","repository":{"id":14132337,"uuid":"16837739","full_name":"anseki/jquery-plainoverlay","owner":"anseki","description":"The simple jQuery Plugin for customizable overlay which covers a page, elements or iframe-windows that is specified.","archived":false,"fork":false,"pushed_at":"2022-08-19T03:35:02.000Z","size":206,"stargazers_count":61,"open_issues_count":0,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-14T09:38:36.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://anseki.github.io/jquery-plainoverlay/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anseki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-14T13:19:11.000Z","updated_at":"2022-08-19T03:34:28.000Z","dependencies_parsed_at":"2022-09-05T11:31:01.455Z","dependency_job_id":null,"html_url":"https://github.com/anseki/jquery-plainoverlay","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainoverlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainoverlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainoverlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainoverlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anseki","download_url":"https://codeload.github.com/anseki/jquery-plainoverlay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T01:43:58.131Z","updated_at":"2025-04-07T02:34:31.636Z","avatar_url":"https://github.com/anseki.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jQuery-plainOverlay\n\n[![npm](https://img.shields.io/npm/v/jquery-plainoverlay.svg)](https://www.npmjs.com/package/jquery-plainoverlay) [![GitHub issues](https://img.shields.io/github/issues/anseki/jquery-plainoverlay.svg)](https://github.com/anseki/jquery-plainoverlay/issues) [![David](https://img.shields.io/david/anseki/jquery-plainoverlay.svg)](package.json) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n***Recommend: [PlainOverlay](https://anseki.github.io/plain-overlay/) instead of \"jQuery-plainOverlay\"***  \n*No dependency, Modern browsers supported, Lightweight \u0026 Single file, and more features*\n\n---\n\nThe 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.\n\n**See \u003ca href=\"https://anseki.github.io/jquery-plainoverlay/\"\u003eDEMO\u003c/a\u003e**\n\nThis is used for making the users wait until the your application is ready.  \nThe elements under the overlay don't accept access via mouse or keyboard. And the scrollable elements (e.g. `\u003cbody\u003e`, `\u003cdiv style=\"overflow:scroll\"\u003e` or `\u003ciframe\u003e`) which are specified can't scroll.\n\nThe 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.\n\njQuery-plainOverlay does:\n\n* Covering a page, the elements or the iframe-windows that is specified with the overlay.\n* Avoiding focusing the elements under the overlay. (by pressing Tab key)\n* Avoiding scrolling a page, the elements or the iframe-windows that is specified.\n\n```js\n// Cover an element with overlay.\n$('#post-form').plainOverlay('show');\n// Hide overlay.\n$('#post-form').plainOverlay('hide');\n\n// Cover all of a page.\n$('body').plainOverlay('show'); // Or, $(document), $(window)\n```\n\n## Getting Started\nLoad after jQuery.\n\n```html\n\u003cscript src=\"jquery-1.11.0.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"jquery.plainoverlay.min.js\"\u003e\u003c/script\u003e\n```\n\n## Methods\n\n### `show`\n\n```js\nelement = element.plainOverlay('show'[, options])\n```\n\nCover the specified element with the overlay. This element may be `\u003cbody\u003e`, `\u003ciframe\u003e` or a box-element like `\u003cdiv\u003e`. `$(document)` and `$(window)` are same as `$('body')`.  \nIf `options` (see [Options](#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).  \nThe element can be initialized by new `options` any number of times.\n\n### `hide`\n\n```js\nelement = element.plainOverlay('hide'[, ignoreComplete])\n```\n\nHide the overlay.\n\nBy default, behavior restrictions of the element (e.g. scrolling) are removed after the fading effect took [`options.duration`](#duration) to complete. (i.e. after the overlay was hidden completely.)  \nIf `true` is specified to `ignoreComplete`, the restrictions are removed when `hide` method is called, and [`plainoverlayhide`](#plainoverlayhide) event is triggered.  \nFor example, this is used to do something about the element (e.g. changing scroll position) while the overlay is shown.\n\n### Initialize\n\n```js\nelement = element.plainOverlay([options])\n```\n\nInitialize the specified element. (preparation the overlay)  \nThe [`show`](#show) method too, can initialize. This is used to initialize without showing the overlay at voluntary time.  \nYou can specify `options` to every [`show`](#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`](#show) method, or use this method for initializing it only once.  \nIf you don't customize any options (using default all), this method isn't needed because `options` isn't specified to [`show`](#show) method, and the element is initialized at only first time.\n\nIn this code, it is initialized meaninglessly again, again, and again:\n\n```js\n$('#show-button').click(function() {\n  // Same initializing per every showing\n  $('#list').plainOverlay('show', {duration: 500});\n});\n```\n\nIn this code, it is initialized at once:\n\n```js\n// Initialize without showing\nvar list = $('#list').plainOverlay({duration: 500});\n$('#show-button').click(function() {\n  // Show without initializing\n  list.plainOverlay('show');\n});\n```\n\nIn this code, it is initialized at once:\n\n```js\n$('#show-button').click(function() {\n  // Initialize at only first time\n  list.plainOverlay('show');\n});\n```\n\n### `option`\n\n```js\ncurrentValue = element.plainOverlay('option', optionName[, newValue])\n```\n\nReturn the current option value (see [Options](#options)) as `optionName`. If `newValue` is specified, it is set before returning.\n\n*NOTE:* The current version of the jQuery-plainOverlay can change option value of [`duration`](#duration) and [`opacity`](#opacity) options. Use [Initialize](#initialize) method to update option value of others.\n\n### `scrollLeft`, `scrollTop`\n\n```js\nelement = element.plainOverlay('scrollLeft', scrollLen)\n```\n\n```js\nelement = element.plainOverlay('scrollTop', scrollLen)\n```\n\njQuery-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.\n\nFor example:\n\n```js\n$('body').plainOverlay('show', {\n  show: function(event) {\n    // Now, the overlay is shown. The user can't scroll the page.\n    // Do something...\n    // Scroll the page to show something.\n    $('body').plainOverlay('scrollLeft', 100).plainOverlay('scrollTop', 400)\n      // And hide the overlay.\n      .plainOverlay('hide');\n  }\n});\n```\n\n## Options\n\nAn `options` Object can be specified to [`show`](#show) or [Initialize](#initialize) method. It can have following properties.\n\n### `duration`\n\nType: Number  \nDefault: `200`\n\nA number determining how long (milliseconds) the effect animation for showing and hiding the overlay will run.\n\n### `fillColor`\n\nType: String  \nDefault: `'#888'`\n\nA fill-color of the overlay.\n\n```js\n$('#list').plainOverlay({fillColor: 'red'});\n```\n\n`color` is an alias for `fillColor`.\n\n### `opacity`\n\nType: Number  \nDefault: `0.6`\n\nA number in the range `0.0` (invisible) to `1.0` (solid).\n\n```js\n$('#list').plainOverlay({opacity: 0.3});\n```\n\nIf you want to style the overlay more, add style to `plainoverlay` class.\n\n```css\n.plainoverlay {\n  background-image: url('bg.png');\n}\n```\n\n### `progress`\n\nType: Function or Boolean  \nDefault: Builtin Element\n\nThe 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...\".  \nIf `false` is specified, nothing is shown on the overlay.  \nThe 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.\n\n```js\n$('#list').plainOverlay({\n  progress: function() { return $('\u003cdiv\u003eI am busy...\u003c/div\u003e'); }\n});\n```\n\nOf 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](https://github.com/jxnblk/loading))\n\nIf you want to change the color of shapes in the builtin progress-element, use CSS below.\n\n```css\n/* Change to red */\n.jQuery-plainOverlay-progress {\n  border-color: red !important;\n}\n.jQuery-plainOverlay-progress-legacy div {\n  background-color: red !important;\n}\n```\n\n### `zIndex`\n\nType: Number  \nDefault: `9000`\n\nA `z-index` CSS property of the overlay.\n\n### `show`, `hide`\n\nType: Function  \nDefault: `undefined`\n\nThe [`plainoverlayshow`](#plainoverlayshow) and [`plainoverlayhide`](#plainoverlayhide) event handlers. This is convenient way to do `on(type, handler)` method. (see [Events](#events))\n\n```js\n$('#form1').plainOverlay({show: function(event) { console.log(event); } });\n```\n\n*NOTE:* If this option is specified in the [`show`](#show) method, declared Function or the variable the Function is assigned should be specified (Don't specify the function expression). Because the [`show`](#show) method may be called again, and the *function expression* generates the new Function every time.  \nThe *\"function statement\"* and the *\"function operator\"* are different.  \nSee [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions#Defining_functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions#Defining_functions)  \nFor example, this code is OK:\n\n```js\nfunction handler(event) { console.log(event); }\n$('#show-button').click(function() {\n  $('#form1').plainOverlay('show', {show: handler});\n});\n```\n\nThis code registers event handler repeatedly when the [`show`](#show) method is called:\n\n```js\n$('#show-button').click(function() {\n  $('#form1').plainOverlay('show', {show: function(event) { console.log(event); } });\n});\n```\n\n## Events\n\n### `plainoverlayshow`\n\nTriggered when the overlay is shown. (after the fading effect took [`options.duration`](#duration) to complete.)  \nAn event handler can be attached when initializing via [`options.show`](#show-hide) as well.\n\n```js\n$('#form1').on('plainoverlayshow', function(event) {\n  $('#loading', event.target).text(size + ' Bytes Downloading');\n});\n```\n\n### `plainoverlayhide`\n\nTriggered when the overlay is hidden.  \nBy default, it is triggered after the fading effect took [`options.duration`](#duration) to complete. If [`hide`](#hide) method is called with `ignoreComplete` argument, it is triggered when `hide` method is called.  \nAn event handler can be attached when initializing via [`options.hide`](#show-hide) as well.\n\n```js\n$('#form1').on('plainoverlayhide', function(event) {\n  $('#complete-message').show();\n});\n```\n\n## Note\n\n- If target is `\u003ciframe\u003e` element, jQuery 1.10.3+ or 2.0.4+ must be used. (see [#14180: focusin/out special events don't work cross-window](http://bugs.jquery.com/ticket/14180))\n- As everyone knows, IE8- has many problems. CSS `position:fixed` in HTML without `\u003c!DOCTYPE\u003e` is ignored.  \nIf your web site supports IE8- and it use `position:fixed`, HTML must include `\u003c!DOCTYPE\u003e` even if jQuery-plainOverlay is not used. And jQuery-plainOverlay uses `position:fixed`.\n- [`plainoverlayshow`](#plainoverlayshow) and [`plainoverlayhide`](#plainoverlayhide) events bubble up the DOM hierarchy.\n\n## See Also\n\n- [PlainOverlay](https://anseki.github.io/plain-overlay/) : The simple library for customizable overlay which covers all or part of a web page.\n- [PlainModal](https://anseki.github.io/plain-modal/) : The simple library for fully customizable modal window in a web page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Fjquery-plainoverlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanseki%2Fjquery-plainoverlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Fjquery-plainoverlay/lists"}