An expandable JavaScript popups engine

Hello everybody, its been a while I haven't posted anything, I've been very busy :) But I promise you today's post will be good, or at least I hope so. Read on...

Every website needs to show alerts, popups, layers, whatever you want to call them. New Web 2.0 websites need this more as they show information with popups about the asynchronous actions the end user does. Take a look at Google Reader for example, my favorite RSS reader, when you do things like scroll down, you see a small popup (or a layer if you want) that is a simple div with a different background color that shows on the top of the page centered, displaying things like "Loading..." etc.

What I will present to you in this post is an engine for displaying such popups in a snap. Adding the engine to your site is very simple, you just have to include some JavaScript files in your pages. Please check my earlier post on Server side JavaScript because it contains a small engine that allows you to serve JavaScript files to the client browser in a more efficient manner. Let me start with a simple syntax of adding a simple popup to your site, it is as easy as this:

CommonPopupsEngine.GetHtmlPopup(0, "<div class='popup'>Loading...</div>").
   Center(CommonPopupsEngine.CenterHorizontal).
   ShowDialog();

This will show a div in the middle of the page (horizontal) saying "Loading...". The CSS class popup will customize it's color, background color and so on.

The first parameter is the channel, I will defer the explanation of this till later, for now set it always to zero. The next parameter is the actual html text of the popup you want to add, in this case it is a simple div with a CSS class. The function GetHtmlPopup at this point returns an object that is called "PopupCollection". The "PopupCollection" object is considered as one popup, visually speaking, however the name is set to collection because each visual popup you show, could be created from several html elements and not just one, for example if you want to add a shadow to your popup, then the popup will have your html code that was specified with the function call and another html element behind your element that is casting the shadow, together they form the visual popup that you see.

The PopupCollection object has several functions defined on it including ShowDialog() which will show the PopupCollection once called. The PopupCollection functions use the chaining method, which means each function returns "this" at the end of it to enable chaining the functions one after the other, this technique makes it easy to customize the PopupCollection in an easy memorable/expandable way without having to shove everything as parameters on one function.

The engine also offers you Grayouts to popups. Grayouts are when the whole page fades before showing the popup. Adding a grayout is as easy as calling AddGrayout() on your PopupCollection object, similarly for adding a shadow, you call AddShadow(). These two functions have a restriction on the order that you call them. If you want them, you have to call them in the beginning of the chain and the AddShadow() should be before the AddGrayout().

The functions that you can use in chaining are:

• AddShadow: Adds a shadow to your PopupCollection.
• AddGrayout: Adds a grayout to your PopupCollection.
• SetDimensions: Sets the position/dimensions of your PopupCollection. It takes 4 parameters, each of the parameters is optional and you specify null if you do not want to specify it. The parameters are x, y, width and height. The parameters are self explanatory.
• Center: Center the element instead of specifying dimensions using SetDimensions. You can call this method without any parameter and it will put the PopupCollection in the middle of the page. Or you can pass it one of the following parameters: CommonPopupsEngine.CenterVertical, CommonPopupsEngine.CenterHorizontal, CommonPopupsEngine.CenterBoth.
• SetFadeInDelay: Usually the popups show and hide, however if you call this function passing it a delay value (in milliseconds), it will FadeIn.
• SetFadeOutDelay: Same as above but for closing the dialog.
• EnableUserPositioning: Enables the PopupCollection to be dragged by the end user.
• AutoCloseDialogAfter:If you want to have the PopupCollection close automatically after a period of time, call this function passing it the delay in milliseconds.
• ShowDialog:Usually this is the last function you call in the chain, it will display the PopupCollection.

An example on the usage of these:

CommonPopupsEngine.GetHtmlPopup(0, 
    "<div class='popup'>An error has occurred</div>")
    .AddShadow()
    .AddGrayout()
    .SetDimensions(null, 40)
    .Center(CommonPopupsEngine.CenterHorizontal)
    .SetFadeInDelay(300)
    .SetFadeOutDelay(400)
    .EnableUserPositioning()
    .ShowDialog();

This example will show a popup that says "An error has occurred" inside a div having the CSS Class 'popup', It will have a Shadow and a Grayout, it will be centered horizontally and its Y coordinates will be 40 pixels from the top. The popup will FadeIn in 300 milliseconds and will FadeOut in 400 milliseconds. The popup can be dragged by the end user.

You can also easily open an Iframe in a popup by using a call like this:

CommonPopupsEngine.GetIFramePopup(channel, "http://www.yahoo.com/",
    450, 250, 200, 100, true)
    .AddShadow(null, 10)
    .AddGrayout()
    .SetFadeInDelay(300)
    .SetFadeOutDelay(400)
    .ShowDialog();

More examples can be seen in the file commonpopup.js in the attached example project.

To close the popups, there is one easy function to call CommonPopupsEngine.CloseTopmostPopupCollection. This function can be called without any parameter, in this case, it will close the last PopupCollection that was showed on the page. You can also pass it a specific channel to indicate to close the top most popup of a specific channel, I will explain the channels next.

When you show several popups, the engine stacks them on top of each other. And when you close the popups, it will close the topmost and shows the ones under it. If you want to have a different stack on the page, then this is what the channel is for, a channel is a stack of popups, specifying a different channel instructs the engine to use a different stack for the popups internally.

The engine takes care of the z-index of the popups that it shows transparently for you. It also makes sure that each individual html element in a PopupCollection has the proper z-index set for it (usually this is dictated by the order of the elements in the PopupCollection, this is why the AddShadow() and AddGrayout() has an order restriction when you call them in the chain).

The popup engine is written in the file commonpopupsengine.js, in the top of the file, there are few customizable parameters that affect how the engine works, they are put between two comments called configuration.

• CommonPopupsEngine_startupZIndex:

This is the startup z-index that the engine uses to manage the z-indexes of the PopupCollections you show. You might need to raise this value if you have your own popups or your own elements that have higher z-indexes.

• CommonPopupsEngine_maxPopupCollectionElements:

As described in the paragraph above, the engine takes care of the z-index of the individual elements of the PopupCollection, to do so correctly, it needs to know the maximum number of html elements that may exist in one single PopupCollection, this is this value. Usually you will not need to change this value however if you want to expand this code you will need to understand this more. On a later post, I will go into more details to explain how you can expand the code here.

• CommonPopupsEngine_useGlobalZIndex:

If this value is set to true, then even if you have multiple channels, the last popup will be shown on top of all including all channels. If you have this set to false, if you open two popups in two different channels then they will have the same z-index and they will be shown both as on top and not just one.

• CommonPopupsEngine_onlyShowToplevelPopup:

When this is set to true, if you open more than one popup, then only the last popup will be seen. When you show a new popup, the current one will be hidden and when you close the topmost popup, then if there is a popup below it, it will be shown again.

Here are some snapshots:

Let me know if you have any comments or if you need further help.

Hope this helps you.