NyroModal :: jQuery Plugin

Edito

Designers seem to like using modal windows more and more, as they provide a quick way to show data without reloading the entire page. It's easy to use and easy to design.
The big problem I experienced with every plugin I tried either using Prototype/Scriptaculous or jQuery is the customization. They say you can do whatever you want simply but that's not fully true. The default CSS works fine, but most of time it's a mix between required elements and optional. That mean you have to be very careful when editing it.
The other problem is the animation. That's the worst point. I never found one plugin allowing to redefine easily the animations.

I tried to solve these problems with my plugin. I documented everything possible. The default CSS contains only optional rules. Without it, the plugin will works perfectly —but will also looks very sad. Regarding the animations, you can simply redefine them from A to Z. Thanks to the useful jQuery function like animate, fadeTo or the future enchant, it's pretty simple.
Moreover, I added the ability to define many callbacks at different time in the process to allow you to edit the settings, the data or do whatever you need.

Enough talk, let's try it and learn it!

Features

Demos

Show All Codes

Ajax
Ajax Filtering Content #test
Ajax Filtering Content #blabla 

<a href="demoSent.php" class="nyroModal">Ajax</a>
<a href="demoSent.php#test" class="nyroModal">Ajax Filtering Content #test</a>
<a href="demoSent.php#blabla" class="nyroModal">Ajax Filtering Content #blabla</a>

Ajax without closing

<a href="demoSent.php" class="nyroModal" rev="modal">Ajax without closing</a>

Image

<a href="img/img2.jpg" class="nyroModal" title="3rd Street Promenade">Image</a>

Gallery Img 1
Gallery Img 2
Gallery Img 3 

<a href="img/img1.jpg" id="imgFiche" class="nyroModal" title="UCLA" rel="gal">Gallery Img 1</a>
<a href="img/img2.jpg" class="nyroModal" title="3rd Street Promenade by Night" rel="gal">Gallery Img 2</a>
<a href="img/img3.jpg" class="nyroModal" title="Sunset at Santa Monica" rel="gal">Gallery Img 3</a>

DOM Element (hidden div)

<a href="#test" class="nyroModal">DOM Element (hidden div)</a>
<div id="test" style="display: none; width: 600px;">
  <a href="demoSent.php" class="nyroModal">Open a new modal</a><br />
  Test
</div>

Youtube Via Process Handler

<script type="text/javascript">
$(function() {
  $.fn.nyroModal.settings.processHandler = function(settings) {
    var from = settings.from;
    if (from && from.href && from.href.indexOf('http://www.youtube.com/watch?v=') == 0) {
      $.nyroModalSettings({
        type: 'swf',
        height: 355,
        width: 425,
        url: from.href.replace(new RegExp("watch\\?v=", "i"), 'v/')
      });
    }
  };
});
</script>
<a href="http://www.youtube.com/watch?v=lddUnv1R5y0" class="nyroModal">Youtube Via Process Handler</a>

Manual Call
Manual Call calling through an other link 

<script type="text/javascript">
$(function() {
  $('#manual').click(function(e) {
    e.preventDefault();
    var content = 'Content wrote in JavaScript<br />';
    jQuery.each(jQuery.browser, function(i, val) {
      content+= i + " : " + val+'<br />';
    });
    $.fn.nyroModalManual({
      bgColor: '#3333cc',
      content: content
    });
    return false;
  });
  $('#manual2').click(function(e) {
    e.preventDefault();
    $('#imgFiche').nyroModalManual({
      bgColor: '#cc3333'
    });
    return false;
  });
  $('#myValidForm').submit(function(e) {
    e.preventDefault();
    if ($("#myValidForm :text").val() != '') {
      $('#myValidForm').nyroModalManual();
    } else {
      alert("Enter a value before going to " + $('#myValidForm').attr("action"));
    }
    return false;
  });
});
</script>
<a id="manual" href="#">Manual Call</a>
<a id="manual2" href="#">Manual Call calling through an other link</a>
<form id="myValidForm" method="post" action="demoSent.php">
  <input type="text" name="wouhou" />
  <input type="submit" value="simple form with validation" />
</form>

Automatic Iframe via other hostname
Automatic Iframe via target=_blank 

<a href="http://www.perdu.com/" class="nyroModal">Iframe Automatique via other hostname</a>
<a href="demoIframe.php" target="_blank" class="nyroModal">Iframe Automatique via target=_blank</a>

<form method="post" action="demoSent.php" class="nyroModal">
  <input type="text" name="wouhou" />
  <input type="submit" value="simple form"/>
</form>
<form method="post" action="demoSent.php#test" class="nyroModal">
  <input type="text" name="wouhou" />
  <input type="submit" value="simple form Filtering Content"/>
</form>

<form method="post" enctype="multipart/form-data" action="demoSent.php" class="nyroModal">
  <input type="file" name="file" />
  <input type="submit" value="form with file"/>
</form>
<form method="post" enctype="multipart/form-data" action="demoSent.php#blabla" class="nyroModal">
  <input type="file" name="file" />
  <input type="submit" value="form with file Filtering Content"/>
</form>

Non existent URL
Non existent Image
Non existent Element ID
Non existent Element ID in Ajax Request 

<a href="invalidUrl.php" class="nyroModal">Non existent URL</a><br />
<a href="invalidUrl.jpg" class="nyroModal">Non existent Image</a><br />
<a href="#inexistent" class="nyroModal">Non existent Element ID</a><br />
<a href="demoSent.php#inexistent" class="nyroModal">Non existent Element ID in Ajax Request</a>

Preloading Images is not considered to be a part of the plugin, as you probably need to preload other images for your website.
If you need to do so, you can use this code.

<script type="text/javascript">
$(function() {
  function preloadImg(image) {
    var img = new Image();
    img.src = image;
  }

  preloadImg('img/ajaxLoader.gif');
  preloadImg('img/prev.gif');
  preloadImg('img/next.gif');
});
</script>

Usage

The plugin provide some function to work with it:

Settings

You have 3 different ways to modify the settings:

  1. Directly modify $.fn.nyroModal.settings. These settings will be used by default for every modal which will be open
  2. Set at first parameter to the nyroModal(); function. Example: 
    $('a.nyroModal').nyroModal({bgColor: '#ffffff'});
  3. Use the $.nyroModalSettings(settings); function

Here is the complete usable settings list, with their default values.

$.fn.nyroModal.settings = {
  debug: false, // Show the debug in the background
  modal: false, // Esc key or click backgrdound enabling or not
  type: '', // nyroModal type (form, formData, iframe, image, etc...)
  from: '', // Dom object where the call come from
  hash: '', // Eventual hash in the url
  processHandler: null, // Handler just before the real process
  selIndicator: 'nyroModalSel', // Value added when a form or Ajax is sent with a filter content
  formIndicator: 'nyroModal', // Value added when a form is sent
  content: null, // Raw content if type content is used
  bgColor: '#000000', // Background color
  ajax: {}, // Ajax option (url, data, type, success will be overwritten for a form, url and success only for an ajax call)
  width: 650, // default Width
  height: 500, // default Height
  minWidth: 150, // Minimum width
  minHeight: 150, // Minimu height
  padding: 20, // padding for the max modal size
  extImg: 'jpg|jpeg|png|tiff|gif|bmp', // Images extensions seperate by | (regexp using)
  defaultImgAlt: 'Image', // Default alt attribute for the images
  setWidthImgTitle: true, // Set the width to the image title
  css: { // Default CSS option for the nyroModal Div. Some will be overwritten or updated when using IE6
    bg: {
      zIndex: 100,
      position: 'fixed',
      top: 0,
      left: 0,
      height: '100%',
      width: '100%'
    },
    wrapper: {
      zIndex: 101,
      position: 'fixed',
      top: '50%',
      left: '50%'
    },
    wrapper2: {
    },
    content: {
      overflow: 'auto'
    },
    loading: {
      zIndex: 102,
      position: 'fixed',
      top: '50%',
      left: '50%',
      marginTop: '-50px',
      marginLeft: '-50px'
    }
  },
  wrap: { // Wrapper div used to style the modal regarding the content type
    div: '<div class="wrapper"></div>',
    ajax: '<div class="wrapper"></div>',
    form: '<div class="wrapper"></div>',
    formData: '<div class="wrapper"></div>',
    image: '<div class="wrapperImg"></div>',
    gallery: '<div class="wrapperImg"><a href="#" class="nyroModalPrev">Prev</a><a href="#"  class="nyroModalNext">Next</a></div>', // Use .nyroModalPrev and .nyroModalNext to set the navigation link
    swf: '<div class="wrapperSwf"></div>',
    iframe: '<div class="wrapperIframe"></div>',
    manual: '<div class="wrapper"></div>'
  },
  closeButton: '<a href="#" class="nyroModalClose" id="closeBut" title="close">Close</a>', // Adding automaticly as the first child of #nyroModalWrapper 
  openSelector: '.nyroModal', // selector for open a new modal. will be used to parse automaticly at page loading
  closeSelector: '.nyroModalClose', // selector to close the modal
  contentLoading: '<a href="#" class="nyroModalClose">Cancel</a>', // Loading div content
  errorClass: 'error', // CSS Error class added to the loading div in case of error
  contentError: 'The requested content cannot be loaded.<br />Please try again later.<br /><a href="#" class="nyroModalClose">Close</a>', // Content placed in the loading div in case of error
  handleError: null, // Callback in case of error
  showBackground: showBackground, // Show background animation function
  hideBackground: hideBackground, // Hide background animation function
  endFillContent: null, // Will be called after filling and wraping the content, before parsing closeSelector and openSelector and showing the content
  showContent: showContent, // Show content animation function
  endShowContent: null, // Will be called once the content is shown
  hideContent: hideContent, // Hide content animation function
  showTransition: showTransition, // Show the transition animation (a modal is already shown and a new one is requested)
  hideTransition: hideTransition, // Hide the transition animation to show the content
  showLoading: showLoading, // show loading animation function
  hideLoading: hideLoading, // hide loading animation function
  resize: resize, // Resize animation function
  endResize: null, // Will be called one the content is resized
  updateBgColor: updateBgColor // Change background color animation function
};

Callbacks

As an effort to be as more flexible as possible, the plugin provide many callbacks that you can use to alter the data at different time in the process. To be more clear, here is the full process with all possible callback:

  1. The User click on the link or you write some code to open the modal
  2. processHandler(settings);: Use this callback to change the type, the height requested, etc...
  3. If it's a new modal:
    1. showBackground(elts, settings, callback);: elts.bg should be visible after it
    2. showLoading(elts, settings, callback);: elts.loading should be visible after it
    3. handleError(elts, settings);: will be calling in case of error, just before showing the error message
    4. hideLoading(elts, settings, callback);: elts.loading should be hidden after it
    5. If there is an ajax or a form call, the eventual Javascript code inside it will be called at this time
    6. endFillContent(elts, settings);: modal.content is already wrapped. The links to open or close are not binded. This could be a could be good place to alter the content, the size, add some close link
    7. showContent(elts, settings, callback);: modal.contentWrapper should be visible after it
    Or if the modal already exist (call from a modal, navigation inside the gallery):
    1. showTransition(elts, settings, callback);: elts.loading should be visible after it and elts.contentWrapper should be hidden
    2. If there is an ajax or a form call, the eventual Javascript code inside it will be called at this time
    3. handleError(elts, settings);: will be calling in case of error, just before showing the error message
    4. endFillContent(elts, settings);: modal.content is already wrapped. The links to open or close are not binded. This could be a could be good place to alter the content, the size, add some close link
    5. hideTransition(elts, settings, callback);: elts.loading should be hidden after it and elts.contentWrapper should be shown
  4. endShowContent(elts, settings);: The modal is now fully visible. Here is a place to add more visual elements which could have some issues in some browser
  5. The User enjoy the modal. One day, he will probably close the modal or click somewhere to open a new modal
  6. You have the ability to resize the modal by using $.nyroModalSettings with width and/or height parameters. In this case:
    1. resize(elts, settings, callback);: elts.contentWrapper should be at the new dimensions after it
    2. endResize(elts, settings);: will be called once the resize is done
    It's also possible to update the background color by using $.nyroModalSettings again with the bgColor parameter:
    1. updateBgColor(elts, settings, callback);: elts.bg should be shown with the new color. To animate the color, be sure to include the color plugin.
  7. hideContent(elts, settings, callback);: modal.contentWrapper should be hidden after it
  8. If a new modal is requested, go back to the 2nd step. If not, we're closing the modal and continue
  9. hideBackground(elts, settings, callback);: modal.bg should be hidden after it
  10. Everything created by the plugin will be removed

The object elts will contains these parameters:

To read more about the animation callback, see below.

Animation Callbacks

You can redefine the animation as you want. To do so, you'll rewrite completly the animation function. That mean you can whatever you want. If you want simply show the element without any animation, you can simply do an show in the element and execute the callback. That's it.

To be more convenient, all animation callback function takes the exact same parameters:

  1. elts: will be used to access to the elements. To be sure to be totally free to do what you want as you want, you can access all element. You're free to break everything if you like to! See previous chapter to know what's inside
  2. settings: contains the whole currentsettings object. You have to use some elements inside this object to be sure to do something working good
  3. callback: don't forget to execute this one! If you don't, the modal will be broken. You can call it by passing it to the complete attribute for the animation, or simply do something like: callback();

The best way to start an animation function is probably to copy/paste his content from the plugin, see how it works and what is doing and then start edit it.

When positionning the loading or the content, you'll probably center it. To do so we usually use this king of CSS:

#element {
  position: fixed;
  width: 500px;
  height: 300px;
  margin-left: -250px; // -width / 2
  margin-top: -150px; // -height / 2
}

And it should works. But you probably know that IE6 doesn't understand the position fixed. That's why you have to use settings.marginScrollTop and settings.marginScrollLeft to be sure your element is well centered. These values will be equal to zero in the convenient browser, and equal to the scroll values in IE6. When showing the content, 2 others values are available to set the margin: settings.marginLeft and settings.marginTop. For example, the CSS for the content wrapper is set like that:

function showContent(elts, settings, callback) {
  elts.contentWrapper
    .css({ // Reset the CSS at the start position
      marginTop: (-100/2 + settings.marginScrollTop)+'px',
      marginLeft: (-100/2 + settings.marginScrollLeft)+'px',
      height: '100px',
      width: '100px',
      opacity: 0
    })
    .show()
    .animate({ // Set the width
      width: settings.width+'px',
      marginLeft: (settings.marginLeft)+'px',
      opacity: 0.5
    }, {duration: 350})
    .animate({ // Set the height
      height: settings.height+'px',
      marginTop: (settings.marginTop)+'px',
      opacity: 1
    }, {complete: callback, duration: 350});
}

Modal Dimensions

Because understand how the modal is resized could be a nightmare, here is the explanation about how works nyroModal.

Firstly, there is minWidth and minHeight which will apply everytime regardless the modal content type. By default, these values are set to 150 by 150.

Then the modal window will never goes outside the viewport. If a dimension will be outside, it's decreased to fit with the view port.
There is a padding parameter (20 by default) used to space the external boundary of the modal from the viewport.

Regarding the images, they will be resized proportionnaly if they are to big to respect the padding described below.

When you make an Ajax Request, you'll show HTML content. In nyroModal, the size requested will be the real content size available inside the #nyroModalContent div. That mean the content inside the padding of the #nyroModalContent div will be the requested dimensions. For example, requested a 500 by 500 pixels size will result for the #nyroModalContent of these values (screenshot made with Firebug):

nyroModal Dimensions

Why do that?
Imagine working on a website using nyroModal. When requested your modal with different size, you'll take care of the content to fit exactly with the design. That works and everybody is happy.
But 3 months later the design has to be changed regarding the nyroModal looks and feel for adding some margin or border.
As the dimensions is the content inside the modal, changing the dimensions of the margin, padding or border of the wrapper or content won't change the shown dimensions. To make the change you only have to change your CSS and check for some modal if it's work as expected.

Download

nyroModal is licensed under the MIT License.
nyroModal is hosted by Google code.
You can download the latest version here.

In the archive you will find the whole javascript source, the packed and the minified source.
You'll also find 2 CSS version and the default images. The full CSS version is just here to show you the whole HTML structure to customize exactly how you want, if you need.

Changelog

Support

If you find a bug or have a suggestion/request which could be useful for everybody, you can report them in the Google Code Page Issues.

If you created some improvements or great animations functions, I will be glad to share them. Please use also the Issue report to share them.