Version 1.7 glow.widgets.Overlay
API Quick Reference
JavaScript is required to use the quick reference
A container element displayed on top of the other page content
glow.ready() call.Further Info & Examples
Constructor
new glow.widgets.Overlay(content, opts)Parameters
- content
- Type
- selector | Element | 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
- Object
Zero or more of the following as properties of an object:
- anim
A transition for showing / hiding the panel
- ariaProperties
Key-value pairs of aria properties and values
- Type
- Object
- 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
- String
- Optional
- Yes
This is used for accessibility purposes. No role is defined by default.
- autoPosition
Position the overlay relative to the viewport
- Type
- Boolean
- 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
- String
- Optional
- Yes
- closeOnEsc
Close the overlay when the ESC key is pressed
- Type
- Boolean
- 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
- Boolean
- Default
- "true"
- Optional
- Yes
- focusOnShow
Give the overlay keyboard focus when it appears?
- Type
- Boolean
- Default
- false
- Optional
- Yes
Use 'returnTo' to specify where to send focus when the overlay closes
- hideFilter
Exclude elements from hiding
- Type
- Function
- 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 | Element | 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
- Boolean
- 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
- String
- 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
- Boolean
- 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 | Element | 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
- y
Distance of overlay from the top of the viewport
- zIndex
The z-index to set on the overlay
- Type
- Number
- 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
- Boolean
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.
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
- isShown
True if the overlay is showing
- Type
- Boolean
- returnTo
Element to give focus to when the overlay closes
- Type
- selector | Element | 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
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
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
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
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
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
Event Object
