³ÉÈËÂÛ̳

Constructor

new glow.widgets.Overlay(content, opts)

Parameters

content

Type

selector | | glow.dom.NodeList

the element that contains the contents of the overlay. If this is in the document it will be moved to document.body.

opts

Type

Zero or more of the following as properties of an object:

anim

A transition for showing / hiding the panel

Type

|

Default

"null"

Optional

Yes

Can be "fade" or "slide", or a function which returns a glow.anim.Animation or glow.anim.Timeline. The function is passed the overlay as the first parameter, and 'true' if the overlay is showing, 'false' if it's hiding.

ariaProperties

Key-value pairs of aria properties and values

Type

Optional

Yes

These are applied to the overlay container for accessibility purposes. By default the overlay is a polite live area.

ariaRole

The aria role of the overlay.

Type

Optional

Yes

This is used for accessibility purposes. No role is defined by default.

autoPosition

Position the overlay relative to the viewport

Type

Default

"true"

Optional

Yes

If true, the overlay will be positioned to the viewport according to the x & y options. If false, you will have to set the position manually by setting the left / top css styles of the container property.

className

Values for the Overlay container's class attribute.

Type

Optional

Yes

closeOnEsc

Close the overlay when the ESC key is pressed

Type

Default

false

Optional

Yes

The overlay needs to have focus for the ESC key to close.

closeOnMaskClick

if true then listens for a click event on the mask and hides when it fires

Type

Default

"true"

Optional

Yes

focusOnShow

Give the overlay keyboard focus when it appears?

Type

Default

false

Optional

Yes

Use 'returnTo' to specify where to send focus when the overlay closes

hideFilter

Exclude elements from hiding

Type

Optional

Yes

When provided this function is run for every element that may be hidden. This includes windowed Flash movies if 'hideWindowedFlash' is true, and any matches for 'hideWhileShown'. In the function, 'this' refers to the element. Return false to prevent this element being hidden.

hideWhileShown

Elements to hide while the overlay is shown

Type

selector | | glow.dom.NodeList

Optional

Yes

This is useful for hiding page elements which always appear on top of other page elements. Flash movies can be handled easier using the hideWindowedFlash option.

hideWindowedFlash

Hide windowed Flash movies?

Type

Default

true

Optional

Yes

When set to true, any Flash movie without wmode "transparent" or "opaque" will be hidden when the overlay shows. This is because they always appear on top of other elements on the page. Flash movies inside the overlay are excluded from hiding.

id

Value for the Overlay container's ID attribute

Type

Optional

Yes

mask

Mask to use for modal overlays

Type

glow.widgets.Mask

Optional

Yes

used to indicate to the user that the overlay is modal. If provided then the modal property is set to true.

modal

Is the overlay modal?

Type

Default

"false"

Optional

Yes

If true then a default Mask will be created if one is not provided.

returnTo

Element to give focus to when the overlay closes

Type

selector | | glow.dom.NodeList

Optional

Yes

For accessibility purposes you may want to set an element to give focus to when the overlay closes. This meanss devices which present data to the user by the cursor position (such as screen readers) will be sent somewhere useful.

x

Distance of overlay from the left of the viewport

Type

|

Default

"50%"

Optional

Yes

If the unit is a percentage then 0% is aligned to the left of the viewport, 100% is aligned to the right of viewport and 50% is centered.

y

Distance of overlay from the top of the viewport

Type

|

Default

"50%"

Optional

Yes

If the unit is a percentage then 0% is aligned to the left of the viewport, 100% is aligned to the right of viewport and 50% is centered.

zIndex

The z-index to set on the overlay

Type

Default

"9991"

Optional

Yes

If the overlay is modal, the zIndex of the mask will be set to one less than the value of this attribute.

Examples

var overlay = new glow.widgets.Overlay(
  glow.dom.create(
    '<div>' +
    '  <p>Your Story has been saved.</p>' +
    '</div>'
  )
);
overlay.show();

Properties

autoPosition

Position the overlay relative to the viewport

Type

Description

If true, the overlay will be positioned to the viewport according to the x & y options. If false, you will have to set the position manually by setting the left / top css styles of the container property.

container

The overlay's container.

Type

glow.dom.NodeList

Description

Use this to alter the width of the overlay. You can also manually position the overlay using this node when autoPosition is false.

content

The content of the overlay

Type

glow.dom.NodeList

isShown

True if the overlay is showing

Type

returnTo

Element to give focus to when the overlay closes

Type

selector | | glow.dom.NodeList

Description

For accessibility purposes you may want to set an element to give focus to when the overlay closes. This meanss devices which present data to the user by the cursor position (such as screen readers) will be sent somewhere useful.

Methods

hide

Hides the overlay

Synopsis

myOverlay.hide();

Returns

this

setPosition

Change or recalculate the position of the overlay

Synopsis

myOverlay.setPosition(x, y);

Parameters

x

Type

|

Optional

Yes

distance of overlay from the left of the viewport. If the unit is a percentage then 0% is aligned to the left of the viewport, 100% is aligned to the right of viewport and 50% is centered.

y

Type

|

Optional

Yes

distance of overlay from the top of the viewport. If the unit is a percentage then 0% is aligned to the left of the viewport, 100% is aligned to the right of viewport and 50% is centered.

Returns

this

Description

Call with parameters to change the position of the overlay or call without parameters to recalculate the position of the overlay. You may need to call this without parameters if relative positions become invalid.

show

Displays the overlay

Synopsis

myOverlay.show();

Returns

this

Events

show

Fired when the overlay is about to appear on the screen, before any animation.

Synopsis

glow.events.addListener(myOverlay, "show", function(event) {
    // ...
});

Arguments

event

Type

glow.events.Event

Event Object

Description

At this point you can access the content of the overlay and make changes before it is shown to the user. If you prevent the default action of this event (by returning false or calling event.preventDefault) the overlay will not show.

afterShow

Fired when the overlay is visible to the user and any 'show' animation is complete

Synopsis

glow.events.addListener(myOverlay, "afterShow", function(event) {
    // ...
});

Arguments

event

Type

glow.events.Event

Event Object

Description

This event is ideal to assign focus to a particular part of the overlay. If you want to change content of the overlay before it appears, see the 'show' event.

hide

Fired when the overlay is about to hide

Synopsis

glow.events.addListener(myOverlay, "hide", function(event) {
    // ...
});

Arguments

event

Type

glow.events.Event

Event Object

Description

If you prevent the default action of this event (by returning false or calling event.preventDefault) the overlay will not hide.

afterHide

Fired when the overlay has fully hidden, after any hiding animation has completed

Synopsis

glow.events.addListener(myOverlay, "afterHide", function(event) {
    // ...
});

Arguments

event

Type

glow.events.Event

Event Object