Usage

The plugin provide some function to work with it:

• nyroModal(); is the basic function to set the click or submit function. To add the nyroModal functionnality to all links containing in #container, you’ll do:

  $('#container a').nyroModal();

  Pretty long, right? As all jQuery plugin, the chain is not broken. That mean you can use it like all other jQuery functions. You can also set the settings as an object paramter to overwrite the default parameter.

• nyroModalManual(); will execute the same action like a click in a real link. You can simulate an user click or create your modal content. See demos to better understand.
• $.nyroModalSettings(settings); could be used to change the default settings if no modal are started or the current settings if a modal is currently shown. For example, it will be pretty useful to change the modal size or background color from an Ajax request. If you call this function with the width, height, and/or bgColor parameters while the modal is already shown, the related animation function will be called.
• $.nyroModalRemove(); will simply remove the modal. Could be useful if you need to close after a time or something else.

When using the gallery modal, you can also use these functions:

• $.nyroModalNext(); Go to the next image. Return the link which opened the image if successful or false if nothing was done
• $.nyroModalPrev(); Go to the previous image. Return the link which opened the image if successful or false if nothing was done

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

• If the modal is a targeting content, only the scripts inside this element are executed
• If the modal isn’t targeting:
  • All the inline script are executed
  • The scripts with a src attribute to load a javascript file are loaded only if they are the attribute rel=”forceLoad”. This avoid the reload of jQuery for example

If you need to investigate what’s going on with your modal, you could enable the debug. But sometimes, it’s not enough and you want more. You could overwrite the function nyroModalDebug(msg, elts, settings); to do what ever you want!

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
  blocker: false, // Element which will be blocked by the modal
  windowResize: true, // indicates if the modal should resize when the window is resized
  modal: false, // Esc key or click backgrdound enabling or not
  type: '', // nyroModal type (form, formData, iframe, image, etc...)
  forceType: null, // Used to force the type
  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)
  swf: { // Swf player options if swf type is used.
    wmode: 'transparent'
  },
  width: null, // default Width If null, will be calculate automatically
  height: null, // default Height If null, will be calculate automatically
  minWidth: 400, // Minimum width
  minHeight: 300, // Minimum height
  resizable: true, // Indicate if the content is resizable. Will be set to false for swf
  autoSizable: true, // Indicate if the content is auto sizable. If not, the min size will be used
  padding: 20, // padding for the max modal size
  regexImg: '[^\.]\.(jpg|jpeg|png|tiff|gif|bmp)\s*$', // Regex to find images
  addImageDivTitle: false, // Indicate if the div title should be inserted
  defaultImgAlt: 'Image', // Default alt attribute for the images
  setWidthImgTitle: true, // Set the width to the image title
  ltr: true, // Right to left by default. Put to false for Hebrew or Left to Right language
  gallery: null, // Gallery name if provided
  galleryLinks: 'PrevNext', // Use .nyroModalPrev and .nyroModalNext to set the navigation link
  galleryCounts: galleryCounts, // Callback to show the gallery count
  galleryLoop: false, // Indicate if the gallery should loop
  zIndexStart: 100,
  cssOpt: { // Default CSS option for the nyroModal Div. Some will be overwritten or updated when using IE6
    bg: {
      position: 'absolute',
      overflow: 'hidden',
      top: 0,
      left: 0,
      height: '100%',
      width: '100%'
    },
    wrapper: {
      position: 'absolute',
      top: '50%',
      left: '50%'
    },
    wrapper2: {
    },
    content: {
    },
    loading: {
      position: 'absolute',
      top: '50%',
      left: '50%',
      marginTop: '-50px',
      marginLeft: '-50px'
    }
  },
  wrap: { // Wrapper div used to style the modal regarding the content type
    div: '
',
    ajax: '
',
    form: '
',
    formData: '
',
    image: '
',
    swf: '
',
    iframe: '
',
	iframeForm: '
',
    manual: '
'
  },
  closeButton: 'Close', // Adding automaticly as the first child of #nyroModalWrapper 
  title: null, // Modal title
  titleFromIframe: true, // When using iframe in the same domain, try to get the title from it
  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: 'Cancel', // Loading div content
  errorClass: 'error', // CSS Error class added to the loading div in case of error
  contentError: 'The requested content cannot be loaded.
Please try again later.
Close', // 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
  beforeHideContent: null, // Will be called just before the modal closing
  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
  endRemove: null // Will be called once the modal is totally gone
};

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. beforeHideContent(elts, settings, callback);: called just before the removing modal. use this to remove element that could create trouble with the hiding animation
8. hideContent(elts, settings, callback);: modal.contentWrapper should be hidden after it
9. If a new modal is requested, go back to the 2nd step. If not, we’re closing the modal and continue
10. hideBackground(elts, settings, callback);: modal.bg should be hidden after it
11. Everything created by the plugin will be removed
12. endRemove(elts, settings);: will be called once the modal is totally gone. Elements in the elts object will be unusable

The object elts will contain these parameters:

• started: indicate if the modal is started
• ready: indicate if the modal is ready
• dataReady: indicate if the data are ready
• anim: indicate if the modal is currently animated
• animContent: indicate if the modal content is currently animated
• loadingShown: indicate if the loading is currently shown
• transition: indicate if the transtion is currently shown
• closing: indicate if the modal is closing
• error: indicate if there is an error in the data loading
• blocker: the blocker element if existing
• blockerVars: blocker variables used to position the modal elements
• full: jQuery object for the full nyroModal div container
• bg: jQuery object for the background div
• loading: jQuery object for the loading div
• tmp: jQuery object for the temporary div
• content: jQuery object for the content div
• wrapper: jQuery object for the wrapper div (inserted between content and contentWrapper)
• contentWrapper: jQuery object for the content wrapper div

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):

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.