openwebware - Free Components and Applications openPopUps 1.01 Documentation
Please read this document completely before using openPopUps.

This document will walk you through the basics of getting started. If you have any suggestions, or have improvements that will make it more complete, please contact us. We're always looking for ways to improve, whether it's the product itself or the accompanying documentation.

  1. Introduction
    1. What is openPopUps?
    2. Is openPopUps really free and open source?
    3. Do you have a working example I can see?
    4. Where can I learn more about it and download the latest version?
  2. Browser Requirements
  3. Installation
    1. How do I add openPopUps to my web page or web application?
    2. Copy and Paste
  4. Frequently Asked Questions
    1. What are the project goals for openPopUps?
    2. openPopUps is great, is there anyway I can help?
    3. I'd like to add a feature, can you add it?
    4. My question isn't answered here?
  5. Change Log
  6. Feature Recommendations for the Next Version
  7. Copyright and Disclaimer

1. Introduction

If you are just getting started with openPopUps, then you've come to the right place. This document explains what openPopUps is, contains information on setting up openPopUps, answers frequently asked questions, lists the program's requirements, and provides other useful information.



1.i. What is openPopUps?

openPopUps is a free cross-browser DHTML pop-up generator. openPopUps can be used for your site's advertisements or for launching components (color picker, calendar, etc) in your custom web application.

Because DHTML code used to create an openPopUp window is part of the web page and not launched in a seperate browser window pop-up blockers will fail to prevent openPopUps from launching.

Also, because the pop-ups are served without launching a new browser window, openPopUps will not overwhelm and annoy your site visitors or users like most pop-up windows do.

The end result, better user interaction from your visitors/users and better ROI for your advertisements!



1.ii. Is openPopUps really free and open source?

Yes! There are other scripts out there that do the same thing and are priced anywhere from $30 to $100. Don't waste your money, openPopUps is absolutely free!

openPopUps is an open source application released under the LGPL, meaning you'll have access to the full source code to modify or customize it to your needs. Add new features, change the styles, or even optimize the code. It's entirely up to you.



1.iii. Do you have a working example I can see?

Below are two demos, one advertisement example and one web application example.

Advertisement Example
This demo showcases openPopUps in action with a 336x280 banner for scripts.com. While normally the advertisement would load instanly when the page loads, for the purpose of this demo you can view the advertisemint by clicking the button below.

After clicking the buttons below scroll to the top of the page to see the pop-up.



Web Application Example
The next demo shows openPopUps in action using plain <html> as the output. This demo also includes a minimize feature as well.



The nice thing about using openPopUps in your applications is you can use it to launch a custom compoent (date picker, color picker, survey, graph, etc), and build the component using the language of your choice (ASP.net, ASP, Perl, PHP, etc).


NOTE: Launch both popups at the same time and place one in front of the other.Next, click on the title bar belonging to the window in the background. You'll notice that they work like regular browser windows, with the one recently clicked window moving into the foreground.
Scripts.com
Easily create a popup with the content of your choice.
Regular text and <html> can be entered directly into the popup windows.
Pop Up blockers fail to prevent an openPopUp window from opening.
 
Regular text and <html> can be entered directly into the popup windows.


1.iv. Where can I learn more about it and download the latest version?

You can learn more about openPopUps and download the latest version at www.openwebware.com. There's also an excellent user community where you can share ideas, learn various tricks, or even post suggestions and comments.



2. Browser Requirements

openPopUps is cross-browser compatible and will work with the most popular internet browsers. This means your users will have no trouble making use of it. Supported browsers include: Internet Explorer, Firefox, Mozilla and Netscape.



3. Installation

Once you've downloaded openPopUps you'll want to unzip it (while maintaining the directory structure).

openPopUps is coded completely in JavaScript, HTML, and CSS. It also uses images (.gif and .jpg), so if you're uploading these files to your web server you'll want to make sure they're readable.

On Unix based servers, that means every directory has chmod permissions of 755 while the files (.html, .js, .jpg., .gif, etc) are 644. Most Unix based servers use these settings for folders and files by default, so you most likely won't have to change a thing.



3.i. How do I add openPopUps to my website or web application?

You can easily add openPopUps to your website or web application by just adding a few simple lines of JavaScript code.

1. Near the beginning of the web page to which you plan to add openPopUps insert the following line of code before the closing </head> tag.

Include the following:
<script language="JavaScript" type="text/javascript" src="/your_directory_path/openpopups/openpopups.js"></script>

Where your_directory_path is the path to your openpopups directory.

2. Next, add an onLoad call to your opening <body> tag. This onLoad will be used to call the hideDiv() function. The hideDiv function is used to hide our pop-up windows when your page first loads. We'll be adding the code for your windows in a later step.

Example code:
<body onload="hideDiv()">

For each pop-up you plan on having in your page/applicaiton, you'll want to pass that number to your hideDiv() function. For example, if you plan on having three pop-up windows you'll want to call the hideDiv function using hideDiv(3);. On the other hand, if you're only planning to have one pop-up window you would use hideDiv(1);.

3. Now you'll want to add your pop-up windows using <div> tags. Just add code similar to the following.

Example JavaScript code:
<div id="Div1">
  Source Code Goes Here
</div>

You'll want to make sure you give your first pop-up window an id of Div1. For each subsequent window you add increment the id by 1. For example, if you add a second window you would use the following code.

<div id="Div2">
  Source Code Goes Here
</div>

You can output any content you want (images, html, flash, etc) with an openPopUps window. Using the example above, add your content (images, text, etc) where it reads Source Code Goes Here.

4. Finally, you will call the pop-up using the createWindow() function.

When calling this function you pass a total of seven variables. From left to right the variables are:

  1. Window Title
  2. Window Width
  3. Window Background Color
  4. Window ID (this would be the ID in for the window's respective <div>)
  5. Display Minimize Icon (1 for Yes, 0 for No)
  6. X (The number of pixels from the left the window appears when first open)
  7. Y (The number of pixels from the top the window appears when first open)

Here's an example of the createWindow function being called.

createWindow('My Window', 400, 'brown', 1, 0, 240, 375);

Using the example above, we've just called a window with:

  • A title of "My Window"
  • 400 pixels wide
  • A brown background color
  • The pop-ups content will be in a <div> with an id of 1 (<div id="1">content goes here</div>)
  • The window doesn't have a minimize feature
  • The window will be output 240 pixels from the left and 375 pixels from the top of the web page

Common ways to call the createWindow() function is by the click of the button or when the page is loading.

Using a button (usually used in web applicaitons):
<input type="button" value="Create Window" onClick="createWindow('My Window', 400, 'brown', 1, 0, 240, 375);">


When the page loads (usually used in advertisements):
<body onLoad="hideDiv(1); createWindow('My Window', 400, 'brown', 1, 0, 240, 375);">

Note: when calling createWindow() in your onLoad call you must always call HideDiv(); first.

And that's about it. You'll now have added openPopUps to your application or web site.



3.i. Copy and Paste

To make it even easier for you to get started, you can just copy and paste the following example code from below into a webpage and use it to create your first openPopUps window.

Just remember to replace your_directory_path with the path to your openpopups.js file.

4. Frequently Asked Questions

4.i.What are the project goals for openPopUps?

The project goals for openPopUps are designed to make it easy for developers to know where openPopUps is headed. This also lets people know what's important to us and what we believe makes a great pop-up generator.

100% JavaScript

openPopUps must always be coded entirely in JavaScript and DHTML. This is so developers can use it in their applications and site owners can use it on their website regardless of the programming language they choose to build their applications/website, be it Perl, PHP, ASP, Cold Fusion, or any other language.

Easy to Set Up

openPopUps must always be developed from the user perspective. This means making it as easy to set up as possible.


4.ii.openPopUps is great, is there any way I can help?

Absolutely. Whether you're just starting with openPopUps, are a developer or programmer, or have your own website, almost anyone can help.

If You're a Programmer or Developer

Any code improvements you want to share are most certainly welcome. After all, openPopUps is open source, so we're always open for suggestions and improvements.

If you notice anything that you can do better, or have an improvement you would like to make you can always share it with others in the openPopUps forum, or send us an email with your code improvements, new features, or suggestions.

If you're not sure where to get started you can always check out the feature recommendations slated for the next version.

All contributions will be credited to the creator in the openPopUps source code and on the openwebware.com website.

If You're a Webmaster or Site Owner

As a webmaster, the best thing you can do to help is also the easiest thing to do: give us a link on your website. The more people who can find out about openPopUps the better it will be.

Just copy the HTML from one of the code samples below and place it somewhere on your website.

Image Link:
openPopUps - DHTML Powered Pop-up Window



Text Link:
openPopUps - DHTML Powered Pop-up Window

If You're a New User

Participate in our forum and post a message or two to help other users of openPopUps (or learn something new yourself).



4.iii.I'd like to add a feature, can you add it?

Probably not. If it's not listed in the feature recommendations for the next version we just won't have the time to work on it. That doesn't mean you can't work on it or post a message in the forum asking if someone else could help you with it.



4.v.My question isn't answered here?

We're always happy to answer questions. Post your question in the forum if it wasn't answered here.



5. Change Log

Version 1.01 (Released: April 8, 2006)

  • Replaced document.all reference with document.getElementById
  • Minor corrections to documentation

    Version 1.00 (Released: March 1, 2006)
    Initial Release



    6. Feature Recommendations for the Next Version

    Included below is a list of features for the next update to openPopUps. We could really use your help, so if you would like to lend a hand let us know, any additions and enhancements will be credited in the source code and on the openwebware.com website.

    • Features and Improvements
      • Default Window settings for width, background color, minimize icon, and X and Y coordinates
      • Ability to launch static windows (non-draggable) and "slide-in" windows


    7. Copyright and Disclaimer

    This application is open source software released under the LGPL. Please see source code for more details. This package and its contents are Copyright © 2006 openWebWare.com, All Rights Reserved.