jQuery-plainModal

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

---

The 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.

See DEMO

Many great plugins already exist.

• The gorgeous plugins which has many functions and rich styles.
• The simple plugins which has small functions and customizable styles.

plainModal 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.

plainModal does:

• Showing the specified element as the modal window, and hiding it.
• Covering a page with an overlay.
• Avoiding focusing the outside elements of the modal window. (by pressing Tab key)
• Avoiding scrolling a page window.
• Hiding the modal window when Escape key is pressed.

// Show modal window. 

 is styled via your CSS.
$('#modal').plainModal('open');
// Hide modal window.
$('#modal').plainModal('close');

Getting Started

Load after jQuery.

<script src="https://github.com/anseki/jquery-plainmodal/raw/1.0.1/jquery-1.11.0.min.js"></script>
<script src="https://github.com/anseki/jquery-plainmodal/raw/1.0.1/jquery.plainmodal.min.js"></script>

Methods

open

element = element.plainModal('open'[, options])

Show the specified element as the modal window.
If options (see 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).
The element can be initialized by new options any number of times.

close

element = element.plainModal('close')

Hide the shown modal window.

Initialize

element = element.plainModal([options])

Initialize the specified element as the modal window.
The open method too, can initialize. This is used to initialize without showing the modal window at voluntary time.
You can specify options to every 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 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 open method, and the element is initialized at only first time.

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

$('#open-button').click(function() {
  // Same initializing per every showing
  $('#modal').plainModal('open', {duration: 500});
});

In this code, it is initialized at once:

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

In this code, it is initialized at once:

$('#open-button').click(function() {
  // Initialize at only first time
  modal.plainModal('open');
});

option

currentValue = element.plainModal('option', optionName)

element = element.plainModal('option', optionName, newValue)

element = element.plainModal('option', {
  optionName1: newValue1,
  optionName2: newValue2 ... 
})

Get the current option value (see Options) of the modal window, or set the new value to the modal windows.

NOTE: If you want to change the event handlers (see Events), use on or off method.

blur

element = element.plainModal('blur'[, on[, duration[, complete]]])

Let the modal window go under the overlay. If false is specified to on argument, restore the modal window. The default is true.
This 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.
For 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.

Options

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

offset

Type: Object or Function
Default: Calculated center position

An Object that has left and top, relative to the view area.

$('#modal').plainModal({offset: {left: 100, top: 50}});

Or, 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.

var button = $('#open-button').click(function() {
      modal.plainModal('open');
    }),
    modal = $('#modal').plainModal({
      offset: function() {
        // Fit the position to a button.
        var btnOffset = button.offset(), win = $(window);
        return {
          left:   btnOffset.left - win.scrollLeft()
                    + parseInt(this.css('borderLeftWidth'), 10),
          top:    btnOffset.top - win.scrollTop()
                    + parseInt(this.css('borderTopWidth'), 10)
        };
      }
    });

If 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.
A 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.

$('#modal').plainModal({
  offset: function(center) {
    // sizing by view port, step by 100px
    var jqHtml = $('html'),
      width = jqHtml.prop('clientWidth'),
      height = jqHtml.prop('clientHeight');
    width = width * 0.5;
    height = height * 0.5;
    width = Math.round(width / 100) * 100;
    height = Math.round(height / 100) * 100;
    if (width < 100) { width = 100; }
    if (height < 100) { height = 100; }
    this.width(width).height(height);
    center(); // position to center.
  }
});

overlay

Type: Object
Default: {fillColor: '#888', opacity: 0.6, zIndex: 9000}

An Object that can have fillColor, opacity and zIndex of the overlay.

$('#modal').plainModal({overlay: {fillColor: '#fff', opacity: 0.5}});

color is an alias for fillColor.

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

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

closeClass

Type: String
Default: 'plainmodal-close'

If the element that has this class name is found in the modal window, the close method is attached to click event of it.
You can know that the element was clicked, via event.from.

Lorem ipsum dolor ...




Close

duration

Type: Number
Default: 200

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

effect

Type: Object
Default: {open: jQuery.fn.fadeIn, close: jQuery.fn.fadeOut}

An Object that can have open and close Functions for showing and hiding the modal window.
These Functions are called with options.duration Number (see above) and complete Function.
It's same to standard effect methods of jQuery (slideDown, slideUp, animate, etc.). Therefore, those methods can be specified.

$('#modal').plainModal({effect: {open: $.fn.slideDown, close: $.fn.slideUp}});

Custom animation:

$('#modal').plainModal({
  offset: {left: 300, top: 100},
  duration: 500,
  effect: {
    open: function(duration, complete) {
      this.css({
        display:          'block',
        marginTop:        -100 - this.outerHeight()
      })
      .animate({marginTop: 0}, duration, complete);
    },
    close: function(duration, complete) {
      this.animate({
        marginTop:        -100 - this.outerHeight()
      }, duration, function() {
        $(this).css({display: 'none'});
        complete();
      });
    }
  }
});

These Functions can ignore duration, but it must call complete, when the effect was finished.

$('#modal').plainModal({
  effect: {
    open: function(duration, complete) {
      var that = this.css({
        display:          'block',
        color:            '#fff',
        backgroundColor:  '#f1e470'
      });
      setTimeout(function() {
        that.css({color: '', backgroundColor: ''});
        complete();
      }, 500);
    },
    close: function(duration, complete) {
      var that = this.css({
        color:            '#fff',
        backgroundColor:  '#f1e470'
      });
      setTimeout(function() {
        that.css({display: 'none'});
        complete();
      }, 500);
    }
  }
});

zIndex

Type: Number
Default: options.overlay.zIndex + 1

A z-index CSS property of the modal window. This number have to be bigger than zIndex of options.overlay.

child

Type: jQuery object
Default: undefined

A child modal window or multiple child modal windows.
A 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).
You can trace or control those behavior via event.from.

var child = $('#child').plainModal(),
  parent = $('#parent').plainModal({child: child});

$('#main-button').click(function() { parent.plainModal('open'); });
$('#button-in-parent').click(function() { child.plainModal('open'); });

force

Type: Boolean
Default: false

The only one modal window can open in the one window. Therefore the open method is ignored when another modal window is already opened.
If the 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.
You can trace or control those behavior via event.from. If you want to let the modal windows behave like the parent and child, you should consider options.child.

var modal1 = $('#modal1').plainModal(),
  modal2 = $('#modal2').plainModal({force: true});

fixOverlay

Type: Boolean
Default: false

If true is specified, the effects for showing and hiding the overlay are avoided.
For 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.

open, close, beforeopen, beforeclose

Type: Function
Default: undefined

The plainmodalopen, plainmodalclose, plainmodalbeforeopen and plainmodalbeforeclose event handlers. This is convenient way to do on(type, handler) method. (see Events)

$('#modal').plainModal({open: function(event) { console.log(event); } });

NOTE: If this option is specified in the open method, declared Function or the variable the Function is assigned should be specified (Don't specify the function expression). Because the open 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); }
$('#open-button').click(function() {
  $('#modal').plainModal('open', {open: handler});
});

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

$('#open-button').click(function() {
  $('#modal').plainModal('open', {open: function(event) { console.log(event); } });
});

Events

plainmodalopen

Triggered when the modal window is opened. (after the open of options.effect took options.duration to complete.)
An event handler can be attached when initializing via options.open as well.
The Event object that is passed to the event handler might have a from property.

$('#modal').on('plainmodalopen', function(event) {
  $('textarea', event.target).addClass('highlight');
});

plainmodalclose

Triggered when the modal window is closeed. (after the close of options.effect took options.duration to complete.)
An event handler can be attached when initializing via options.close as well.
The Event object that is passed to the event handler might have a from property.

$('#modal').on('plainmodalclose', function(event) {
  $('#screen').show();
});

`plainmoda