Overlays

The Ojay.Overlay package provides a number of classes that help you to place content on top of the rest of the page. You can use these base classes to construct window systems, lightbox effects, and any number of other UIs. The Overlay package is designed to be very general and highly flexible, and is based on the simple idea of positioning an HTML element absolutely on top of the page. The core classes are:

  • Overlay – provides most of the API, but unlikely you’ll use this directly
  • ContentOverlay – for positioning content on top of the page, extends Overlay
  • Tooltip – extends ContentOverlay to provide overlays that follow the mouse
  • PageMask – extends Overlay, can be used to ‘fade out’ the page for lightbox effects

Required files

  • http://yui.yahooapis.com/2.6.0/build/yahoo-dom-event/yahoo-dom-event.js
  • http://yui.yahooapis.com/2.6.0/build/selector/selector-beta.js
  • http://yui.yahooapis.com/2.6.0/build/animation/animation.js
  • http://yoursite.com/ojay/js-class.js
  • http://yoursite.com/ojay/core.js
  • http://yoursite.com/ojay/pkg/overlay.js

Creating an overlay

It is unlikely that you will use the Overlay class directly – you will probably use one of its descendants instead. But since it contains most of the API for the other classes I will be using it to go through the methods available. Click ‘Show me’ after each bit of code to see it in action.

To create an overlay, you pass in a set of options – the available options are listed in this example:

            var overlay = new Ojay.Overlay({
              width:      400,
              height:     300,
              left:       450,
              top:        1350,
              className:  'example',
              layer:      10,
              opacity:    0.7
            });

This will add the following markup to the top of the body element:

            <div class="overlay-container example"></div>

The element will be absolutely positioned and have the position and dimensions you specify. All the options are just that – optional; if you omit an option it’s given a sensible default value.

Showing and hiding

By default, overlays are not shown on creation. To show it, call its show() method with the name of a transition effect. Available transitions are fade and zoom; if you don’t specify a transition, the overlay shows/hides instantaneously.

            overlay.show('fade');
Show me

That’s probably getting in your way a bit there, so let’s hide it again:

            overlay.hide('zoom');
Show me

They are even chainable using MethodChain:

            overlay.show('zoom').wait(3).hide('fade');
Show me

Positioning methods

To set the position of an overlay, you can use its setPosition() method, if you want to center the overlay on the screen call center():

            overlay.setPosition(600, 1500);
Show me
            overlay.center();
Show me

As well as horizontal/vertical positioning, Overlay makes z-positioning easy. The following methods can be used to set the z-index of an overlay:

  • overlay.setLayer(n) – sets the overlay’s z-index to n
  • overlay.positionBehind(another) sets the overlay’s z-index so it displays behind another overlay
  • overlay.positionInFront(another) sets the overlay’s z-index so it displays in front of another overlay

Sizing methods

To set the size of an overlay, just pass in the width and height values. These can be numbers, or strings containing units. If numbers are used, we assume the units are pixels:

            overlay.setSize('25%', '10%');
            overlay.center();
Show me
            overlay.setSize(400, 200);
            overlay.center();
Show me

Getting size and position information

There are a number of methods for getting information about the size and position of an overlay. These are getSize(), getPosition() and getRegion().

            var pos = overlay.getPosition(), size = overlay.getSize();
            alert('Left: ' + pos.left + ', top: ' + pos.top);
            alert('Width: ' + size.width + ', height: ' + size.height);
            alert(overlay.getRegion().toString());
Show me

If you want to know the z-index of an overlay, just call overlay.getLayer().

Changing the opacity

Setting and getting the opacity of an overlay is straightforward with the following methods:

            overlay.center();
            alert(overlay.getOpacity());
            overlay.setOpacity(0.3);
Show me

Listening to events

All Overlay instances (and instances of its subclasses) publish a number of events that you can listen and react to. These events are:

  • show – fired when an overlay is made visible
  • hide – fired when an overlay is hidden
  • close – fired when the overlay is removed from the DOM

To listen to one of these events, just use the on() method. The overlay instance is passed as the first argument to your callback.

            var overlay = new Ojay.Overlay();
            
            overlay.on('show', function(overlay) {
              // do other stuff with overlay,
              // call other parts of your codebase
            });

Using ContentOverlay

This is likely to be the overlay type you’ll use most often. It has all the methods we’ve discussed so far, plus a few more to let you populate the overlay with HTML content. You create a content overlay in much the same way as above, but you can pass an extra option, content to set the initial content.

            var overlay = new Ojay.ContentOverlay({
              /* standard options here */
              content: '<h1>The title</h1><p>The content</p>'
            });

The markup generated is slightly different to that of basic Overlay instances, and looks like the following:

            <div class="overlay-container">
                <div class="overlay-content">
                    <h1>The title</h1>
                    <p>The content</p>
                </div>
            </div>

ContentOverlay instances have two extra methods on top of those provided by Overlay: setContent() and insert(). These work in exactly the same way as the methods of the same names found in the Ojay core library, and simply manipulate the contents of the overlay-content element. They also have a fitToContent() method, which sizes the overlay container element so that it only just contains the content element.

Using PageMask

The PageMask class extends Overlay and provides a mechanism for fading out page content to create a ‘lightbox’ effect. As an example, let’s fetch some content using Ajax and display it in a lightbox above the page (push ESC to close the overlay):

            var mask = new Ojay.PageMask({color: '#807065', opacity: 0.8});
            var overlay = new Ojay.ContentOverlay({className: 'ex1'});
            mask.positionBehind(overlay);
            
            Ojay.HTTP.GET('/service/paginator/01.html')
            .insertInto(overlay)
            ._(mask).show('fade')
            ._(overlay).fitToContent().center().show('zoom');
            
            Ojay.Keyboard.listen(document, 'ESCAPE', function() {
              overlay.hide('zoom')._(mask).hide('fade');
            });
Show me