overLIB - Getting started with overlibmws

Getting Started with the overlibmws
DHTML Popup Library

maintained by Foteos Macrides at Macrides Web Services
Discuss these examples, seek help, and offer suggestions for
Getting Started support via the overlibmws Support Group.

1. POPUP TYPES:
The overlibmws library uses javascript for DHTML popups that serve as informational and navigational aids for websites. The overlib calls invoke either tooltip popups, or (typically more elaborate) sticky popups that hang around until they are actively closed or are replaced by another popup. Both types can be invoked with or without a caption. They are most commonly invoked via the onmouseover (hover) event, but also can be invoked via the onclick event, or both events, or any event supported by browsers for invoking javascript (e.g., onload). The preceding four anchors (links) invoke popups with the distribution default styles, but you can customize the popups for your site's look and feel. You can make the tooltip popups more like an OS or title-based tooltip by toggling off the mouse-following behavior and imposing an onset delay and a timeout.

2. PREPARING THE HTML/XML DOCUMENT:
The minimum necessary preparation is to import the core module, overlibmws.js, via a script block in the head section of the document:

You also can declare the overDiv positioned div (layer) immediately after the body start tag:

or omit the declaration and let the core module create the div dynamically. You may need to include a path in the src value for the core module, if it is not in the same directory (folder) as the document. If you have other javascript files or blocks with code which captures mouse movements (e.g., for menu systems such as Milonic), you should import the core module after those. Also, if you have other positioned divs in the document, make sure that the z-index of the overDiv layer is the highest. If the layer is created dynamically, the default value of 1000 is used. The popups are invoked by using the library's javascript for dynamically loading content into the overDiv container (layer), positioning the container, and changing its visibility to visible. They are closed by restoring the visibility to hidden.

3. INVOKING AND CLOSING POPUPS:
You are now able to make overlib() calls for invoking popups with the core commands (i.e., ones which do not require plugin modules, see below), and nd() calls for closing the popups (though sticky popups require an additional action to close). Here are the calls associated with the six anchors in the first section of this document:

<a
href="javascript:void(0);"
onmouseover="return overlib('This is a tooltip popup.', AUTOSTATUS, WRAP);"
onmouseout="nd();">tooltip</a>

<a
href="javascript:void(0);"
onmouseover="return overlib('This is a (typically more elaborate) sticky popup.',
CAPTION, 'This is a Caption', STICKY, STATUS, 'This is a sticky popup with a caption.');"
onmouseout="nd();">sticky</a>

<a
href="javascript:void(0);"
onmouseover="return overlib('This is a tooltip popup.', CAPTION, 'This is a Caption',
WRAP, STATUS, 'This is a tooltip popup with a caption.');"
onmouseout="nd();">caption</a>

<a
href="javascript:void(0);"
onmouseover="return overlib('Click to help an exhibitionist.', AUTOSTATUS, WRAP);"
onmouseout="nd();"
onclick="overlib('Thanks for clicking.  I have a burning desire to be seen.',
CAPTION, 'I love onclick!'); return false;">both events</a>

<a
href="javascript:void(0);"
onmouseover="return overlib('Click to help an exhibitionist.', AUTOSTATUS,
  TEXTPADDING, 4, FGCOLOR, '#cceeff', TEXTFONTCLASS, 'oltxt', WRAP, BASE, 2, HAUTO);"
onmouseout="nd();"
onclick="overlib('Thanks for clicking.  I<br>have a burning '
  +'desire<br>to be seen.', CAPTION, 'I love onclick!', STICKY, FGCOLOR, '#bbddff',
  TEXTPADDING, 8, CAPTIONPADDING, 4, TEXTFONTCLASS, 'oltxt', CAPTIONFONTCLASS, 'olcap',
  CLOSEFONTCLASS, 'olcap', WRAP, BASE, 2, HAUTO, FILTER); return false;">look and feel</a>

These overlib calls consist of a lead argument which is a quoted string that will be displayed as the popup content, and a comma-separated list of uppercase commands that may have parameters which are either quoted strings or unquoted numeric values. We use href="javascript:void(0);" in these examples, and the STATUS or AUTOSTATUS commands for specifying a status bar string to show when the popup is displayed. The href instead could be a URL for another document, in which case we would not specify a status bar string but instead allow the URL to be shown in the status bar. Note that IE7's default security setting allows such modifications of the status bar text only on intranets, so it will work when using local copies of HTML/XHTHL files, but not when received via the Internet. Also, Firefox has an option via its Tools | Options | Content | Enable JavaScript | Advanced menu to disable such modifications. Also note that IE7 has a bug which prevents the href from being displayed while hovering over a link if an onmouseover popup contains a background or foreground image. If the link has an href other than javascript:void(0); and thus should be displayed, a workaround for the IE7 bug is to include onmousemove="if(OLie7)self.status=this.href;" which works even if the file is received via the Internet (i.e., appears to be a "counterbalancing" bug in IE7).

Though this should be enough to get started "learning by doing" you should study the overlibmws Command Reference to become proficient with the library. It presently has 135 commands. If commands which have parameters are included in an overlib call, those values of the parameters are used instead of the default values. Note that commands which do not have parameters are of two types. A few are members of mutually exclusive sets, e.g., LEFT, CENTER and RIGHT are such a set for horizontal positioning of popups relative to the cursor (RIGHT is the distribution default), and ABOVE, VCENTER and BELOW are such a set for vertical positioning of popups relative to the cursor (BELOW is the distribution default). Most of the commands which do not have parameters act as toggles. Their distribution defaults are normally off (0) and their inclusion in the overlib call toggles them on (1) for that call so that the setting or action that their command name indicates will be applied. But if the default is changed to on (see below), inclusion of the command in the overlib call will toggle the setting or action for that call to off (opposite of what the command name indicates). To reduce possible confusion in that context, a minus sign can be placed immediately before the command name to yield an unconditional off for that call.

4. PLUGIN MODULES:
Some commands or features which are not expected to be used frequently are implemented via plugin modules of the form overlibmws_name.js. They should be imported via script blocks following the core module when their commands or features are to be used in the document, e.g.:

You may need to add path information in the src attribute values if the js files are not in the same directory (folder) as the HTML/XML document. The Command Reference indicates the commands or features which are handled via plugin modules.

5. CUSTOMIZATION:
Although you can customize the popups via commands and their parameters, if any, in the overlib calls, once you become familiar with the library you may wish to customized it by changing the defaults so that they need not be set via commands in every overlib call. As explained in Section 1 of the Command Reference and in the distribution's overlibConfig.txt file, you can change any distribution defaults:

in the DEFAULT CONFIGURATION sections near the tops of the core and plugin modules such that the changes will apply to all of your HTML/XML files, or
by defining sets of configuration defaults in a script block or imported js file so that they override the corresponding distribution defaults for individual HTML/XML documents, or
(preferred) by using the OLpageDefaults() function in a script block or imported js file to set defaults for individual HTML/XML documents in a manner homologous to making overlib calls (i.e., the commands and their parameters, if any, which would be common to all overlib calls in the document can instead be put in an OLpageDefaults call that is made once during loading of the document).

A disadvantage of (a) is that you must edit the DEFAULT CONFIGURATION sections every time you update your copies of overlibmws js files (see below), whereas (b) and (c) are unaffected.

6. REGULATION:
The OLgateOK global variable can be used in documents to disable popups by setting it equal to 0, and to re-enable popups by restoring it to its default value of 1.

7. UPDATING:
The overlibmws library does not use version numbers. The overlibmws.zip archive is updated whenever the core module, any plugin modules, and/or any support scripts are modified to incorporate an enhancement or fix a bug, and the last-changed dates are recorded in the headers of the modified files. The overall last-changed date also is indicated in the Status section of the Command Reference. All enhancements and/or bug fixes are recorded with their dates in the Change History. Once you start using this code set, you should review the recent changes in the Change History periodically to see if anything has been done which would merit your doing an update at your site(s).

8. SUPPORT:
You can use the Foteos Macrides links in the support files at this site to seek help getting started, report problems. or suggest enhancements. Better yet, use the overlibmws Support Group Whenever possible, please include the URL for a document which illustrates the issue you are raising.

This document uses overlibmws and its commands.
	Copyright Foteos Macrides 2002-2010. All rights reserved.