OmniWindow

§Main Ideas

§Basic Usage Run example #1

Make minimum actions to use OmniWindow:

§Classes and Selectors Run example #2

If you want to use your own names for modal and overlay classes, you can set them as options. OmniWindow provides the following options to do that:

overlay.selector
jQuery selector used to find overlay. ".ow-overlay"
overlay.hideClass
Class name used to hide overlay "ow-closed"
modal.hideClass
Class name used to hide modal "ow-closed"

§Events: Show and Hide Run example #3

OmniWindow uses two events to show and hide windows. You can trigger this events any time you need.

For example, you can trigger hide event to create your own close button.

eventsNames.show
OmniWindow uses this event name as trigger value to show windowshow.ow
eventsNames.hide
OmniWindow uses this event name as trigger value to hide windowhide.ow

You can redefine event names as you wish, but remember about jQuery namespaces! It's convenient way to unbind only necessary events.

§Events: Internal part

Plugin also has two additional event listeners:

eventsNames.internal.overlayClick
OmniWindow uses this event name as trigger value to emulate mouse click on overlayclick.ow
eventsNames.internal.keyboardKeyUp
OmniWindow uses this event name to subsribe to ESC keyupkeyup.ow

Don't touch options with internal keys if you don't know what you are doing.

When omniWindow instance is hidden, it listens only for 'show' event.

Don't use events to break OmniWindow behaviour, if you need to stop some action just use callbacks!

§Callbacks: Introduction

There are two groups of callbacks: animation callbacks and lifetime callbacks. Each callback has two parts: user part and internal part.

Any user callback can be described in the same way:

subjects
Object contains two jQuery instances:
subjects.modal
Current modal container.
subjects.overlay
Current overlay container.
internalCallback
System callback which does something useful. See more information about that specific callback below.

You can do something with modal or overlay containers in your callbacks:

Always call internalCallback(subjects); at the end of your callback to prevent a lot of errors!

§Callbacks: Animations Run example #4

You can define any kind of animations you want. Just use one (or all) of this callbacks:

overlay.animations.show
Use this callback to show overlayDoes nothing
overlay.animations.hide
Use this callback to hide overlayDoes nothing
modal.animations.show
Use this callback to show modalDoes nothing
modal.animations.hide
Use this callback to hide modalDoes nothing

For example, if you want use fade effects for overlay, you need to redefine overlay.animations.show and overlay.animations.hide callbacks:

It's not necessary to return some values from animation callbacks.

§Callbacks: Internal Animations

Here is a list of internal animations, which are called after user-defined animations:

overlay.animations.internal.show
Removes overlay.hideClass class from overlay container
overlay.animations.internal.hide
Adds overlay.hideClass class to overlay container
modal.animations.internal.show
Removes modal.hideClass class from modal container
modal.animations.internal.hide
Adds modal.hideClass class to modal container

If you plan to play with internal animations for some reason, please don't use animations with timers there!

§Animation Priority

What will be first: overlay show animation or modal show? You shouldn't guess: it is under your control with animationsPriority option:

animationsPriority.show
Array of methods which describes show animations priority (from first to second)['overlay', 'modal']
animationsPriority.hide
Array of methods which describes hide animations priority (from first to second)['modal', 'overlay']

According to default settings animations will appear in following order: show overlay -> show modal -> hide modal -> hide overlay.

§Callbacks: Lifetime Callbacks Run example #5

Lifetime callbacks are five useful functions created to simplify your life! Meet them:

callbacks.beforeShow
Called before modal window or overlay start any show animations.
Useful for additional checks and for loading content via ajax.
If this function returns false, modal will not be shown.Does nothing
callbacks.positioning
Called before modal window or overlay start any show animations.
You can put here any window position-related logic. Does nothing
callbacks.afterShow
Called after overlay and modal show animations.
Useful to initialize some variables or prepare any kind of event listeners. Does nothing
callbacks.beforeHide
Called before modal window or overlay start any hide animations.
Useful for validations checks and for saving content via ajax.
If this function returns false, modal will not be hidden.Does nothing
callbacks.afterHide
Called after overlay and modal hide animations.
Useful to unbind event listeners and clear all previous defined states. Does nothing

There is an example of callbacks.beforeHide, used to validate input: user should fill in the textbox before closing the window. callbacks.afterShow provides logic to clear field and disable error each time window shows.

§Callbacks: Internal Lifetime Callbacks

callbacks.internal.beforeShow
Checks that window is loaded and showed only once and saves window state. If the window is already shown and someone tries to load it again, function breaks loading.
callbacks.internal.positioning
Aligns window to center by calculating margin-left from outerWidth of window.
callbacks.internal.afterShow
Attaches listeners to close window by clicking on the overlay or pressing ESC
callbacks.internal.beforeHide
Checks that window is not hidden and saves window state. If the window is already hidden and someone tries to hide it again, function breaks hiding process.
callbacks.internal.afterHide
Detaches internal event listeners and clears inline styles after jQuery animations.

§Callbacks' summary

Show event lifecycle:

  1. show event on window is triggered: $(...).trigger('show');
  2. beforeShow trigger is called: if result is true then go next, else stop
  3. internal.beforeShow trigger is called: if result is true then go next, else stop
  4. positioning callback is called
  5. internal.positioning callback is called
  6. first show animations callback is called(by order according to animations priority)
  7. first internal.show animations callback is called
  8. second show animations callback is called
  9. second internal.show animations callback is called
  10. afterShow callback is called
  11. internal.afterShow callback is called

Hide event lifecycle:

  1. hide event on window is triggered: $(...).trigger('hide');
  2. beforeHide trigger is called: if result is true then go next, else stop
  3. internal.beforeHide trigger is called: if result is true then go next, else stop
  4. first hide animations callback is called (by order according to animations priority)
  5. first internal.hide animations callback is called
  6. second hide animations callback is called
  7. second internal.hide animations callback is called
  8. afterHide callback is called
  9. internal.afterHide callback is called

Hello, human!

Click on the overlay or press ESC
to close me.

Hello, human!

Click on the overlay or press ESC
to close me.
X

Close me!

^_^

Please, fill in this field before closing!