Skip to content

Commit

Permalink
Added syntax modes to code samples (closes #47)
Browse files Browse the repository at this point in the history
  • Loading branch information
@kylefox
kylefox committed Sep 11, 2016
1 parent beb02fa commit 97c043a
Showing 1 changed file with 89 additions and 66 deletions.
155 changes: 89 additions & 66 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,6 @@ A simple & lightweight method of displaying modal windows with jQuery.

For quick examples and demos, head to [jquerymodal.com](http://jquerymodal.com/).

Maintainers Wanted
---

![](https://img.shields.io/badge/maintainers-wanted-red.svg)

This library became more popular and active than I ever expected, and unfortunately I don't have time to maintain it myself.

If you are interested in helping me maintain this library, please let me know — **I would love your help!**

[**Read more about becoming a maintainer »**](https://github.com/kylefox/jquery-modal/issues/170)

_I'd especially like people who would be excited about working towards a brand new **jQuery Modal 2.0**. See my [Proposal for jQuery Modal 2.0](https://github.com/kylefox/jquery-modal/issues/169) for more details & discussion._

# Why another modal plugin?

Most plugins I've found try to do too much, and have specialized ways of handling photo galleries, iframes and video. The resulting HTML & CSS is often bloated and difficult to customize.
Expand Down Expand Up @@ -129,28 +116,34 @@ You can provide a clean fallback for users who have JavaScript disabled by manua

By default the overlay & window appear instantaneously, but you can enable a fade effect by specifying the `fadeDuration` option.

$('a.open-modal').click(function(event) {
$(this).modal({
fadeDuration: 250
});
return false;
});
```js
$('a.open-modal').click(function(event) {
$(this).modal({
fadeDuration: 250
});
return false;
});
```

This will fade in the overlay and modal over 250 milliseconds _simultaneously._ If you want the effect of the overlay appearing _before_ the window, you can specify the `fadeDelay` option. This indicates at what point during the overlay transition the window transition should begin.

So if you wanted the window to fade in when the overlay's was 80% finished:

$(elm).modal({
fadeDuration: 250,
fadeDelay: 0.80
});
```js
$(elm).modal({
fadeDuration: 250,
fadeDelay: 0.80
});
```

Or, if you wanted the window to fade in a few moments after the overlay transition has completely finished:

$(elm).modal({
fadeDuration: 250,
fadeDelay: 1.5
});
```js
$(elm).modal({
fadeDuration: 250,
fadeDelay: 1.5
});
```

The `fadeDelay` option only applies when opening the modal. When closing the modal, both the modal and the overlay fade out simultaneously according to the `fadeDuration` setting.

Expand All @@ -160,11 +153,15 @@ Fading is the only supported transition.

Because there can be only one modal active at a single time, there's no need to select which modal to close:

$.modal.close();
```js
$.modal.close();
```

Similar to how links can be automatically bound to open modals, they can be bound to close modals using `rel="modal:close"`:

<a href="#close" rel="modal:close">Close window</a>
```html
<a href="#close" rel="modal:close">Close window</a>
```

_(Note that modals loaded with AJAX are removed from the DOM when closed)._

Expand All @@ -177,19 +174,21 @@ _(Note that modals loaded with AJAX are removed from the DOM when closed)._

These are the supported options and their default values:

$.modal.defaults = {
closeExisting: true, // Close existing modals. Set this to false if you need to stack multiple modal instances.
escapeClose: true, // Allows the user to close the modal by pressing `ESC`
clickClose: true, // Allows the user to close the modal by clicking the overlay
closeText: 'Close', // Text content for the close <a> tag.
closeClass: '', // Add additional class(es) to the close <a> tag.
showClose: true, // Shows a (X) icon/link in the top-right corner
modalClass: "modal", // CSS class added to the element being displayed in the modal.
spinnerHtml: null, // HTML appended to the default spinner during AJAX requests.
showSpinner: true, // Enable/disable the default spinner during AJAX requests.
fadeDuration: null, // Number of milliseconds the fade transition takes (null means no transition)
fadeDelay: 1.0 // Point during the overlay's fade-in that the modal begins to fade in (.5 = 50%, 1.5 = 150%, etc.)
};
```js
$.modal.defaults = {
closeExisting: true, // Close existing modals. Set this to false if you need to stack multiple modal instances.
escapeClose: true, // Allows the user to close the modal by pressing `ESC`
clickClose: true, // Allows the user to close the modal by clicking the overlay
closeText: 'Close', // Text content for the close <a> tag.
closeClass: '', // Add additional class(es) to the close <a> tag.
showClose: true, // Shows a (X) icon/link in the top-right corner
modalClass: "modal", // CSS class added to the element being displayed in the modal.
spinnerHtml: null, // HTML appended to the default spinner during AJAX requests.
showSpinner: true, // Enable/disable the default spinner during AJAX requests.
fadeDuration: null, // Number of milliseconds the fade transition takes (null means no transition)
fadeDelay: 1.0 // Point during the overlay's fade-in that the modal begins to fade in (.5 = 50%, 1.5 = 150%, etc.)
};
```

# Events

Expand All @@ -207,15 +206,19 @@ $.modal.AFTER_CLOSE = 'modal:after-close'; // Fires after the modal has ful

The first and only argument passed to these event handlers is the `modal` object, which has three properties:

modal.$elm; // Original jQuery object upon which modal() was invoked.
modal.options; // Options passed to the modal.
modal.$blocker; // The overlay element.
```js
modal.$elm; // Original jQuery object upon which modal() was invoked.
modal.options; // Options passed to the modal.
modal.$blocker; // The overlay element.
```

So, you could do something like this:

$('#purchase-form').on($.modal.BEFORE_CLOSE, function(event, modal) {
clear_shopping_cart();
});
```js
$('#purchase-form').on($.modal.BEFORE_CLOSE, function(event, modal) {
clear_shopping_cart();
});
```

# AJAX

Expand All @@ -229,10 +232,12 @@ You can add text or additional HTML to the spinner with the `spinnerHtml` option

The following events are triggered when AJAX modals are requested.

$.modal.AJAX_SEND = 'modal:ajax:send';
$.modal.AJAX_SUCCESS = 'modal:ajax:success';
$.modal.AJAX_FAIL = 'modal:ajax:fail';
$.modal.AJAX_COMPLETE = 'modal:ajax:complete';
```js
$.modal.AJAX_SEND = 'modal:ajax:send';
$.modal.AJAX_SUCCESS = 'modal:ajax:success';
$.modal.AJAX_FAIL = 'modal:ajax:fail';
$.modal.AJAX_COMPLETE = 'modal:ajax:complete';
```

The handlers receive no arguments. The events are triggered on the `<a>` element which initiated the AJAX modal.

Expand All @@ -242,30 +247,34 @@ It's a good idea to provide more robust AJAX handling -- error handling, in part

Simply bypass the default AJAX handling (i.e.: don't use `rel="modal"`)

<a href="ajax.html" rel="ajax:modal">Click me!</a>
```html
<a href="ajax.html" rel="ajax:modal">Click me!</a>
```

and make your AJAX request in the link's click handler. Note that you need to manually append the new HTML/modal in the `success` callback:

$('a[rel="ajax:modal"]').click(function(event) {
```js
$('a[rel="ajax:modal"]').click(function(event) {

$.ajax({
$.ajax({

url: $(this).attr('href'),
url: $(this).attr('href'),

success: function(newHTML, textStatus, jqXHR) {
$(newHTML).appendTo('body').modal();
},
success: function(newHTML, textStatus, jqXHR) {
$(newHTML).appendTo('body').modal();
},

error: function(jqXHR, textStatus, errorThrown) {
// Handle AJAX errors
}
error: function(jqXHR, textStatus, errorThrown) {
// Handle AJAX errors
}

// More AJAX customization goes here.
// More AJAX customization goes here.

});
});

return false;
});
return false;
});
```

Note that the AJAX response must be wrapped in a div with class <code>modal</code> when using the second (manual) method.

Expand All @@ -283,6 +292,20 @@ I don't use this library as frequently as I used to, so if you want to see a fix

# Contributing

## Maintainers Wanted

![](https://img.shields.io/badge/maintainers-wanted-red.svg)

This library became more popular and active than I ever expected, and unfortunately I don't have time to maintain it myself.

If you are interested in helping me maintain this library, please let me know — **I would love your help!**

[**Read more about becoming a maintainer &raquo;**](https://github.com/kylefox/jquery-modal/issues/170)

_I'd especially like people who would be excited about working towards a brand new **jQuery Modal 2.0**. See my [Proposal for jQuery Modal 2.0](https://github.com/kylefox/jquery-modal/issues/169) for more details & discussion._

## How to contribute

I welcome improvements to this plugin, particularly with:

* Performance improvements
Expand Down

0 comments on commit 97c043a

Please sign in to comment.