|
525
|
1 |
<!DOCTYPE html> |
|
|
2 |
<html lang="en"> |
|
|
3 |
<head> |
|
|
4 |
<meta charset="utf-8"> |
|
|
5 |
<title>Overlay</title> |
|
|
6 |
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic"> |
|
|
7 |
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css"> |
|
|
8 |
<link rel="stylesheet" href="../assets/css/main.css"> |
|
|
9 |
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css"> |
|
|
10 |
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png"> |
|
|
11 |
<script src="../../build/yui/yui-min.js"></script> |
|
|
12 |
|
|
|
13 |
</head> |
|
|
14 |
<body> |
|
|
15 |
<!-- |
|
|
16 |
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a> |
|
|
17 |
--> |
|
|
18 |
<div id="doc"> |
|
|
19 |
<div id="hd"> |
|
|
20 |
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1> |
|
|
21 |
</div> |
|
|
22 |
|
|
|
23 |
<a href="#toc" class="jump">Jump to Table of Contents</a> |
|
|
24 |
|
|
|
25 |
|
|
|
26 |
<h1>Overlay</h1> |
|
|
27 |
<div class="yui3-g"> |
|
|
28 |
<div class="yui3-u-3-4"> |
|
|
29 |
<div id="main"> |
|
|
30 |
<div class="content"><div class="intro"> |
|
|
31 |
<p>Overlay is a positionable and stackable widget, which also provides support for the standard module format layout, with a header, body and footer section. |
|
|
32 |
|
|
|
33 |
<p>The overlay is built by extending the <a href="http://yuilibrary.com/yui/docs/api/Widget.html"><code>Widget</code></a> class and adding the <a href="http://yuilibrary.com/yui/docs/api/WidgetPosition.html"><code>WidgetPosition</code></a>, <a href="http://yuilibrary.com/yui/docs/api/WidgetStack.html"><code>WidgetStack</code></a>, <a href="http://yuilibrary.com/yui/docs/api/WidgetPositionAlign.html"><code>WidgetPositionAlign</code></a>, <a href="http://yuilibrary.com/yui/docs/api/WidgetPositionConstrain.html"><code>WidgetPositionConstrain</code></a> and <a href="http://yuilibrary.com/yui/docs/api/WidgetStdMod.html"><code>WidgetStdMod</code></a> extensions, |
|
|
34 |
and doesn't actually need to add any implementation code of its own. The <a href="../widget/widget-build.html">"Creating Custom Widget Classes"</a> example shows how you can use these extensions to build classes which mix and match some of the above features.</p> |
|
|
35 |
</div> |
|
|
36 |
|
|
|
37 |
<h2 id="getting-started">Getting Started</h2> |
|
|
38 |
|
|
|
39 |
<p> |
|
|
40 |
To include the source files for Overlay and its dependencies, first load |
|
|
41 |
the YUI seed file if you haven't already loaded it. |
|
|
42 |
</p> |
|
|
43 |
|
|
|
44 |
<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre> |
|
|
45 |
|
|
|
46 |
|
|
|
47 |
<p> |
|
|
48 |
Next, create a new YUI instance for your application and populate it with the |
|
|
49 |
modules you need by specifying them as arguments to the <code>YUI().use()</code> method. |
|
|
50 |
YUI will automatically load any dependencies required by the modules you |
|
|
51 |
specify. |
|
|
52 |
</p> |
|
|
53 |
|
|
|
54 |
<pre class="code prettyprint"><script> |
|
|
55 |
// Create a new YUI instance and populate it with the required modules. |
|
|
56 |
YUI().use('overlay', function (Y) { |
|
|
57 |
// Overlay is available and ready for use. Add implementation |
|
|
58 |
// code here. |
|
|
59 |
}); |
|
|
60 |
</script></pre> |
|
|
61 |
|
|
|
62 |
|
|
|
63 |
<p> |
|
|
64 |
For more information on creating YUI instances and on the |
|
|
65 |
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the |
|
|
66 |
documentation for the <a href="../yui/index.html">YUI Global Object</a>. |
|
|
67 |
</p> |
|
|
68 |
|
|
|
69 |
|
|
|
70 |
<p> |
|
|
71 |
<strong>Note:</strong> be sure to add the <code>yui3-skin-sam</code> classname to the |
|
|
72 |
page's <code><body></code> element or to a parent element of the widget in order to apply |
|
|
73 |
the default CSS skin. See <a href="http://yuilibrary.com/yui/docs/tutorials/skins/">Understanding Skinning</a>. |
|
|
74 |
</p> |
|
|
75 |
<pre class="code prettyprint"><body class="yui3-skin-sam"> <!-- You need this skin class --></pre> |
|
|
76 |
|
|
|
77 |
|
|
|
78 |
<h2 id="using">Using Overlay</h2> |
|
|
79 |
|
|
|
80 |
<h3 id="instantiating">Instantiating The Overlay</h3> |
|
|
81 |
|
|
|
82 |
<p>The Overlay widget extends the <code>Widget</code> class, and hence the Overlay constructor follows the same pattern as any Widget constructor, accepting a configuration object to set the initial configuration for the widget.</p> |
|
|
83 |
|
|
|
84 |
<h4 id="instantiating-from-markup-progressive-enhancement">Instantiating From Markup: Progressive Enhancement</h4> |
|
|
85 |
|
|
|
86 |
<p>The overlay can be instantiated from markup, by specifying the <code>srcNode</code> which contains the header, body and footer content for the overlay:</p> |
|
|
87 |
|
|
|
88 |
<pre class="code prettyprint"><div id="myContent"> |
|
|
89 |
<div class="yui3-widget-hd">Overlay Header</div> |
|
|
90 |
<div class="yui3-widget-bd">Overlay Body</div> |
|
|
91 |
<div class="yui3-widget-ft">Overlay Footer</div> |
|
|
92 |
</div></pre> |
|
|
93 |
|
|
|
94 |
|
|
|
95 |
<p>The header, body and footer sections provided in markup need to be marked with the class name which <code>Overlay</code> (or more accurately, <code>WidgetStdMod</code>) expects for the section ("yui3-widget-hd", "yui3-widget-bd" and "yui3-widget-ft") as shown above. |
|
|
96 |
All of these sections are optional. If content is set via the API at a later point the corresponding section will be created dynamically.</p> |
|
|
97 |
|
|
|
98 |
<p>When instantiating from markup, a reference to the <code>srcNode</code> is provided in the configuration object. This reference can be a node reference, or a selector string which can be used to identify the node. If the selector string is too broad (returns multiple nodes), the first node found will be used. |
|
|
99 |
The following code targets the markup shown above:</p> |
|
|
100 |
|
|
|
101 |
<pre class="code prettyprint">YUI({...}).use("overlay", function(Y) { |
|
|
102 |
|
|
|
103 |
//... |
|
|
104 |
var overlay = new Y.Overlay({ |
|
|
105 |
// Specify a reference to a node which already exists |
|
|
106 |
// on the page and contains header/body/footer content |
|
|
107 |
srcNode:"#myContent", |
|
|
108 |
|
|
|
109 |
// Also set some of the attributes inherited from |
|
|
110 |
// the base Widget class. |
|
|
111 |
visible:false, |
|
|
112 |
width:"20em" |
|
|
113 |
}); |
|
|
114 |
//... |
|
|
115 |
|
|
|
116 |
});</pre> |
|
|
117 |
|
|
|
118 |
|
|
|
119 |
<p>Following instantiation, a call to <code>render</code> is required to have the Overlay's state reflected in the DOM, as with all YUI 3 widgets:</p> |
|
|
120 |
|
|
|
121 |
<pre class="code prettyprint">var overlay = new Y.Overlay({ ... }); |
|
|
122 |
overlay.render();</pre> |
|
|
123 |
|
|
|
124 |
|
|
|
125 |
<p>Note that you could set the state of the Overlay multiple times (modifying content, changing dimensions etc.) before rendering. |
|
|
126 |
When the <code>render</code> method is invoked, the state of the Overlay at that point in time will be reflected in the DOM.</p> |
|
|
127 |
|
|
|
128 |
<p>When <code>render</code> is invoked, the overlay's content box will be wrapped by the bounding box (another DIV), to provide the <a href="../widget/index.html#markup">nested box structure</a> common to all widgets.</p> |
|
|
129 |
|
|
|
130 |
<h4 id="instantiating-from-script">Instantiating From Script</h4> |
|
|
131 |
|
|
|
132 |
<p>You can also create Overlay instances entirely from script, setting content programmatically, using the <code>headerContent</code>, <code>bodyContent</code> and <code>footerContent</code> attributes.</p> |
|
|
133 |
|
|
|
134 |
<pre class="code prettyprint">var overlay = new Y.Overlay({ |
|
|
135 |
headerContent:"My Overlay Header", |
|
|
136 |
bodyContent:"My Overlay Body", |
|
|
137 |
footerContent:"My Footer Content", |
|
|
138 |
//... |
|
|
139 |
}); |
|
|
140 |
overlay.render("#parentNode");</pre> |
|
|
141 |
|
|
|
142 |
|
|
|
143 |
<p>Content can be strings containing markup (innerHTML will be used to set the content), or <code>Node</code> references, in which case they will be appended to the section (header, body or footer) node.</p> |
|
|
144 |
|
|
|
145 |
<p>The <code>render</code> method can be passed a node reference (or a selector string) as shown above, to specify the node |
|
|
146 |
under which the overlay's bounding box should be added to the DOM. When rendering an overlay instance which has not been created from markup |
|
|
147 |
(so it does not have a position in the DOM) if this argument is not provided the overlay will be added to the document's body element (inserted as the first child to avoid the potential for "operation aborted" errors in IE6). |
|
|
148 |
</p> |
|
|
149 |
|
|
|
150 |
<h3 id="attributes">Attributes</h3> |
|
|
151 |
|
|
|
152 |
<p>Overlay adds the following key attributes (through the extensions mentioned above), in addition to the attributes provided by the base <a href="../widget/index.html#attributes">Widget</a> class:</p> |
|
|
153 |
|
|
|
154 |
<table> |
|
|
155 |
<tr><th>Attribute</th><th>Description</th></tr> |
|
|
156 |
<tr><td><code>x</code>, <code>y</code> and <code>xy</code></td><td>Positioning attributes, to set the XY position in page coordinates on the Overlay's bounding box. Set to [0,0] by default</td></tr> |
|
|
157 |
<tr><td><code>zIndex</code></td><td>Sets the z-index on the Overlay's bounding box. Set to 0 by default.</td></tr> |
|
|
158 |
<tr><td><code>shim</code></td><td>Boolean, indicating whether or not an iframe shim should be added to the Overlay to protect against select box bleed through. It is only enabled by default for IE6.</td></tr> |
|
|
159 |
<tr><td><code>align</code></td><td>Used to align a specific point on the Overlay's bounding box to a specific point on another node, or the viewport. Set to null by default.</td></tr> |
|
|
160 |
<tr><td><code>centered</code></td><td>Used to center the Overlay inside another node, or inside the viewport. Set to false by default.</td></tr> |
|
|
161 |
<tr><td><code>constrain</code></td><td>Used to specify a node to constrain the Overlay to, when setting the XY position. Can also be set to true, to constrain to the viewport. Set to false by default.</td></tr> |
|
|
162 |
<tr><td><code>headerContent</code></td><td>Used to set the content of the Overlay's header section. No default value set.</td></tr> |
|
|
163 |
<tr><td><code>bodyContent</code></td><td>Used to set the content of the Overlay's body section. No default value set.</td></tr> |
|
|
164 |
<tr><td><code>footerContent</code></td><td>Used to set the content of the Overlay's footer section. No default value set.</td></tr> |
|
|
165 |
<tr><td><code>fillHeight</code></td><td>Specifies which of the 3 sections - header, body or footer, should be automatically sized to fill out the height of the Overlay if a fixed height has been set. Set to WidgetStdMod.BODY by default. Can be disabled by setting to null.</td></tr> |
|
|
166 |
</table> |
|
|
167 |
|
|
|
168 |
<h3 id="positioning">Positioning</h3> |
|
|
169 |
|
|
|
170 |
<h4 id="basic-xy-positioning">Basic XY Positioning</h4> |
|
|
171 |
|
|
|
172 |
<p>Overlay provides basic XY positioning support through its <code>x</code>, <code>y</code> and <code>xy</code> attributes as well as a convenience <code>move</code> method which wraps the <code>xy</code> attribute.</p> |
|
|
173 |
|
|
|
174 |
<p>The xy position of the overlay can be set in the constructor, as with any attribute value:</p> |
|
|
175 |
|
|
|
176 |
<pre class="code prettyprint">var overlay = new Y.Overlay({ |
|
|
177 |
srcNode:"#myContent", |
|
|
178 |
xy: [200,100] |
|
|
179 |
}); |
|
|
180 |
overlay.render(); |
|
|
181 |
|
|
|
182 |
// or |
|
|
183 |
|
|
|
184 |
var overlay = new Y.Overlay({ |
|
|
185 |
srcNode:"#myContent", |
|
|
186 |
x: 200, |
|
|
187 |
y: 100 |
|
|
188 |
}); |
|
|
189 |
overlay.render(); |
|
|
190 |
|
|
|
191 |
// or |
|
|
192 |
|
|
|
193 |
var overlay = new Y.Overlay({ |
|
|
194 |
srcNode:"#myContent", |
|
|
195 |
x: 200 // y defaults to 0 |
|
|
196 |
}); |
|
|
197 |
overlay.render();</pre> |
|
|
198 |
|
|
|
199 |
|
|
|
200 |
<p>The overlay's default position, if xy values are not provided, will be 0,0. Note that xy are page coordinates, not relative coordinates.</p> |
|
|
201 |
|
|
|
202 |
<p>Changes in the overlay's position, when set programmatically through the API, can be monitored by listening for the attribute <code>xyChange</code> event. Listeners |
|
|
203 |
to this event will receive an event facade, which contains previous and new xy values:</p> |
|
|
204 |
|
|
|
205 |
<pre class="code prettyprint">// Listen to the "on" moment, if you're interested in |
|
|
206 |
// preventing the change in position from occurring. |
|
|
207 |
overlay.on("xyChange", function(e) { |
|
|
208 |
|
|
|
209 |
var currPosition = e.prevVal; |
|
|
210 |
var newPosition = e.newVal; |
|
|
211 |
|
|
|
212 |
if (newPosition[0] > MAX_X || newPosition[1] > MAX_Y) { |
|
|
213 |
// Stop move from occurring. |
|
|
214 |
e.preventDefault(); |
|
|
215 |
} |
|
|
216 |
}); |
|
|
217 |
|
|
|
218 |
// Listen to the "after" moment, if you're just interested |
|
|
219 |
// in being notified when the position has been changed. |
|
|
220 |
overlay.after("xyChange", function(e) { |
|
|
221 |
var position = e.newVal; |
|
|
222 |
console.log("Overlay has been moved to: " + position[0] + "," position[1]); |
|
|
223 |
});</pre> |
|
|
224 |
|
|
|
225 |
|
|
|
226 |
<p>Note that changing just the <code>x</code> or <code>y</code> attribute value, individually, will still fire the <code>xy</code> change event. The <code>x</code> and |
|
|
227 |
<code>y</code> attribute values are simply convenience wrappers which end up setting the <code>xy</code> attribute.</p> |
|
|
228 |
|
|
|
229 |
<p>XY position can also be set after construction, as with any attribute, using <code>set</code> to change the attribute value directly, or using the <code>move</code> method:</p> |
|
|
230 |
|
|
|
231 |
<pre class="code prettyprint">overlay.set("x", 100); |
|
|
232 |
|
|
|
233 |
overlay.set("y", 200); |
|
|
234 |
|
|
|
235 |
overlay.set("xy", [100,200]); |
|
|
236 |
|
|
|
237 |
overlay.move(100,200); |
|
|
238 |
|
|
|
239 |
overlay.move([100,200]);</pre> |
|
|
240 |
|
|
|
241 |
|
|
|
242 |
<p>The <a href="overlay-xy.html">Basic XY Positioning</a> example shows basic positioning in action.</p> |
|
|
243 |
|
|
|
244 |
<h4 id="extended-xy-positioning">Extended XY Positioning</h4> |
|
|
245 |
|
|
|
246 |
<p>Overlay also provides support to help position it relative to another node on the page, or the viewport, through the <code>align</code> and <code>centered</code> attributes, as well as |
|
|
247 |
the corresponding <code>align()</code> and <code>centered()</code> convenience methods, through the application of the <code>WidgetPositionAlign</code> extension.</p> |
|
|
248 |
|
|
|
249 |
<p>The <code>align</code> attribute accepts as a value an object literal with the following properties:</p> |
|
|
250 |
<dl> |
|
|
251 |
<dt>node</dt> |
|
|
252 |
<dd> |
|
|
253 |
The node to which the Widget is to be aligned. If set to null, or not provided, the Overlay is aligned to the viewport |
|
|
254 |
</dd> |
|
|
255 |
<dt>points</dt> |
|
|
256 |
<dd> |
|
|
257 |
<p> |
|
|
258 |
A two element array, defining the two points on the Overlay and node which are to be aligned. The first element is the point on the Overlay, and the second element is the point on the node (or viewport). |
|
|
259 |
Supported alignment points are defined as static properties on <a href="http://yuilibrary.com/yui/docs/api/WidgetPositionAlign.html#property_WidgetPositionAlign.TL"><code>WidgetPositionAlign</code></a>. For example: |
|
|
260 |
</p> |
|
|
261 |
<p> |
|
|
262 |
<code>[Y.WidgetPositionAlign.TR, Y.WidgetPositionAlign.TL]</code> aligns the Top-Right corner of the Overlay with the |
|
|
263 |
Top-Left corner of the node/viewport, and <code>[Y.WidgetPositionAlign.CC, Y.WidgetPositionAlign.TC]</code> aligns the Center of the |
|
|
264 |
Overlay with the Top-Center edge of the node/viewport. |
|
|
265 |
</p> |
|
|
266 |
</dd> |
|
|
267 |
</dl> |
|
|
268 |
|
|
|
269 |
<pre class="code prettyprint">// Align the: |
|
|
270 |
// top-left corner of the overlay, with the |
|
|
271 |
// top-right corner of the node with id = "okBtn" |
|
|
272 |
overlay.set("align", { |
|
|
273 |
node:"#okBtn", |
|
|
274 |
points:[Y.WidgetPositionAlign.TL, Y.WidgetPositionAlign.TR] |
|
|
275 |
}); |
|
|
276 |
|
|
|
277 |
// Align the: |
|
|
278 |
// right-center edge of the overlay, with the |
|
|
279 |
// right-center edge of the viewport (no node specified) |
|
|
280 |
overlay.set("align", { |
|
|
281 |
points:[Y.WidgetPositionAlign.RC, Y.WidgetPositionAlign.RC] |
|
|
282 |
}); |
|
|
283 |
|
|
|
284 |
// Align the: |
|
|
285 |
// center of the overlay, with the |
|
|
286 |
// top-left corner of the node with id = "okBtn" |
|
|
287 |
overlay.align("#okBtn", [Y.WidgetPositionAlign.CC, Y.WidgetPositionAlign.TL]);</pre> |
|
|
288 |
|
|
|
289 |
|
|
|
290 |
<p>The <code>centered</code> property can either by set to <code>true</code> to center the Overlay in the viewport, or set to a selector string or node reference to center the Overlay in a particular node.</p> |
|
|
291 |
|
|
|
292 |
<pre class="code prettyprint">// Center the overlay in the node with id = "module" |
|
|
293 |
overlay.set("centered", "#module"); |
|
|
294 |
|
|
|
295 |
// Center the overlay in the viewport |
|
|
296 |
overlay.set("centered", true);</pre> |
|
|
297 |
|
|
|
298 |
|
|
|
299 |
<p>The <a href="overlay-align.html">"Alignment Support"</a> example shows aligned positioning support in action.</p> |
|
|
300 |
|
|
|
301 |
<p>Note that currently alignment/centering is not maintained when the viewport is scrolled, window resized etc. Support to re-align the overlay on a default and custom set of trigger events will be |
|
|
302 |
provided in a future release.</p> |
|
|
303 |
|
|
|
304 |
<p>In addition to being able to align the overlay to a given element (or the viewport), overlay also supports the ability to constrain its XY position to a given node, or to the viewport.</p> |
|
|
305 |
|
|
|
306 |
<pre class="code prettyprint">// Constrains the XY position to a given node: |
|
|
307 |
overlay.set("constrain", "#constrainingNode"); |
|
|
308 |
|
|
|
309 |
// Or to the viewport |
|
|
310 |
overlay.set("constrain", true);</pre> |
|
|
311 |
|
|
|
312 |
|
|
|
313 |
<p>The <a href="overlay-constrain.html">"Constrain Support"</a> example shows constrained positioning in action.</p> |
|
|
314 |
|
|
|
315 |
<h3 id="stacking">Stacking</h3> |
|
|
316 |
|
|
|
317 |
<p> |
|
|
318 |
The Overlay provides basic stacking support in the form of a <code>zIndex</code> attribute and a <code>shim</code> attribute. The shimming support protects against <select> box bleed through on |
|
|
319 |
IE6 (It is enabled by default for IE6) by adding an iframe shim to the overlay's bounding box (positioned underneath the content box). The default value of the <code>zIndex</code> attribute is 0.</p> |
|
|
320 |
|
|
|
321 |
<p>Using the <code>zIndex</code> and <code>shim</code> attributes is the same as any other attribute, with the ability to set values in the constructor, or at a later point in time:</p> |
|
|
322 |
|
|
|
323 |
<pre class="code prettyprint">// Disable shim for all browsers, set zIndex to 10 |
|
|
324 |
var overlay = new Y.Overlay({ |
|
|
325 |
shim:false, // Disable for all browsers, including IE6 |
|
|
326 |
zIndex:10 |
|
|
327 |
}); |
|
|
328 |
|
|
|
329 |
// Set zIndex to 10. Shim is enabled for IE6 but disabled for all |
|
|
330 |
// other browsers (default value) |
|
|
331 |
var overlay = new Y.Overlay({ |
|
|
332 |
zIndex:10 |
|
|
333 |
});</pre> |
|
|
334 |
|
|
|
335 |
|
|
|
336 |
<p>The <a href="overlay-stack.html">"Stack Support"</a> example creates a simple "bringToTop" implementation based on the <code>zIndex</code> attribute. |
|
|
337 |
This support will be provided as part of Overlay itself (or more precisely, as part of <code>WidgetStack</code>) in a future release.</p> |
|
|
338 |
|
|
|
339 |
<h3 id="content">Setting Section Content</h3> |
|
|
340 |
|
|
|
341 |
<p>Overlay uses the standard module format for its rendering. It provides a header, body and footer section as described above (through the <code>WidgetStdMod</code> extension).</p> |
|
|
342 |
|
|
|
343 |
<h4 id="replacing-content">Replacing Content</h4> |
|
|
344 |
|
|
|
345 |
<p>The content for each of these sections is settable either through the <code>headerContent</code>, <code>bodyContent</code> and <code>footerContent</code> attributes. Setting the content |
|
|
346 |
through these properties will replace any existing content in the section. The content can either be specified as a string, in which case innerHTML will be used to set the new content, or |
|
|
347 |
specified as a <code>Node</code> instance, in which case the content will be added to the respective section using <code>appendChild</code> after clearing existing content.</p> |
|
|
348 |
|
|
|
349 |
<pre class="code prettyprint">var overlay = new Y.Overlay({ |
|
|
350 |
headerContent: '<span class="title">My Header Content</span>', |
|
|
351 |
bodyContent: '<div class="mod">My Body Content</div>' |
|
|
352 |
// Don't want a footer |
|
|
353 |
}); |
|
|
354 |
|
|
|
355 |
// or |
|
|
356 |
|
|
|
357 |
overlay.set("headerContent", '<span class="title">My Header Content</span>'); |
|
|
358 |
|
|
|
359 |
// or |
|
|
360 |
|
|
|
361 |
var headerContent = Y.Node.create("<span></span>"); |
|
|
362 |
headerContent.set("innerHTML", "My Header Content"); |
|
|
363 |
headerContent.addClass("title"); |
|
|
364 |
|
|
|
365 |
overlay.set("headerContent", headerContent);</pre> |
|
|
366 |
|
|
|
367 |
|
|
|
368 |
<p>Overlay will not create the section if there has been no content set for it. (So, for example, the overlay above will not have a footer section). Also, if the section doesn't exist it will be created, |
|
|
369 |
the first time content is set for it.</p> |
|
|
370 |
|
|
|
371 |
<p>As with any attribute change, you can listen for (and prevent) changes in content by listening for the corresponding attribute change event:</p> |
|
|
372 |
|
|
|
373 |
<pre class="code prettyprint">overlay.on("bodyContentChange", function(e) { |
|
|
374 |
if (someCondition) { |
|
|
375 |
// Don't allow body content to be updated |
|
|
376 |
e.preventDefault(): |
|
|
377 |
} |
|
|
378 |
}); |
|
|
379 |
|
|
|
380 |
overlay.after("bodyContentChange", function(e) { |
|
|
381 |
// body section has been modified |
|
|
382 |
});</pre> |
|
|
383 |
|
|
|
384 |
|
|
|
385 |
<p>Setting content in any of the sections will fire Widget's <code>contentUpdate</code> event, which can be monitored if you want to be notified of changes to any section. However, this event is purely a catch-all notification |
|
|
386 |
event. It cannot be prevented to stop the content change from occurring:</p> |
|
|
387 |
|
|
|
388 |
<pre class="code prettyprint">overlay.after("contentUpdate", function(e) { |
|
|
389 |
// Content has been updated in one of the standard module sections. |
|
|
390 |
});</pre> |
|
|
391 |
|
|
|
392 |
|
|
|
393 |
<h4 id="insertingappending-content">Inserting/Appending Content</h4> |
|
|
394 |
|
|
|
395 |
<p>Setting content using the attributes mentioned above always results in content being replaced. If you need to insert content before, or append content after existing content in the section, you can use the <code>setStdModContent(section, content, where)</code> method Overlay provides:</p> |
|
|
396 |
|
|
|
397 |
<pre class="code prettyprint">overlay.setStdModContent( |
|
|
398 |
Y.WidgetStdMod.HEADER, // Section |
|
|
399 |
"New Content To Insert", // Content |
|
|
400 |
Y.WidgetStdMod.BEFORE // Where |
|
|
401 |
); |
|
|
402 |
|
|
|
403 |
overlay.setStdModContent( |
|
|
404 |
Y.WidgetStdMod.FOOTER, // Section |
|
|
405 |
"New Content To Append", // Content |
|
|
406 |
Y.WidgetStdMod.AFTER // Where |
|
|
407 |
);</pre> |
|
|
408 |
|
|
|
409 |
|
|
|
410 |
<ul> |
|
|
411 |
<li>The <code>section</code> argument specifies which section is to be updated. The constants <code>WidgetStdMod.HEADER</code>, <code>WidgetStdMod.BODY</code> and <code>WidgetStdMod.FOOTER</code> define valid values.</li> |
|
|
412 |
<li>The <code>content</code> argument specifies the new content to be added which, as with the attributes, can be a string HTML value or a node reference.</li> |
|
|
413 |
<li>The <code>where</code> argument specifies whether the content should be added before, after, or replace existing content. The constants <code>WidgetStdMod.BEFORE</code>, <code>WidgetStdMod.AFTER</code> and <code>WidgetStdMod.REPLACE</code></p> define valid values.</li> |
|
|
414 |
</ul> |
|
|
415 |
|
|
|
416 |
<p><em>Note, the above <code>WidgetStdMod</code> constants define the set of valid values wherever the API expects a "section" or "where" argument.</em></p> |
|
|
417 |
|
|
|
418 |
<p>The content change events mentioned above, will be fired when content is set through the <code>setStdModContent</code> method just as they would when setting the content using the attribute.</p> |
|
|
419 |
|
|
|
420 |
<p>The <a href="overlay-stdmod.html">Standard Module</a> example provides a way to exercise the above content attributes and methods.</p> |
|
|
421 |
|
|
|
422 |
<h3 id="markup">Markup Structure</h3> |
|
|
423 |
|
|
|
424 |
<p>The final rendered Overlay has the markup structure shown below:</p> |
|
|
425 |
|
|
|
426 |
<pre class="code prettyprint"><div class="yui3-widget yui3-overlay yui3-widget-positioned yui3-widget-stacked"> |
|
|
427 |
<!--Bounding Box--> |
|
|
428 |
<div class="yui3-overlay-content yui3-widget-stdmod"> |
|
|
429 |
<!--Content Box--> |
|
|
430 |
<div class="yui3-widget-hd">Overlay Header Content</div> |
|
|
431 |
<!--Header Section--> |
|
|
432 |
<div class="yui3-widget-bd">Overlay Body Content</div> |
|
|
433 |
<!--Body Section--> |
|
|
434 |
<div class="yui3-widget-ft">Overlay Footer Content</div> |
|
|
435 |
<!--Footer Section--> |
|
|
436 |
</div> |
|
|
437 |
|
|
|
438 |
<iframe class="yui3-widget-shim"></iframe> |
|
|
439 |
<!-- Stacking shim, if enabled--> |
|
|
440 |
|
|
|
441 |
</div></pre> |
|
|
442 |
|
|
|
443 |
|
|
|
444 |
<p>The bounding box is absolutely positioned by default, and top/left positioning and z-index values are applied to it. The nested bounding box/content box structure is discussed in detail on the <a href="../widget/index.html#markup">Widget markup discussion</a>.</p> |
|
|
445 |
|
|
|
446 |
<p>In addition to the default classes applied to the bounding box and content box for all widgets ("yui3-overlay", "yui3-overlay-content", "yui3-widget"), the <code>WidgetStdMod</code>, <code>WidgetPositioned</code> and <code>WidgetStack</code> extensions also mark the appropriate boxes with |
|
|
447 |
"yui3-widget-stdmod", "yui3-widget-positioned" and "yui3-widget-stacked" classes as shown above.</p> |
|
|
448 |
|
|
|
449 |
<p>The iframe shim, added if <code>shim</code> is enabled, is added to the bounding box, as sibling to the content box and stacked underneath it (using a -ve z-index).</p> |
|
|
450 |
|
|
|
451 |
<h3 id="css">CSS</h3> |
|
|
452 |
|
|
|
453 |
<p>Overlay is a generic, foundation widget and doesn't ship with a default look/feel out of the box. Its Sam Skin (build/overlay/assets/skins/sam/overlay.css) implementation consists only of core functional rules, to control how it is positioned and how it is hidden:</p> |
|
|
454 |
|
|
|
455 |
<pre class="code prettyprint">.yui3-overlay { |
|
|
456 |
position:absolute; |
|
|
457 |
} |
|
|
458 |
|
|
|
459 |
.yui3-overlay-hidden { |
|
|
460 |
visibility:hidden |
|
|
461 |
}</pre> |
|
|
462 |
|
|
|
463 |
|
|
|
464 |
<p>Since it includes the <code>WidgetStack</code> extension, the following functional CSS is also provided (through build/widget/assets/skins/sam/widget-stack.css) to handle the shim element, |
|
|
465 |
(along with the Gecko/Mac scroll bar support CSS mentioned above)</p> |
|
|
466 |
|
|
|
467 |
<pre class="code prettyprint">.yui3-widget-stacked .yui3-widget-shim { |
|
|
468 |
opacity: 0; |
|
|
469 |
filter: alpha(opacity=0); |
|
|
470 |
position: absolute; |
|
|
471 |
border: none; |
|
|
472 |
top: 0px; |
|
|
473 |
left: 0px; |
|
|
474 |
padding: 0; |
|
|
475 |
margin: 0; |
|
|
476 |
z-index: -1; |
|
|
477 |
width: 100%; |
|
|
478 |
height: 100%; |
|
|
479 |
/* |
|
|
480 |
We'll be setting these programmatically for IE6, |
|
|
481 |
to account for cases where height is not set |
|
|
482 |
*/ |
|
|
483 |
_width: 0; |
|
|
484 |
_height: 0; |
|
|
485 |
}</pre> |
|
|
486 |
|
|
|
487 |
</div> |
|
|
488 |
</div> |
|
|
489 |
</div> |
|
|
490 |
|
|
|
491 |
<div class="yui3-u-1-4"> |
|
|
492 |
<div class="sidebar"> |
|
|
493 |
|
|
|
494 |
<div id="toc" class="sidebox"> |
|
|
495 |
<div class="hd"> |
|
|
496 |
<h2 class="no-toc">Table of Contents</h2> |
|
|
497 |
</div> |
|
|
498 |
|
|
|
499 |
<div class="bd"> |
|
|
500 |
<ul class="toc"> |
|
|
501 |
<li> |
|
|
502 |
<a href="#getting-started">Getting Started</a> |
|
|
503 |
</li> |
|
|
504 |
<li> |
|
|
505 |
<a href="#using">Using Overlay</a> |
|
|
506 |
<ul class="toc"> |
|
|
507 |
<li> |
|
|
508 |
<a href="#instantiating">Instantiating The Overlay</a> |
|
|
509 |
<ul class="toc"> |
|
|
510 |
<li> |
|
|
511 |
<a href="#instantiating-from-markup-progressive-enhancement">Instantiating From Markup: Progressive Enhancement</a> |
|
|
512 |
</li> |
|
|
513 |
<li> |
|
|
514 |
<a href="#instantiating-from-script">Instantiating From Script</a> |
|
|
515 |
</li> |
|
|
516 |
</ul> |
|
|
517 |
</li> |
|
|
518 |
<li> |
|
|
519 |
<a href="#attributes">Attributes</a> |
|
|
520 |
</li> |
|
|
521 |
<li> |
|
|
522 |
<a href="#positioning">Positioning</a> |
|
|
523 |
<ul class="toc"> |
|
|
524 |
<li> |
|
|
525 |
<a href="#basic-xy-positioning">Basic XY Positioning</a> |
|
|
526 |
</li> |
|
|
527 |
<li> |
|
|
528 |
<a href="#extended-xy-positioning">Extended XY Positioning</a> |
|
|
529 |
</li> |
|
|
530 |
</ul> |
|
|
531 |
</li> |
|
|
532 |
<li> |
|
|
533 |
<a href="#stacking">Stacking</a> |
|
|
534 |
</li> |
|
|
535 |
<li> |
|
|
536 |
<a href="#content">Setting Section Content</a> |
|
|
537 |
<ul class="toc"> |
|
|
538 |
<li> |
|
|
539 |
<a href="#replacing-content">Replacing Content</a> |
|
|
540 |
</li> |
|
|
541 |
<li> |
|
|
542 |
<a href="#insertingappending-content">Inserting/Appending Content</a> |
|
|
543 |
</li> |
|
|
544 |
</ul> |
|
|
545 |
</li> |
|
|
546 |
<li> |
|
|
547 |
<a href="#markup">Markup Structure</a> |
|
|
548 |
</li> |
|
|
549 |
<li> |
|
|
550 |
<a href="#css">CSS</a> |
|
|
551 |
</li> |
|
|
552 |
</ul> |
|
|
553 |
</li> |
|
|
554 |
</ul> |
|
|
555 |
</div> |
|
|
556 |
</div> |
|
|
557 |
|
|
|
558 |
|
|
|
559 |
|
|
|
560 |
<div class="sidebox"> |
|
|
561 |
<div class="hd"> |
|
|
562 |
<h2 class="no-toc">Examples</h2> |
|
|
563 |
</div> |
|
|
564 |
|
|
|
565 |
<div class="bd"> |
|
|
566 |
<ul class="examples"> |
|
|
567 |
|
|
|
568 |
|
|
|
569 |
<li data-description="Shows how to instantiate a basic Overlay instance, and use the Overlay's basic XY positioning support."> |
|
|
570 |
<a href="overlay-xy.html">Basic XY Positioning</a> |
|
|
571 |
</li> |
|
|
572 |
|
|
|
573 |
|
|
|
574 |
|
|
|
575 |
<li data-description="Shows how to create a simple tooltip incorporating the overlay shim feature."> |
|
|
576 |
<a href="overlay-tooltip.html">Simple Tooltip</a> |
|
|
577 |
</li> |
|
|
578 |
|
|
|
579 |
|
|
|
580 |
|
|
|
581 |
<li data-description="Shows how to use the Overlay's XY alignment support, to align the Overlay relative to another element, or to the viewport."> |
|
|
582 |
<a href="overlay-align.html">Alignment Support</a> |
|
|
583 |
</li> |
|
|
584 |
|
|
|
585 |
|
|
|
586 |
|
|
|
587 |
<li data-description="Shows how to use the Overlay's zindex and shim support when positioning Overlays above other elements on the page."> |
|
|
588 |
<a href="overlay-stack.html">Stack Support</a> |
|
|
589 |
</li> |
|
|
590 |
|
|
|
591 |
|
|
|
592 |
|
|
|
593 |
<li data-description="Shows how to modify content in the Overlay's header, body and footer sections."> |
|
|
594 |
<a href="overlay-stdmod.html">Standard Module Support</a> |
|
|
595 |
</li> |
|
|
596 |
|
|
|
597 |
|
|
|
598 |
|
|
|
599 |
<li data-description="Shows how to use Overlay's constrainment support, to limit the XY value which can be set for an Overlay."> |
|
|
600 |
<a href="overlay-constrain.html">Constrain Support</a> |
|
|
601 |
</li> |
|
|
602 |
|
|
|
603 |
|
|
|
604 |
|
|
|
605 |
<li data-description="Shows how to create a simple plugin to retrieve content for the Overlay using the io utility."> |
|
|
606 |
<a href="overlay-io-plugin.html">IO Plugin</a> |
|
|
607 |
</li> |
|
|
608 |
|
|
|
609 |
|
|
|
610 |
|
|
|
611 |
<li data-description="Shows how to create a simple plugin to animate the Overlay's movement and visibility."> |
|
|
612 |
<a href="overlay-anim-plugin.html">Animation Plugin</a> |
|
|
613 |
</li> |
|
|
614 |
|
|
|
615 |
|
|
|
616 |
|
|
|
617 |
|
|
|
618 |
|
|
|
619 |
|
|
|
620 |
</ul> |
|
|
621 |
</div> |
|
|
622 |
</div> |
|
|
623 |
|
|
|
624 |
|
|
|
625 |
|
|
|
626 |
<div class="sidebox"> |
|
|
627 |
<div class="hd"> |
|
|
628 |
<h2 class="no-toc">Examples That Use This Component</h2> |
|
|
629 |
</div> |
|
|
630 |
|
|
|
631 |
<div class="bd"> |
|
|
632 |
<ul class="examples"> |
|
|
633 |
|
|
|
634 |
|
|
|
635 |
|
|
|
636 |
|
|
|
637 |
|
|
|
638 |
|
|
|
639 |
|
|
|
640 |
|
|
|
641 |
|
|
|
642 |
|
|
|
643 |
|
|
|
644 |
|
|
|
645 |
|
|
|
646 |
|
|
|
647 |
|
|
|
648 |
|
|
|
649 |
|
|
|
650 |
|
|
|
651 |
<li data-description="Creating an accessible menu button using the Focus Manager Node Plugin, Event's delegation support and mouseenter event, along with the Overlay widget and Node's support for the WAI-ARIA Roles and States."> |
|
|
652 |
<a href="../node-focusmanager/node-focusmanager-button.html">Accessible Menu Button</a> |
|
|
653 |
</li> |
|
|
654 |
|
|
|
655 |
|
|
|
656 |
|
|
|
657 |
<li data-description="Use StyleSheet to adjust the CSS rules applying a page theme from user input"> |
|
|
658 |
<a href="../stylesheet/stylesheet-theme.html">Adjusting a Page Theme on the Fly</a> |
|
|
659 |
</li> |
|
|
660 |
|
|
|
661 |
|
|
|
662 |
</ul> |
|
|
663 |
</div> |
|
|
664 |
</div> |
|
|
665 |
|
|
|
666 |
</div> |
|
|
667 |
</div> |
|
|
668 |
</div> |
|
|
669 |
</div> |
|
|
670 |
|
|
|
671 |
<script src="../assets/vendor/prettify/prettify-min.js"></script> |
|
|
672 |
<script>prettyPrint();</script> |
|
|
673 |
|
|
|
674 |
<script> |
|
|
675 |
YUI.Env.Tests = { |
|
|
676 |
examples: [], |
|
|
677 |
project: '../assets', |
|
|
678 |
assets: '../assets/overlay', |
|
|
679 |
name: 'overlay', |
|
|
680 |
title: 'Overlay', |
|
|
681 |
newWindow: '', |
|
|
682 |
auto: false |
|
|
683 |
}; |
|
|
684 |
YUI.Env.Tests.examples.push('overlay-xy'); |
|
|
685 |
YUI.Env.Tests.examples.push('overlay-tooltip'); |
|
|
686 |
YUI.Env.Tests.examples.push('overlay-align'); |
|
|
687 |
YUI.Env.Tests.examples.push('overlay-stack'); |
|
|
688 |
YUI.Env.Tests.examples.push('overlay-stdmod'); |
|
|
689 |
YUI.Env.Tests.examples.push('overlay-constrain'); |
|
|
690 |
YUI.Env.Tests.examples.push('overlay-io-plugin'); |
|
|
691 |
YUI.Env.Tests.examples.push('overlay-anim-plugin'); |
|
|
692 |
YUI.Env.Tests.examples.push('node-focusmanager-button'); |
|
|
693 |
YUI.Env.Tests.examples.push('stylesheet-theme'); |
|
|
694 |
|
|
|
695 |
</script> |
|
|
696 |
<script src="../assets/yui/test-runner.js"></script> |
|
|
697 |
|
|
|
698 |
|
|
|
699 |
|
|
|
700 |
</body> |
|
|
701 |
</html> |