# Overlay

Questions or comments?

## Purpose

A flexible, responsive overlay plugin. Implements the WAI-ARIA Dialog (Modal) design pattern.

## Working example

- English example
- French example

## How to implement

For centred popups, please see the Lightbox documentation.

1. Create a `section` element with a unique id and the following classes `wb-overlay modal-content overlay-def`.

       <section id="unique-id" class="wb-overlay modal-content overlay-def wb-bar-t"></section>

2. Add one of the following classes to the section element to configure the type of overlay:

   - `wb-panel-l`: Left panel
   - `wb-panel-r`: Right panel
   - `wb-bar-t`: Top bar
   - `wb-bar-b`: Bottom bar
   - `wb-popup-mid`: Middle screen overlay
   - `wb-popup-full`: Full-screen overlay
   - `wb-popup-full hidden-hd`: Full-screen overlay - Hidden header

3. Add the header of the overlay by adding the following code at the start of the section element:

       <header class="modal-header">
       	<h2 class="modal-title">Overlay title</h2>
       </header>

   For the full-screen overlay with a hidden header, use the following instead:

       <header>
       	<h2 class="wb-inv">Overlay title</h2>
       </header>

4. Add the body of the overlay by adding the following code after the header code:

       <div class="modal-body">
       	... Overlay content ...
       </div>

5. Add a way of opening the overlay. The overlay can be opened either by clicking a link or by triggering an event.

   - Link approach: Add the following link to the page where the `href` and the `aria-controls` attribute match the `id` attribute on the `section` element of the overlay:

         <li>
         	<a href="#unique-id" aria-controls="unique-id" class="overlay-lnk" role="button">Open overlay</a>
         </li>

   - Event approach: Trigger the overlay with the following JavaScript code:

         $( "#unique-id" ).trigger( "open.wb-overlay" );

## Configuration options

Option | Description | How to configure | Values
--- | --- | --- | ---
Overlay type | Configure the type of overlay to display. | Add the configuration class to the `<section>` element of the overlay. | `wb-panel-l`: Left panel `wb-panel-r`: Right panel `wb-bar-t`: Top bar `wb-bar-b`: Bottom bar `wb-popup-mid`: Middle screen overlay `wb-popup-full`: Full-screen overlay
No print | Hide the opened overlay when printing. | Only work for left panel, right panel, top bar and bottom bar. Add the class `no-print` to the `<section>` element of the overlay. | `no-print`
Add an overlay background | Stand up the overlay dialog by adding a black overlay background. | To be used with middle overlay. | `overlay-bg`

## Events

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-overlay` | Triggered manually (e.g., `$( ".wb-overlay" ).trigger( "wb-init.wb-overlay" );`). | Used to manually initialize the Overlay plugin. Note: The Overlay plugin will be initialized automatically unless the required markup is added after the page has already loaded.
`wb-ready.wb-overlay` (v4.0.5+) | Triggered automatically after an overlay is initialized. | Used to identify when an overlay has initialized (target of the event)
    $( document ).on( "wb-ready.wb-overlay", ".wb-overlay", function( event ) {
    });
    $( ".wb-overlay" ).on( "wb-ready.wb-overlay", function( event ) {
    });
`open.wb-overlay` | Triggered manually (e.g., `$( ".wb-overlay" ).trigger( "open.wb-overlay" );`). | Used to manually open an overlay (event must be triggered on the `section` element of the overlay).
`opened.wb-overlay` | Triggered automatically after an overlay is open. | Used to identify when an overlay has been opened (target of the event)
    $( document ).on( "opened.wb-overlay", ".wb-overlay", function( event ) {
    });
    $( ".wb-overlay" ).on( "opened.wb-overlay", function( event ) {
    });
`close.wb-overlay` | Triggered manually (e.g., `$( ".wb-overlay" ).trigger( "close.wb-overlay" );`). | Used to manually close an overlay (event must be triggered on the `section` element of the overlay).
`closed.wb-overlay` | Triggered automatically after an overlay is close. | Used to identify when an overlay has been closed (target of the event)
    $( document ).on( "closed.wb-overlay", ".wb-overlay", function( event ) {
    });
    $( ".wb-overlay" ).on( "closed.wb-overlay", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Overlay plugin source code on GitHub

Date modified:
  2014-08-06