nyroModal

NyroModal v2 :: 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. Regarding the animations, you can simply redefine them from A to Z. Thanks to the useful jQuery function like animate or fadeTo it's pretty simple.
nyroModal v2 now works with filters that let you define totally new possibilities for the plugin about the way it should work.
like in the version 1, you still have a bunch of callbacks that you can define in many different places.

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>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

Ajax without closing

<a href="demoSent.php" class="nyroModal" rev="modal">Ajax without closing</a>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

Image

<a href="img/img2.jpg" class="nyroModal" title="3rd Street Promenade">Image</a>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

Gallery Img 1
Gallery Img 2
Youtube in gallery
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="https://www.youtube.com/watch?v=lddUnv1R5y0" class="nyroModal" rel="gal" title="Hockey Goal fight">Youtube in gallery</a><br />
<a href="img/img3.jpg" class="nyroModal" title="Sunset at Santa Monica" rel="gal">Gallery Img 3</a>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

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>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

Youtube (Via Embedly filter)

<a href="https://www.youtube.com/watch?v=lddUnv1R5y0" class="nyroModal">Youtube (Via Embedly filter)</a>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

Manual Call to get an ajax content
Manual Call calling through an other link

<a id="manual1" href="#">Manual Call to get an ajax content</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>
<script type="text/javascript">
$(function() {
  $('#manual1').click(function(e) {
    e.preventDefault();
    $.nmManual('demoSent.php');
  });
  $('#manual2').click(function(e) {
    e.preventDefault();
    $('#imgFiche').nmCall();
  });
  var validForm = $('#myValidForm').submit(function(e) {
    e.preventDefault();
    if (validForm.find(':text').val() != '') {
      validForm.nyroModal().nmCall();
    } else {
      alert("Enter a value before going to " + validForm.attr("action"));
    }
  });
});
</script>

Automatic Iframe via other hostname
Automatic Iframe via target=_blank

<a href="https://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>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>
<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" class="nyroModal" target="_blank">
  <input type="text" name="wouhou" />
  <input type="submit" value="simple form in iframe"/>
</form>
<form method="post" action="demoSent.php#test" class="nyroModal">
  <input type="text" name="wouhou" />
  <input type="submit" value="simple form Filtering Content"/>
</form>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>
<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>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

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>
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

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 functions to work with it:

In order to work, you will have to:

All the needed stuff in a few lines:

<link rel="stylesheet" href="styles/nyroModal.css" type="text/css" media="screen" />
<script src="//code.jquery.com/jquery-1.11.1.min.js"></script>
<script type="text/javascript" src="js/jquery.nyroModal.custom.js"></script>
<!--[if IE 6]>
	<script type="text/javascript" src="js/jquery.nyroModal-ie6.min.js"></script>
<![endif]-->
<script type="text/javascript">
$(function() {
  $('.nyroModal').nyroModal();
});
</script>

Overwritting nyroModal

You can overwrite absolutely all nyroModal functions using:

Filters

Filters are used to provide many basics functionnality like Ajax download, but it alos let you the ability to fully customize the way nyroModal work, by adding as many callbacks as you need.

A filter is a set function that will be called by nyroModal core at many differents points. These functions call be used to do everything needed to make the modal work as you excpet or to add others behaviors needed for your projet: add some elements inside the modal, updating your page content, add some Ajax call, etc...

Here is how filters works:

  1. When $('element').nyroModal(); is called, the nyroModal object is created and attached to the DOM element instancied
  2. Every available filters are tested again the nyroModal object using the is function

    • If this function returns true, the filters will be used all the time for this element.
    • If it returns false, the filters will not be used anymore for this element.
  3. nyroModal core calls every init function of every filters selected for the element

    • These init function should bind the event they need, create their own object if needed.
    • If the filters need to be the one used to load the content, the loadFilter setting of the nyroModal ovject should be defined to its name.
  4. Througout the living of nyroModal, every function or callback defined in all selected filters will be called (see the list below)

All function or callbacks receive the same nyroModal object as a unique parameter.

The list of all function or callback that can be called in a filter:

Like the version 1, there is a bunch of others callback that you can define before and after every animation. The version 2 put it in a new way by letting you the ability to define a function before and after every animation function.

nyroModal automatically add 2 filters for every elements:

There is some some basic filters that you can use on your project that enable the basic usage of this kind of plugin. Here is a list of the filters officially provided:

Using callbacks

To use callback, you can: define tour own filter, using the custom filter by adding the callback function you need

Misc

When using the gallery modal, you can use these code:

When you open a modal using an Ajax request, the scripts included in the loaded page are executed folowing these rules:

Embed.ly

nyroModal uses the great Embed.ly API in order to show videos form many different websites.
To use this feature in nyroModal, you have to include the embed.ly filter first, and then set your API key.
If your API key is not set, nyroModal will simply ignore the Embed.ly filter.
To set your API key, is a simple single line of code that should be placed after including the nyroModal files, and before the initialization of links.

<script type="text/javascript">
$(function() {
  $.nmObj({embedly: {key: 'YOUR EMBED.LY KEY'}});
});
</script>

To create your free API key, go to the embed.ly sign up page

Caching embed.ly results

When you have a lots of embed.ly calls, you may rich the free API limit (that's actually the case of nyroModal).
To fix this problem, we can use a server-side script to retrieve the API result, store on it on the server, and send it to the user.
We created a simple PHP script to do so. You can get it on github.
To use it, simply place this script on your server and configure it regarding your needs. Finally, you have to indicates to nyroModal that the URL to use is a local URL. You can do it with:

<script type="text/javascript">
$(function() {
  $.nmObj({
    embedlyUrl: 'embedlyProxy.php',
    embedly: {key: 'php'}
  });
});
</script>

The key still have to be set to work. In this case, it will be defined in the PHP.

nmObject

nmObject or nyroModal Object is an object associated with every DOM element that are nyroModal enabled. This object is stored with the jQuery data function with the name of nmObj in the opner element. This object provides many function useful for the life of the modal: resizing, closing, calling filters callbacks, etc...
You can overwrite or add more functionnality to this object using the $.nmObj(options); function, or when initializing the nyroModal with nyroModal(options); function (or its synonymous: nm(options);).

Here is the list of all parameter in this object:

  filters: [],	// List of filters used
  callbacks: {},	// Sepcific callbacks
  anims: {},	// Sepcific animations functions
  loadFilter: undefined,	// Name of the filter used for loading
  enabled: true, // Indicates if it's enabled or not
  modal: false,	// Indicates if it's a modal window or not
  closeOnEscape: true,	// Indicates if the modal should close on Escape key
  closeOnClick: true,	// Indicates if a click on the background should close the modal
  useKeyHandler: false,	// Indicates if the modal has to handle key down event
  showCloseButton: true,	// Indicates if the closeButonn should be added
  closeButton: '<a href="#" class="nyroModalClose nyroModalCloseButton nmReposition" title="close">Close</a>',	// Close button HTML
  stack: false,	// Indicates if links automatically binded inside the modal should stack or not
  nonStackable: 'form',	// Filter to not stack DOM element
  header: undefined,	// header include in every modal
  footer: undefined,	// footer include in every modal
  galleryLoop: true,	// Indicates if the gallery should loop
  galleryCounts: true,	// Indicates if the gallery counts should be shown
  ltr: true, // Left to Right by default. Put to false for Hebrew or Right to Left language. Used in gallery filter
  domCopy: false, // Indicates if DOM element should be copied or moved
  imageRegex: '[^\.]\.(jpg|jpeg|png|tiff|gif|bmp)\\s*$',	// Regex used to detect image link
  swfObjectId: undefined, // Object id for swf object
  swf:  {	// Default SWF attributes
    allowFullScreen: 'true',
    allowscriptaccess: 'always',
    wmode: 'transparent'
  },
  store: {},	// Storage object for filters.
  errorMsg: 'An error occured',	// Error message
  elts: {	// HTML elements for the modal
    all: undefined,
    bg: undefined,
    load: undefined,
    cont: undefined,
    hidden: undefined
  },
  sizes: {	// Size information
    initW: undefined,	// Initial width
    initH: undefined,	// Initial height
    w: undefined,		// width
    h: undefined,		// height
    minW: undefined,	// minimum width
    minH: undefined,	// minimum height
    maxW: undefined,	// maximum width
    maxH: undefined,	// maximum height
    wMargin: undefined,	// Horizontal margin
    hMargin: undefined	// Vertical margin
  },
  anim: {	// Animation names to use
    def: undefined,			// Default animation set to use if sspecific are not defined or doesn't exist
    showBg: undefined,		// Set to use for showBg animation
    hideBg: undefined,		// Set to use for hideBg animation
    showLoad: undefined,	// Set to use for showLoad animation
    hideLoad: undefined,	// Set to use for hideLoad animation
    showCont: undefined,	// Set to use for showCont animation
    hideCont: undefined,	// Set to use for hideCont animation
    showTrans: undefined,	// Set to use for showTrans animation
    hideTrans: undefined,	// Set to use for hideTrans animation
    resize: undefined		// Set to use for resize animation
  },
  _open: false,	// Indicates if the modal is open
  _bgReady: false,	// Indicates if the background is ready
  _opened: false,	// Indicates if the modal was opened (useful for stacking)
  _loading: false,	// Indicates if the loading is shown
  _animated: false,	// Indicates if the modal is currently animated
  _transition: false,	//Indicates if the modal is in transition
  _needClose: false, // Indicates if the modal should close after current animation
  _nmOpener: undefined,	// nmObj of the modal that opened the current one in non stacking mode
  _nbContentLoading: 0,	// Counter for contentLoading call
  _scripts: '',	// Scripts tags to be included
  _scriptsShown: '',	//Scripts tags to be included once the modal is swhon

With this bunch of settings, there is also many function:

  // save the object in data
  saveObj: function() {},

  // Open the modal
  open: function() {},

  // Resize the modal according to sizes.initW and sizes.initH
  // Will call size function
  // @param recalc boolean: Indicate if the size should be recalaculated (useful when content has changed)
  resize: function(recalc) {},

  // Update sizes element to not go outsize the viewport.
  // Will call 'size' callback filter
  size: function() {},

  // Get the nmObject for a new nyroModal
  getForNewLinks: function() {},

  // Indicate if an element can be stackable or not, regarding the nonStackable setting
  isStackable: function(elt) {},

  // key handle function.
  // Will call 'keyHandle' callback filter
  keyHandle: function(e) {},

  // Get the internal object
  getInternal: function() {},

  // Internal function for closing a nyroModal
  // Will call 'close' callback filter
  _close: function() {},

  // Public function for closing a nyroModal
  close: function() {},

  // Init HTML elements
  _initElts: function() {},

  // Trigger the error
  // Will call 'error' callback filter
  _error: function() {},

  // Set the HTML content to show.
  // - html: HTML content
  // - selector: selector to filter the content
  // Will init the size and call the 'size' function.
  // Will call 'filledContent' callback filter
  _setCont: function(html, selector) {},

  // Filter an html content to remove the script[src] and store them appropriately if needed
  // - data: Data to filter
  _filterScripts: function(data) {},

  // Check if the nmObject has a specific filter
  // - filter: Filter name
  _hasFilter: function(filter) {},

  // Remove a specific filter
  // - filter: Filter name
  _delFilter: function(filter) {},

  // Call a function against all active filters
  // - fct: Function name
  // return an array of all return of callbacks; keys are filters name
  _callFilters: function(fct) {},

  // Call a filter function for a specific filter
  // - f: Filter name
  // - fct: Function name
  // return the return of the callback
  _callFilter: function(f, fct) {},

  // Call animation callback.
  // Will also call beforeNNN and afterNNN filter callbacks
  // - fct: Animation function name
  // - clb: Callback once the animation is done
  _callAnim: function(fct, clb) {},

  // Load the content
  // Will call the 'load' function of the filter specified in the loadFilter parameter
  _load: function() {},

  // Show the content or the loading according to the current state of the modal
  _contentLoading: function() {},

  // Write the content in the modal.
  // Content comes from the hidden div, scripts and eventually close button.
  _writeContent: function() {},

  // Reposition elements with a class nmReposition
  _reposition: function() {},

  // Unreposition elements with a class nmReposition
  // Exaclty the reverse of the _reposition function
  _unreposition: function() {}

Callbacks

See Filters sections for more informations

Download

nyroModal is licensed under the MIT License.
nyroModal is hosted on Github.

Download the last release
Create your own build

Changelog

Support

You could ask in the Github Page Issues.

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

If you created some improvements or great animations functions, I will be glad to share them. Pleeas use the git feature to make a pull request.