{"id":18389610,"url":"https://github.com/anseki/jquery-plainmodal","last_synced_at":"2025-04-07T02:34:36.695Z","repository":{"id":12689170,"uuid":"15361420","full_name":"anseki/jquery-plainmodal","owner":"anseki","description":"The simple jQuery Plugin for fully customizable modal windows.","archived":false,"fork":false,"pushed_at":"2022-08-19T03:30:40.000Z","size":277,"stargazers_count":79,"open_issues_count":0,"forks_count":11,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-24T13:16:52.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://anseki.github.io/jquery-plainmodal/","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":"2013-12-21T15:55:27.000Z","updated_at":"2024-03-17T08:05:02.000Z","dependencies_parsed_at":"2022-08-31T00:01:55.860Z","dependency_job_id":null,"html_url":"https://github.com/anseki/jquery-plainmodal","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainmodal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainmodal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainmodal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fjquery-plainmodal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anseki","download_url":"https://codeload.github.com/anseki/jquery-plainmodal/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:57.330Z","updated_at":"2025-04-07T02:34:31.671Z","avatar_url":"https://github.com/anseki.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# jQuery-plainModal\n\n[![npm](https://img.shields.io/npm/v/jquery-plainmodal.svg)](https://www.npmjs.com/package/jquery-plainmodal) [![GitHub issues](https://img.shields.io/github/issues/anseki/jquery-plainmodal.svg)](https://github.com/anseki/jquery-plainmodal/issues) [![David](https://img.shields.io/david/anseki/jquery-plainmodal.svg)](package.json) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n***Recommend: [PlainModal](https://anseki.github.io/plain-modal/) instead of \"jQuery-plainModal\"***  \n*No dependency, Modern browsers supported, Lightweight \u0026 Single file, and more features*\n\n---\n\nThe simple jQuery Plugin for fully customizable modal windows. plainModal has basic functions only, and it does not style. It has no image files and no CSS files. Just one small file.\n\n**See \u003ca href=\"https://anseki.github.io/jquery-plainmodal/\"\u003eDEMO\u003c/a\u003e**\n\nMany great plugins already exist.\n\n* The gorgeous plugins which has many functions and rich styles.\n* The simple plugins which has small functions and customizable styles.\n\nplainModal has necessary functions for the modal windows. That's all. You can free style it to perfect match for your web site. Of course it can be responsive web design.\n\nplainModal does:\n\n* Showing the specified element as the modal window, and hiding it.\n* Covering a page with an overlay.\n* Avoiding focusing the outside elements of the modal window. (by pressing Tab key)\n* Avoiding scrolling a page window.\n* Hiding the modal window when Escape key is pressed.\n\n```js\n// Show modal window. \u003cdiv id=\"modal\"\u003e is styled via your CSS.\n$('#modal').plainModal('open');\n// Hide modal window.\n$('#modal').plainModal('close');\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.plainmodal.min.js\"\u003e\u003c/script\u003e\n```\n\n## Methods\n\n### `open`\n\n```js\nelement = element.plainModal('open'[, options])\n```\n\nShow the specified element as the modal window.  \nIf `options` (see [Options](#options)) is specified, the element is initialized with specified `options` before it 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### `close`\n\n```js\nelement = element.plainModal('close')\n```\n\nHide the shown modal window.\n\n### Initialize\n\n```js\nelement = element.plainModal([options])\n```\n\nInitialize the specified element as the modal window.  \nThe [`open`](#open) method too, can initialize. This is used to initialize without showing the modal window at voluntary time.  \nYou can specify `options` to every [`open`](#open) method. But, if `options` of an element isn't changed, re-initializing it isn't needed. Then, you specify `options` to only first [`open`](#open) 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 [`open`](#open) 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$('#open-button').click(function() {\n  // Same initializing per every showing\n  $('#modal').plainModal('open', {duration: 500});\n});\n```\n\nIn this code, it is initialized at once:\n\n```js\n// Initialize without showing\nvar modal = $('#modal').plainModal({duration: 500});\n$('#open-button').click(function() {\n  // Show without initializing\n  modal.plainModal('open');\n});\n```\n\nIn this code, it is initialized at once:\n\n```js\n$('#open-button').click(function() {\n  // Initialize at only first time\n  modal.plainModal('open');\n});\n```\n\n### `option`\n\n```js\ncurrentValue = element.plainModal('option', optionName)\n```\n\n```js\nelement = element.plainModal('option', optionName, newValue)\n```\n\n```js\nelement = element.plainModal('option', {\n  optionName1: newValue1,\n  optionName2: newValue2 ... \n})\n```\n\nGet the current option value (see [Options](#options)) of the modal window, or set the new value to the modal windows.\n\n*NOTE:* If you want to change the event handlers (see [Events](#events)), use `on` or `off` method.\n\n### `blur`\n\n```js\nelement = element.plainModal('blur'[, on[, duration[, complete]]])\n```\n\nLet the modal window go under the overlay. If `false` is specified to `on` argument, restore the modal window. The default is `true`.  \nThis method is used to just effect. Note that it works without depending on the current status of the modal window and it doesn't change the status. Therefore, you must restore it after.  \nFor example, you want to show something to the user while the modal window is shown, you let it blur temporarily and show something, and then you restore it after something.\n\n## Options\n\nAn `options` Object can be specified to [`open`](#open) or [Initialize](#initialize) method. It can have following properties.\n\n### `offset`\n\nType: Object or Function  \nDefault: Calculated center position\n\nAn Object that has `left` and `top`, relative to the view area.\n\n```js\n$('#modal').plainModal({offset: {left: 100, top: 50}});\n```\n\nOr, a Function that returns the above Object. This Function is called when the modal window is opened and the browser window is resized. Therefore the position be able to change according to the situation.\n\n```js\nvar button = $('#open-button').click(function() {\n      modal.plainModal('open');\n    }),\n    modal = $('#modal').plainModal({\n      offset: function() {\n        // Fit the position to a button.\n        var btnOffset = button.offset(), win = $(window);\n        return {\n          left:   btnOffset.left - win.scrollLeft()\n                    + parseInt(this.css('borderLeftWidth'), 10),\n          top:    btnOffset.top - win.scrollTop()\n                    + parseInt(this.css('borderTopWidth'), 10)\n        };\n      }\n    });\n```\n\nIf the Function returns nothing, the position isn't changed. In this case, that Function will change the position. For example, positioning by `margin` instead of `left`/`top`.  \nA `center` argument is given to the Function. It is a Function that moves the modal window to the center of the window. For example, your Function does something that changes a size of the modal window, and it calls a `center` to adjust a position.\n\n```js\n$('#modal').plainModal({\n  offset: function(center) {\n    // sizing by view port, step by 100px\n    var jqHtml = $('html'),\n      width = jqHtml.prop('clientWidth'),\n      height = jqHtml.prop('clientHeight');\n    width = width * 0.5;\n    height = height * 0.5;\n    width = Math.round(width / 100) * 100;\n    height = Math.round(height / 100) * 100;\n    if (width \u003c 100) { width = 100; }\n    if (height \u003c 100) { height = 100; }\n    this.width(width).height(height);\n    center(); // position to center.\n  }\n});\n```\n\n### `overlay`\n\nType: Object  \nDefault: `{fillColor: '#888', opacity: 0.6, zIndex: 9000}`\n\nAn Object that can have `fillColor`, `opacity` and `zIndex` of the overlay.\n\n```js\n$('#modal').plainModal({overlay: {fillColor: '#fff', opacity: 0.5}});\n```\n\n`color` is an alias for `fillColor`.\n\nIf you want to style the overlay more, add style to `plainmodal-overlay` class.\n\n```css\n.plainmodal-overlay {\n  background-image: url('bg.png');\n}\n```\n\n### `closeClass`\n\nType: String  \nDefault: `'plainmodal-close'`\n\nIf the element that has this class name is found in the modal window, the [`close`](#close) method is attached to `click` event of it.  \nYou can know that the element was clicked, via [`event.from`](#from).\n\n```html\n\u003cdiv\u003e\n  \u003cp\u003eLorem ipsum dolor ...\u003c/p\u003e\n  \u003cdiv class=\"plainmodal-close\"\u003eClose\u003c/div\u003e\n\u003c/div\u003e\n```\n\n### `duration`\n\nType: Number  \nDefault: `200`\n\nA number determining how long (milliseconds) the effect animation for showing and hiding the modal window will run.\n\n### `effect`\n\nType: Object  \nDefault: `{open: jQuery.fn.fadeIn, close: jQuery.fn.fadeOut}`\n\nAn Object that can have `open` and `close` Functions for showing and hiding the modal window.  \nThese Functions are called with [`options.duration`](#duration) Number (see above) and `complete` Function.  \nIt's same to standard effect methods of jQuery (`slideDown`, `slideUp`, `animate`, etc.). Therefore, those methods can be specified.\n\n```js\n$('#modal').plainModal({effect: {open: $.fn.slideDown, close: $.fn.slideUp}});\n```\n\nCustom animation:\n\n```js\n$('#modal').plainModal({\n  offset: {left: 300, top: 100},\n  duration: 500,\n  effect: {\n    open: function(duration, complete) {\n      this.css({\n        display:          'block',\n        marginTop:        -100 - this.outerHeight()\n      })\n      .animate({marginTop: 0}, duration, complete);\n    },\n    close: function(duration, complete) {\n      this.animate({\n        marginTop:        -100 - this.outerHeight()\n      }, duration, function() {\n        $(this).css({display: 'none'});\n        complete();\n      });\n    }\n  }\n});\n```\n\nThese Functions can ignore `duration`, but it must call `complete`, when the effect was finished.\n\n```js\n$('#modal').plainModal({\n  effect: {\n    open: function(duration, complete) {\n      var that = this.css({\n        display:          'block',\n        color:            '#fff',\n        backgroundColor:  '#f1e470'\n      });\n      setTimeout(function() {\n        that.css({color: '', backgroundColor: ''});\n        complete();\n      }, 500);\n    },\n    close: function(duration, complete) {\n      var that = this.css({\n        color:            '#fff',\n        backgroundColor:  '#f1e470'\n      });\n      setTimeout(function() {\n        that.css({display: 'none'});\n        complete();\n      }, 500);\n    }\n  }\n});\n```\n\n### `zIndex`\n\nType: Number  \nDefault: `options.overlay.zIndex + 1`\n\nA `z-index` CSS property of the modal window. This number have to be bigger than `zIndex` of [`options.overlay`](#overlay).\n\n### `child`\n\nType: jQuery object  \nDefault: `undefined`\n\nA child modal window or multiple child modal windows.  \nA parent modal window is already opened, and then a child modal window is opened. Now, a child modal window is activated and a parent modal window is blurred (status is \"closed\" but it is not hidden). And when a child modal window is closed, a parent modal window is activated again (re-opened).  \nYou can trace or control those behavior via [`event.from`](#from).\n\n```js\nvar child = $('#child').plainModal(),\n  parent = $('#parent').plainModal({child: child});\n\n$('#main-button').click(function() { parent.plainModal('open'); });\n$('#button-in-parent').click(function() { child.plainModal('open'); });\n```\n\n### `force`\n\nType: Boolean  \nDefault: `false`\n\nThe only one modal window can open in the one window. Therefore the [`open`](#open) method is ignored when another modal window is already opened.  \nIf the [`open`](#open) method of the modal window that is set `true` to `force` is called when another modal window is already opened, another modal window is closed immediately, and the target modal window is opened.  \nYou can trace or control those behavior via [`event.from`](#from).\n*If you want to let the modal windows behave like the parent and child, you should consider [`options.child`](#child).*\n\n```js\nvar modal1 = $('#modal1').plainModal(),\n  modal2 = $('#modal2').plainModal({force: true});\n```\n\n### `fixOverlay`\n\nType: Boolean  \nDefault: `false`\n\nIf `true` is specified, the effects for showing and hiding the overlay are avoided.  \nFor example, this is used to close a modal window and open another modal window, without a screen flickering. Note that the overlay stays when the modal window is closed before this option is reset to `false`.\n\n### `open`, `close`, `beforeopen`, `beforeclose`\n\nType: Function  \nDefault: `undefined`\n\nThe [`plainmodalopen`](#plainmodalopen), [`plainmodalclose`](#plainmodalclose), [`plainmodalbeforeopen`](#plainmodalbeforeopen) and [`plainmodalbeforeclose`](#plainmodalbeforeclose) event handlers. This is convenient way to do `on(type, handler)` method. (see [Events](#events))\n\n```js\n$('#modal').plainModal({open: function(event) { console.log(event); } });\n```\n\n*NOTE:* If this option is specified in the [`open`](#open) method, declared Function or the variable the Function is assigned should be specified (Don't specify the function expression). Because the [`open`](#open) 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$('#open-button').click(function() {\n  $('#modal').plainModal('open', {open: handler});\n});\n```\n\nThis code registers event handler repeatedly when the [`open`](#open) method is called:\n\n```js\n$('#open-button').click(function() {\n  $('#modal').plainModal('open', {open: function(event) { console.log(event); } });\n});\n```\n\n## Events\n\n### `plainmodalopen`\n\nTriggered when the modal window is opened. (after the `open` of [`options.effect`](#effect) took [`options.duration`](#duration) to complete.)  \nAn event handler can be attached when initializing via [`options.open`](#open-close-beforeopen-beforeclose) as well.  \nThe Event object that is passed to the event handler might have a [`from`](#from) property.\n\n```js\n$('#modal').on('plainmodalopen', function(event) {\n  $('textarea', event.target).addClass('highlight');\n});\n```\n\n### `plainmodalclose`\n\nTriggered when the modal window is closeed. (after the `close` of [`options.effect`](#effect) took [`options.duration`](#duration) to complete.)  \nAn event handler can be attached when initializing via [`options.close`](#open-close-beforeopen-beforeclose) as well.  \nThe Event object that is passed to the event handler might have a [`from`](#from) property.\n\n```js\n$('#modal').on('plainmodalclose', function(event) {\n  $('#screen').show();\n});\n```\n\n### `plainmodalbeforeopen`\n\nTriggered before the modal window is opened.  \nAn event handler can be attached when initializing via [`options.beforeopen`](#open-close-beforeopen-beforeclose) as well.  \nThe Event object that is passed to the event handler might have a [`from`](#from) property.\n\nThis event might be cancelable by calling `event.preventDefault()` in an event handler. The `plainmodalbeforeopen` event of the second modal window by [`options.child`](#child) or [`options.force`](#force) is not cancelable. Call `event.preventDefault()` in [`plainmodalbeforeclose`](#plainmodalbeforeclose) event of the first (i.e. parent) modal window to cancel that action.  \nYou can know whether or not it is cancelable, via whether or not `event.cancelable` is `true`.\n\n```js\n$('#modal').on('plainmodalbeforeopen', function(event) {\n  if (!dataList.ready) {\n    event.preventDefault(); // Don't open yet.\n  }\n});\n```\n\n### `plainmodalbeforeclose`\n\nTriggered before the modal window is closeed.  \nAn event handler can be attached when initializing via [`options.beforeclose`](#open-close-beforeopen-beforeclose) as well.  \nThe Event object that is passed to the event handler might have a [`from`](#from) property.\n\nThis event is cancelable by calling `event.preventDefault()` in an event handler.\n\n```js\n$('#modal').on('plainmodalbeforeclose', function(event) {\n  if (elmUserName.val() === '') {\n    alert('\"User Name\" is required.');\n    event.preventDefault(); // Stay opening.\n  }\n});\n```\n\n### Properties\n\nThe Event object that is passed to the event handler might have additional properties.\n\n#### `from`\n\nIn some cases, the modal window is opened or closed without you calling [`open`](#open) method or [`close`](#close) method. For example, when the overlay or the button which is specified [`options.closeClass`](#closeclass) is clicked. Or the parent modal window is closed when the child modal window is closed. (See [`options.child`](#child))  \nIn those cases, the Event object that is passed to the event handler has the `from` property. It refers to:\n\n* The Event object of another event, when the overlay or the button that is specified [`options.closeClass`](#closeclass) is clicked (`click` event), or Escape key is pressed (`keydown` event). In the [`plainmodalclose`](#plainmodalclose) or [`plainmodalbeforeclose`](#plainmodalbeforeclose) event handler.\n* The child modal window, when it is opened. In the [`plainmodalclose`](#plainmodalclose) or [`plainmodalbeforeclose`](#plainmodalbeforeclose) event handler of the parent modal window.\n* The child modal window, when it is closed. In the [`plainmodalopen`](#plainmodalopen) or [`plainmodalbeforeopen`](#plainmodalbeforeopen) event handler of the parent modal window.\n* The another modal window that `true` is specified to [`options.force`](#force), when it is opened. In the [`plainmodalclose`](#plainmodalclose) or [`plainmodalbeforeclose`](#plainmodalbeforeclose) event handler of the modal window that is closed by that action.\n\n```js\nvar\n  modal1 = $('#modal1').plainModal({duration: 500})\n\n  .on('plainmodalbeforeclose', function(event) {\n    var from = event.from, orgDuration, offset;\n    if (!from) { return; }\n\n    if (from.type === 'keydown') {\n      // If the user pushed the Escape key, (s)he is in a hurry.\n      orgDuration = modal1.plainModal('option', 'duration');\n      modal1.one('plainmodalclose', function() {\n          modal1.plainModal('option', 'duration', orgDuration); // Restore\n        })\n        .plainModal('option', 'duration', 1); // Set to fast closing\n\n    } else if (from.type === 'click' \u0026\u0026\n        from.currentTarget.className === 'plainmodal-overlay') {\n      // If the user clicked the overlay that is too short\n      // distance from this small modal, (s)he might have mistaken.\n      // And ignore clicking.\n      offset = modal1.offset();\n      if (from.clientX \u003e= offset.left - 20 \u0026\u0026\n          from.clientX \u003c= offset.left + modal1.outerWidth() + 20 \u0026\u0026\n          from.clientY \u003e= offset.top -20 \u0026\u0026\n          from.clientY \u003c= offset.top + modal1.outerHeight() + 20) {\n        event.preventDefault(); // Stay opening.\n      }\n\n    } else if (from.jquery) { // This is jQuery object. i.e. another modal.\n      // The another modal takes over this message.\n      from.find('.warning-message').text(modal1.find('.warning-message').text());\n    }\n  });\n```\n\n#### `isChild`\n\nA `true` is set, when a current modal window is handled as the child modal window.\n\n## Note\n\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 plainModal is not used. And plainModal uses `position:fixed`.\n* The [Initialize](#initialize) method set `display:none` to specified element. You can hide the element before Initialize method, by your stylesheet.\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-plainmodal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanseki%2Fjquery-plainmodal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Fjquery-plainmodal/lists"}