nyroModal的使用方法

by Xiang Zhuyuan

Technorati 标签: nyroModal jquery
#### 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: 'Prev Next', // 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
  4. showLoading(elts, settings, callback);: elts.loading should be visible after it
  5. handleError(elts, settings);: will be calling in case of error, just before showing the error message
  6. hideLoading(elts, settings, callback);: elts.loading should be hidden after it
  7. If there is an ajax or a form call, the eventual Javascript code inside it will be called at this time
  8. 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
  9. 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
  6. 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
  7. The User enjoy the modal. One day, he will probably close the modal or click somewhere to open a new modal
  8. 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
  9. 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.
  2. beforeHideContent(elts, settings, callback);: called just before the removing modal. use this to remove element that could create trouble with the hiding animation
  3. hideContent(elts, settings, callback);: modal.contentWrapper should be hidden after it
  4. If a new modal is requested, go back to the 2nd step. If not, we’re closing the modal and continue
  5. hideBackground(elts, settings, callback);: modal.bg should be hidden after it
  6. Everything created by the plugin will be removed
  7. 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:

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.