~bcsaller/juju-gui/update-reductions

<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.

<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,

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>

</div>

<h2 id="getting-started">Getting Started</h2>

<p>

To include the source files for Overlay and its dependencies, first load

the YUI seed file if you haven't already loaded it.

</p>

<p>

Next, create a new YUI instance for your application and populate it with the

modules you need by specifying them as arguments to the <code>YUI().use()</code> method.

YUI will automatically load any dependencies required by the modules you

specify.

</p>

// Create a new YUI instance and populate it with the required modules.

YUI().use('overlay', function (Y) {

// Overlay is available and ready for use. Add implementation

// code here.

});

</script></pre>

<p>

For more information on creating YUI instances and on the

<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the

documentation for the <a href="../yui/index.html">YUI Global Object</a>.

</p>

<h2 id="using">Using Overlay</h2>

<h3 id="instantiating">Instantiating The Overlay</h3>

<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>

<h4 id="instantiating-from-markup-progressive-enhancement">Instantiating From Markup: Progressive Enhancement</h4>

<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>

<div class="yui3-widget-hd">Overlay Header</div>

<div class="yui3-widget-bd">Overlay Body</div>

<div class="yui3-widget-ft">Overlay Footer</div>

</div></pre>

<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.

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>

<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.

The following code targets the markup shown above:</p>

<pre class="code prettyprint">YUI({...}).use("overlay", function(Y) {

//...

var overlay = new Y.Overlay({

// Specify a reference to a node which already exists

// on the page and contains header/body/footer content

srcNode:"#myContent",

// Also set some of the attributes inherited from

// the base Widget class.

visible:false,

width:"20em"

});

100

//...

101

102

});</pre>

103

104

105

<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>

106

107

<pre class="code prettyprint">var overlay = new Y.Overlay({ ... });

108

overlay.render();</pre>

109

110

111

<p>Note that you could set the state of the Overlay multiple times (modifying content, changing dimensions etc.) before rendering.

112

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>

113

114

<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>

115

116

<h4 id="instantiating-from-script">Instantiating From Script</h4>

117

118

<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>

119

120

<pre class="code prettyprint">var overlay = new Y.Overlay({

121

headerContent:"My Overlay Header",

122

bodyContent:"My Overlay Body",

123

footerContent:"My Footer Content",

124

//...

125

});

126

overlay.render("#parentNode");</pre>

127

128

129

<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>

130

131

<p>The <code>render</code> method can be passed a node reference (or a selector string) as shown above, to specify the node

132

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

133

(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).

134

</p>

135

136

<h3 id="attributes">Attributes</h3>

137

138

<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>

139

140

<table>

141

<tr><th>Attribute</th><th>Description</th></tr>

142

<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>

143

<tr><td><code>zIndex</code></td><td>Sets the z-index on the Overlay's bounding box. Set to 0 by default.</td></tr>

144

<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>

145

<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>

146

<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>

147

<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>

148

<tr><td><code>headerContent</code></td><td>Used to set the content of the Overlay's header section. No default value set.</td></tr>

149

<tr><td><code>bodyContent</code></td><td>Used to set the content of the Overlay's body section. No default value set.</td></tr>

150

<tr><td><code>footerContent</code></td><td>Used to set the content of the Overlay's footer section. No default value set.</td></tr>

151

<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>

152

</table>

153

154

<h3 id="positioning">Positioning</h3>

155

156

<h4 id="basic-xy-positioning">Basic XY Positioning</h4>

157

158

<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>

159

160

<p>The xy position of the overlay can be set in the constructor, as with any attribute value:</p>

161

162

<pre class="code prettyprint">var overlay = new Y.Overlay({

163

srcNode:"#myContent",

164

xy: [200,100]

165

});

166

overlay.render();

167

168

// or

169

170

var overlay = new Y.Overlay({

171

srcNode:"#myContent",

172

x: 200,

173

y: 100

174

});

175

overlay.render();

176

177

// or

178

179

var overlay = new Y.Overlay({

180

srcNode:"#myContent",

181

x: 200 // y defaults to 0

182

});

183

overlay.render();</pre>

184

185

186

<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>

187

188

<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

189

to this event will receive an event facade, which contains previous and new xy values:</p>

190

191

<pre class="code prettyprint">// Listen to the "on" moment, if you're interested in

192

// preventing the change in position from occurring.

193

overlay.on("xyChange", function(e) {

194

195

var currPosition = e.prevVal;

196

var newPosition = e.newVal;

197

198

if (newPosition[0] > MAX_X || newPosition[1] > MAX_Y) {

199

// Stop move from occurring.

200

e.preventDefault();

201

}

202

});

203

204

// Listen to the "after" moment, if you're just interested

205

// in being notified when the position has been changed.

206

overlay.after("xyChange", function(e) {

207

var position = e.newVal;

208

console.log("Overlay has been moved to: " + position[0] + "," position[1]);

209

});</pre>

210

211

212

<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

213

<code>y</code> attribute values are simply convenience wrappers which end up setting the <code>xy</code> attribute.</p>

214

215

<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>

216

217

<pre class="code prettyprint">overlay.set("x", 100);

218

219

overlay.set("y", 200);

220

221

overlay.set("xy", [100,200]);

222

223

overlay.move(100,200);

224

225

overlay.move([100,200]);</pre>

226

227

228

<p>The <a href="overlay-xy.html">Basic XY Positioning</a> example shows basic positioning in action.</p>

229

230

<h4 id="extended-xy-positioning">Extended XY Positioning</h4>

231

232

<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

233

the corresponding <code>align()</code> and <code>centered()</code> convenience methods, through the application of the <code>WidgetPositionAlign</code> extension.</p>

234

235

<p>The <code>align</code> attribute accepts as a value an object literal with the following properties:</p>

236

<dl>

237

238

<dd>

239

The node to which the Widget is to be aligned. If set to null, or not provided, the Overlay is aligned to the viewport

240

</dd>

241

<dt>points</dt>

242

<dd>

243

<p>

244

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).

245

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:

246

</p>

247

<p>

248

<code>[Y.WidgetPositionAlign.TR, Y.WidgetPositionAlign.TL]</code> aligns the Top-Right corner of the Overlay with the

249

Top-Left corner of the node/viewport, and <code>[Y.WidgetPositionAlign.CC, Y.WidgetPositionAlign.TC]</code> aligns the Center of the

250

Overlay with the Top-Center edge of the node/viewport.

251

</p>

252

</dd>

253

</dl>

254

255

<pre class="code prettyprint">// Align the:

256

// top-left corner of the overlay, with the

257

// top-right corner of the node with id = "okBtn"

258

overlay.set("align", {

259

node:"#okBtn",

260

points:[Y.WidgetPositionAlign.TL, Y.WidgetPositionAlign.TR]

261

});

262

263

// Align the:

264

// right-center edge of the overlay, with the

265

// right-center edge of the viewport (no node specified)

266

overlay.set("align", {

267

points:[Y.WidgetPositionAlign.RC, Y.WidgetPositionAlign.RC]

268

});

269

270

// Align the:

271

// center of the overlay, with the

272

// top-left corner of the node with id = "okBtn"

273

overlay.align("#okBtn", [Y.WidgetPositionAlign.CC, Y.WidgetPositionAlign.TL]);</pre>

274

275

276

<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>

277

278

<pre class="code prettyprint">// Center the overlay in the node with id = "module"

279

overlay.set("centered", "#module");

280

281

// Center the overlay in the viewport

282

overlay.set("centered", true);</pre>

283

284

285

<p>The <a href="overlay-align.html">"Alignment Support"</a> example shows aligned positioning support in action.</p>

286

287

<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

288

provided in a future release.</p>

289

290

<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>

291

292

<pre class="code prettyprint">// Constrains the XY position to a given node:

293

overlay.set("constrain", "#constrainingNode");

294

295

// Or to the viewport

296

overlay.set("constrain", true);</pre>

297

298

299

<p>The <a href="overlay-constrain.html">"Constrain Support"</a> example shows constrained positioning in action.</p>

300

301

<h3 id="stacking">Stacking</h3>

302

303

<p>

304

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

305

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>

306

307

<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>

308

309

<pre class="code prettyprint">// Disable shim for all browsers, set zIndex to 10

310

var overlay = new Y.Overlay({

311

shim:false, // Disable for all browsers, including IE6

312

zIndex:10

313

});

314

315

// Set zIndex to 10. Shim is enabled for IE6 but disabled for all

316

// other browsers (default value)

317

var overlay = new Y.Overlay({

318

zIndex:10

319

});</pre>

320

321

322

<p>The <a href="overlay-stack.html">"Stack Support"</a> example creates a simple "bringToTop" implementation based on the <code>zIndex</code> attribute.

323

This support will be provided as part of Overlay itself (or more precisely, as part of <code>WidgetStack</code>) in a future release.</p>

324

325

<h3 id="content">Setting Section Content</h3>

326

327

<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>

328

329

<h4 id="replacing-content">Replacing Content</h4>

330

331

<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

332

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

333

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>

334

335

<pre class="code prettyprint">var overlay = new Y.Overlay({

336

headerContent: '<span class="title">My Header Content</span>',

337

bodyContent: '<div class="mod">My Body Content</div>'

338

// Don't want a footer

339

});

340

341

// or

342

343

overlay.set("headerContent", '<span class="title">My Header Content</span>');

344

345

// or

346

347

var headerContent = Y.Node.create("<span></span>");

348

headerContent.set("innerHTML", "My Header Content");

349

headerContent.addClass("title");

350

351

overlay.set("headerContent", headerContent);</pre>

352

353

354

<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,

355

the first time content is set for it.</p>

356

357

<p>As with any attribute change, you can listen for (and prevent) changes in content by listening for the corresponding attribute change event:</p>

358

359

<pre class="code prettyprint">overlay.on("bodyContentChange", function(e) {

360

if (someCondition) {

361

// Don't allow body content to be updated

362

e.preventDefault():

363

}

364

});

365

366

overlay.after("bodyContentChange", function(e) {

367

// body section has been modified

368

});</pre>

369

370

371

<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

372

event. It cannot be prevented to stop the content change from occurring:</p>

373

374

<pre class="code prettyprint">overlay.after("contentUpdate", function(e) {

375

// Content has been updated in one of the standard module sections.

376

});</pre>

377

378

379

<h4 id="insertingappending-content">Inserting/Appending Content</h4>

380

381

<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>

382

383

<pre class="code prettyprint">overlay.setStdModContent(

384

Y.WidgetStdMod.HEADER, // Section

385

"New Content To Insert", // Content

386

Y.WidgetStdMod.BEFORE // Where

387

);

388

389

overlay.setStdModContent(

390

Y.WidgetStdMod.FOOTER, // Section

391

"New Content To Append", // Content

392

Y.WidgetStdMod.AFTER // Where

393

);</pre>

394

395

396

<ul>

397

<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>

398

<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>

399

<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>

400

</ul>

401

402

<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>

403

404

<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>

405

406

<p>The <a href="overlay-stdmod.html">Standard Module</a> example provides a way to exercise the above content attributes and methods.</p>

407

408

<h3 id="markup">Markup Structure</h3>

409

410

<p>The final rendered Overlay has the markup structure shown below:</p>

411

412

413

414

415

416

<div class="yui3-widget-hd">Overlay Header Content</div>

417

418

<div class="yui3-widget-bd">Overlay Body Content</div>

419

420

<div class="yui3-widget-ft">Overlay Footer Content</div>

421

422

</div>

423

424

425

426

427

</div></pre>

428

429

430

<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>

431

432

<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

433

"yui3-widget-stdmod", "yui3-widget-positioned" and "yui3-widget-stacked" classes as shown above.</p>

434

435

<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>

436

437

438

439

<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>

440

441

<pre class="code prettyprint">.yui3-overlay {

442

position:absolute;

443

}

444

445

.yui3-overlay-hidden {

446

visibility:hidden

447

}</pre>

448

449

450

<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,

451

(along with the Gecko/Mac scroll bar support CSS mentioned above)</p>

452

453

<pre class="code prettyprint">.yui3-widget-stacked .yui3-widget-shim {

454

opacity: 0;

455

filter: alpha(opacity=0);

456

position: absolute;

457

border: none;

458

top: 0px;

459

left: 0px;

460

padding: 0;

461

margin: 0;

462

z-index: -1;

463

width: 100%;

464

height: 100%;

465

466

We'll be setting these programmatically for IE6,

467

to account for cases where height is not set

468

469

_width: 0;

470

_height: 0;

471

}</pre>

472

473

</div>

474

</div>

475

</div>

476

477

478

479

480

481

482

<h2 class="no-toc">Table of Contents</h2>

483

</div>

484

485

486

487

<li>

488

<a href="#getting-started">Getting Started</a>

489

</li>

490

<li>

491

<a href="#using">Using Overlay</a>

492

493

<li>

494

<a href="#instantiating">Instantiating The Overlay</a>

495

496

<li>

497

<a href="#instantiating-from-markup-progressive-enhancement">Instantiating From Markup: Progressive Enhancement</a>

498

</li>

499

<li>

500

<a href="#instantiating-from-script">Instantiating From Script</a>

501

</li>

502

</ul>

503

</li>

504

<li>

505

<a href="#attributes">Attributes</a>

506

</li>

507

<li>

508

<a href="#positioning">Positioning</a>

509

510

<li>

511

<a href="#basic-xy-positioning">Basic XY Positioning</a>

512

</li>

513

<li>

514

<a href="#extended-xy-positioning">Extended XY Positioning</a>

515

</li>

516

</ul>

517

</li>

518

<li>

519

<a href="#stacking">Stacking</a>

520

</li>

521

<li>

522

<a href="#content">Setting Section Content</a>

523

524

<li>

525

<a href="#replacing-content">Replacing Content</a>

526

</li>

527

<li>

528

<a href="#insertingappending-content">Inserting/Appending Content</a>

529

</li>

530

</ul>

531

</li>

532

<li>

533

<a href="#markup">Markup Structure</a>

534

</li>

535

<li>

536

537

</li>

538

</ul>

539

</li>

540

</ul>

541

</div>

542

</div>

543

544

545

546

547

548

<h2 class="no-toc">Examples</h2>

549

</div>

550

551

552

553

554

555

556

<a href="overlay-xy.html">Basic XY Positioning</a>

557

</li>

558

559

560

561

562

<a href="overlay-tooltip.html">Simple Tooltip</a>

563

</li>

564

565

566

567

568

<a href="overlay-align.html">Alignment Support</a>

569

</li>

570

571

572

573

574

<a href="overlay-stack.html">Stack Support</a>

575

</li>

576

577

578

579

580

<a href="overlay-stdmod.html">Standard Module Support</a>

581

</li>

582

583

584

585

586

<a href="overlay-constrain.html">Constrain Support</a>

587

</li>

588

589

590

591

592

<a href="overlay-io-plugin.html">IO Plugin</a>

593

</li>

594

595

596

597

598

<a href="overlay-anim-plugin.html">Animation Plugin</a>

599

</li>

600

601

602

603

604

605

606

</ul>

607

</div>

608

</div>

609

610

611

612

613

614

<h2 class="no-toc">Examples That Use This Component</h2>

615

</div>

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

<a href="../node-focusmanager/node-focusmanager-3.html">Accessible Menu Button</a>

639

</li>

640

641

642

643

644

<a href="../stylesheet/stylesheet-theme.html">Adjusting a Page Theme on the Fly</a>

645

</li>

646

647

648

</ul>

649

</div>

650

</div>

651

652

</div>

653

</div>

654

</div>

655

</div>

656

657

658

659

660

</body>

661

</html>

Older »