~bcsaller/juju-gui/charmFind

<p>This is an advanced example, in which we create a ListBox widget with nested Option widgets, by extending the base <code>Widget</code> class, and adding <code>WidgetParent</code> and <code>WidgetChild</code> extensions, through <code>Base.build</code>.</p>

<p>The <a href="../tabview">TabView</a> component that is included in the YUI 3 library, is also built using the WidgetParent and WidgetChild extensions.</p>

</div>

<p id="selected">Selected: <span id="selection">None</span></p>

100

YUI({

101

modules: {

102

"listbox": {

103

fullpath: "../assets/widget/listbox.js",

104

requires: ["substitute", "widget", "widget-parent", "widget-child", "node-focusmanager"]

105

}

106

}

107

}).use("listbox", function (Y) {

108

109

var listbox = new Y.ListBox({

110

id:"mylistbox",

111

width:"13em",

112

height:"15em",

113

children: [

114

{ label: "Item One" },

115

{ label: "Item Two" }

116

]

117

});

118

119

listbox.add({

120

type: "ListBox",

121

label: "Item Three",

122

children: [

123

{ label: "Item Three - One" },

124

{ label: "Item Three - Two" }

125

]

126

});

127

128

listbox.add({ label: "Item Four" });

129

130

listbox.add(

131

new Y.Option({ label: "Item Five" })

132

);

133

134

listbox.add({

135

type: "ListBox",

136

label: "Item Six",

137

children: [

138

{ label: "Item Six - One" },

139

{ label: "Item Six - Two" }

140

]

141

});

142

143

listbox.after("selectionChange", function(e) {

144

145

var selection = this.get("selection");

146

if (selection instanceof Y.ListBox) {

147

selection = selection.get("selection");

148

}

149

150

if (selection) {

151

Y.one("#selection").setContent(selection.get("label"));

152

}

153

});

154

155

listbox.render("#exampleContainer");

156

});

157

</script>

158

</div>

159

160

<h3>The WidgetParent and WidgetChild Extensions</h3>

161

162

<p><a href="http://yuilibrary.com/yui/docs/api/WidgetParent.html">WidgetParent</a> is an extension, designed to be used with <code>Base.build</code> to create a class of Widget which is designed to contain child Widgets (for example a Tree widget, which contains TreeNode children).

163

WidgetParent itself augments <a href="http://yuilibrary.com/yui/docs/api/ArrayList.html">ArrayList</a> providing a convenient set of array iteration and convenience methods, allowing users of your class to easily work with parent's list of children.</p>

164

165

<p><a href="http://yuilibrary.com/yui/docs/api/WidgetChild.html">WidgetChild</a> is also an extension, designed to be used with <code>Base.build</code> to create a class of Widget which is designed to nested inside parent Widgets (for example a TreeNode widget, which sits inside a Tree widget).</p>

166

167

<p>A Widget can be built with both the WidgetParent and WidgetChild extensions (it can be both a Parent and a Child), in cases where we want to support multi-level hierarchies, such as the ListBox example below.</p>

168

169

<p>In addition to providing the basic support to manage (add/remove/iterate/render) children the Widget Parent/Child implementations also provides support for both single and multiple selection models.</p>

170

171

<h3>Using WidgetParent and WidgetChild to Create the ListBox Class</h3>

172

173

<p>For ListBox, since we're creating a new class from scratch, we use the sugar version of <code>Base.build</code>, called <code>Base.create</code>, which allows us to easily create a new class and define it's prototype and static properties/methods, in a single call, as shown below:</p>

174

175

<pre class="code prettyprint">// Create a new class, ListBox, which extends Widget, and mixes in both the WidgetParent and WidgetChild

176

// extensions since we want to be able to nest one ListBox inside another, to create heirarchical listboxes

177

178

Y.ListBox = Y.Base.create("listbox", Y.Widget, [Y.WidgetParent, Y.WidgetChild], {

179

// Prototype Properties for ListBox

180

}, {

181

// Static Properties for ListBox

182

});</pre>

183

184

185

<p>We can then go ahead and fill out the prototype and static properties we want to override in our ListBox implementation, while Widget, WidgetParent and WidgetChild provide the basic Widget rendering and parent-child relationship support. Comments inline below provide the background:</p>

186

187

<h4>Prototype Method and Properties</h4>

188

189

<pre class="code prettyprint">Y.ListBox = Y.Base.create("listbox", Y.Widget, [Y.WidgetParent, Y.WidgetChild], {

190

191

// The default content box for ListBoxes will be a UL (Widget uses a DIV by default)

192

CONTENT_TEMPLATE : "<ul></ul>",

193

194

// Setup Custom Listeners

195

bindUI: function() {

196

197

if (this.isRoot()) {

198

199

// Setup custom focus handling, using the NodeFocusManager plugin

200

// This will help us easily crete next/previous item handling using the arrow keys

201

202

this.get("boundingBox").plug(Y.Plugin.NodeFocusManager, {

203

descendants: ".yui3-option",

204

keys: {

205

next: "down:40", // Down arrow

206

previous: "down:38" // Up arrow

207

208

circular: true

209

});

210

}

211

212

this.get("boundingBox").on("contextmenu", function (event) {

213

event.preventDefault();

214

});

215

216

// Setup listener to control keyboard based single/multiple item selection

217

this.on("option:keydown", function (event) {

218

219

var item = event.target,

220

domEvent = event.domEvent,

221

keyCode = domEvent.keyCode,

222

direction = (keyCode == 40);

223

224

if (this.get("multiple")) {

225

if (keyCode == 40 || keyCode == 38) {

226

if (domEvent.shiftKey) {

227

this._selectNextSibling(item, direction);

228

} else {

229

this.deselectAll();

230

this._selectNextSibling(item, direction);

231

}

232

}

233

} else {

234

if (keyCode == 13 || keyCode == 32) {

235

domEvent.preventDefault();

236

item.set("selected", 1);

237

}

238

}

239

});

240

241

// Setup listener to control mouse based single/multiple item selection

242

this.on("option:mousedown", function (event) {

243

244

var item = event.target,

245

domEvent = event.domEvent,

246

selection;

247

248

if (this.get("multiple")) {

249

if (domEvent.metaKey) {

250

item.set("selected", 1);

251

} else {

252

this.deselectAll();

253

item.set("selected", 1);

254

}

255

} else {

256

item.set("selected", 1);

257

}

258

259

});

260

261

262

// Helper Method, to find the correct next sibling, taking into account nested ListBoxes

263

_selectNextSibling : function(item, direction) {

264

265

var parent = item.get("parent"),

266

method = (direction) ? "next" : "previous",

267

268

// Only go circular for the root listbox

269

circular = (parent === this),

270

sibling = item[method](circular);

271

272

if (sibling) {

273

// If we found a sibling, it's either an Option or a ListBox

274

if (sibling instanceof Y.ListBox) {

275

// If it's a ListBox, select it's first child (in the direction we're headed)

276

sibling.selectChild((direction) ? 0 : sibling.size() - 1);

277

} else {

278

// If it's an Option, select it

279

sibling.set("selected", 1);

280

}

281

} else {

282

// If we didn't find a sibling, we're at the last leaf in a nested ListBox

283

parent[method](true).set("selected", 1);

284

}

285

286

287

// The markup template we use internally to render nested ListBox children

288

NESTED_TEMPLATE : '<li class="{nestedOptionClassName}"><em class="{labelClassName}">{label}</em></li>',

289

290

renderUI: function () {

291

292

// Handling Nested Child Element Rendering

293

if (this.get("depth") > -1) {

294

295

var tokens = {

296

labelClassName : this.getClassName("label"),

297

nestedOptionClassName : this.getClassName("option"),

298

label : this.get("label")

299

300

liHtml = Y.substitute(this.NESTED_TEMPLATE, tokens),

301

li = Y.Node.create(liHtml),

302

303

boundingBox = this.get("boundingBox"),

304

parent = boundingBox.get("parentNode");

305

306

li.appendChild(boundingBox);

307

parent.appendChild(li);

308

}

309

}

310

311

} { /* static properties */ });</pre>

312

313

314

<h4>Static Properties</h4>

315

316

<p>The only static property we're interested in defining for the ListBox class is the <code>ATTRS</code> property. Comments inline below provide the background:</p>

317

318

<pre class="code prettyprint">{

319

// Define any new attributes, or override existing ones

320

ATTRS : {

321

322

// We need to define the default child class to use,

323

// when we need to create children from the configuration

324

// object passed to add or to the "children" attribute (which is provided by WidgetParent)

325

326

// In this case, when a configuration object (e.g. { label:"My Option" }),

327

// is passed into the add method,or as the value of the "children"

328

// attribute, we want to create instances of Y.Option

329

defaultChildType: {

330

value: "Option"

331

332

333

// Setup Label Attribute

334

label : {

335

validator: Y.Lang.isString

336

}

337

}

338

}</pre>

339

340

341

<h3>Using WidgetChild to Create the Option (leaf) Class</h3>

342

343

<p>The Option class is pretty simple, and largely just needs the attribute and API provided by WidgetChild. We only need to over-ride the default templates and tabIndex handling:</p>

344

345

<pre class="code prettyprint">Y.Option = Y.Base.create("option", Y.Widget, [Y.WidgetChild], {

346

347

// Override the default DIVs used for rendering the bounding box and content box.

348

CONTENT_TEMPLATE : "<em></em>",

349

BOUNDING_TEMPLATE : "<li></li>",

350

351

// Handle rendering the label attribute

352

renderUI: function () {

353

this.get("contentBox").setContent(this.get("label"));

354

}

355

356

}, {

357

358

ATTRS : {

359

360

// Setup Label Attribute

361

label : {

362

validator: Y.Lang.isString

363

364

365

// Override the default tabIndex for an Option,

366

// since we want FocusManager to control keboard

367

// based focus

368

tabIndex: {

369

value: -1

370

}

371

}

372

373

});</pre>

374

375

376

<h3>Adding The Code As A "listbox" Custom Module</h3>

377

378

<p>This example also shows how you can package code for re-use as a module, by registering it through the <code>YUI.add</code> method, specifying any requirements it has (the packaged code is available in ./assets/listbox.js).</p>

379

380

<pre class="code prettyprint">YUI.add('listbox', function(Y) {

381

382

Y.ListBox = ...

383

384

Y.Option = ...

385

386

}, '3.1.0' ,{requires:['substitute', 'widget', 'widget-parent', 'widget-child', 'node-focusmanager']});</pre>

387

388

389

<h3>Using the Custom "listbox" Module</h3>

390

391

<p>To create an instance of a ListBox, we ask for the "listbox" module we packaged in the previous step, through <code>YUI().use("listbox")</code>:</p>

392

393

<pre class="code prettyprint">YUI({

394

modules: {

395

"listbox": {

396

fullpath: "listbox.js",

397

requires: ["substitute", "widget", "widget-parent", "widget-child", "node-focusmanager"]

398

}

399

}

400

}).use("listbox", function (Y) {

401

402

// Create the top level ListBox instance, and start it off with

403

// 2 children (the defaultChildType will be used to create instances of Y.Option with the

404

// children configuration passed in below).

405

406

var listbox = new Y.ListBox({

407

id:"mylistbox",

408

width:"13em",

409

height:"15em",

410

children: [

411

{ label: "Item One" },

412

{ label: "Item Two" }

413

]

414

});

415

416

...

417

});</pre>

418

419

420

<p>We can also use the <code>add</code> method provided by WidgetParent, to add children after contruction, and then render to the DOM:</p>

421

422

<pre class="code prettyprint">// Then we add a nested ListBox which itself has 2 children, using

423

// the add API provided by WidgetParent

424

425

listbox.add({

426

type: "ListBox",

427

label: "Item Three",

428

children: [

429

{ label: "Item Three - One" },

430

{ label: "Item Three - Two" }

431

]

432

});

433

434

// One more Option child

435

436

listbox.add({ label: "Item Four" });

437

438

// One more Option child, using providing an actual

439

// instance, as opposed to just the configuration

440

441

listbox.add(

442

new Y.Option({ label: "Item Five" })

443

);

444

445

// And finally, a last nested ListBox, again with

446

// 2 children

447

448

listbox.add({

449

type: "ListBox",

450

label: "Item Six",

451

children: [

452

{ label: "Item Six - One" },

453

{ label: "Item Six - Two" }

454

]

455

});

456

457

// Render it, using Widget's render method,

458

// to the "#exampleContainer" element.

459

listbox.render("#exampleContainer");</pre>

460

461

462

<p>The ListBox fires selectionChange events, every time it's selection state changes (provided by WidgetParent), which we can listen and respond to:</p>

463

464

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

465

466

var selection = this.get("selection");

467

if (selection instanceof Y.ListBox) {

468

selection = selection.get("selection");

469

}

470

471

if (selection) {

472

Y.one("#selection").setContent(selection.get("label"));

473

}

474

475

});</pre>

476

477

478

479

480

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

481

padding:0;

482

margin: .25em;

483

border: solid 1px #000;

484

background-color:#fff;

485

white-space:nowrap;

486

}

487

488

.yui3-listbox .yui3-listbox {

489

margin-top: .25em;

490

margin-bottom: .25em;

491

border: none;

492

}

493

494

.yui3-listbox .yui3-option,

495

.yui3-listbox .yui3-listbox-option {

496

margin:0;

497

padding:0;

498

cursor:default;

499

list-style-image:none;

500

list-style-position:outside;

501

list-style-type:none;

502

}

503

504

.yui3-option-content,

505

.yui3-listbox-label {

506

display: block;

507

padding: .25em .5em;

508

}

509

510

.yui3-listbox-content {

511

margin:0;

512

padding:0;

513

overflow:auto;

514

}

515

516

.yui3-listbox .yui3-listbox .yui3-option-content {

517

margin-left:.5em;

518

}

519

520

.yui3-listbox-label {

521

font-weight: bold;

522

}

523

524

.yui3-option-selected {

525

background-color: #cccccc;

526

}

527

528

.yui3-option-focused {

529

outline: none;

530

background-color: blue;

531

color: #fff;

532

}</pre>

533

534

535

<h2>Complete Example Source</h2>

536

<pre class="code prettyprint"><p id="selected">Selected: <span id="selection">None</span></p>

537

538

539

540

541

YUI({

542

modules: {

543

"listbox": {

544

fullpath: "../assets/widget/listbox.js",

545

requires: ["substitute", "widget", "widget-parent", "widget-child", "node-focusmanager"]

546

}

547

}

548

}).use("listbox", function (Y) {

549

550

var listbox = new Y.ListBox({

551

id:"mylistbox",

552

width:"13em",

553

height:"15em",

554

children: [

555

{ label: "Item One" },

556

{ label: "Item Two" }

557

]

558

});

559

560

listbox.add({

561

type: "ListBox",

562

label: "Item Three",

563

children: [

564

{ label: "Item Three - One" },

565

{ label: "Item Three - Two" }

566

]

567

});

568

569

listbox.add({ label: "Item Four" });

570

571

listbox.add(

572

new Y.Option({ label: "Item Five" })

573

);

574

575

listbox.add({

576

type: "ListBox",

577

label: "Item Six",

578

children: [

579

{ label: "Item Six - One" },

580

{ label: "Item Six - Two" }

581

]

582

});

583

584

listbox.after("selectionChange", function(e) {

585

586

var selection = this.get("selection");

587

if (selection instanceof Y.ListBox) {

588

selection = selection.get("selection");

589

}

590

591

if (selection) {

592

Y.one("#selection").setContent(selection.get("label"));

593

}

594

});

595

596

listbox.render("#exampleContainer");

597

});

598

</script></pre>

599

600

</div>

601

</div>

602

</div>

603

604

605

606

607

608

609

610

611

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

612

</div>

613

614

615

616

617

618

619

<a href="widget-extend.html">Extending the Base Widget Class</a>

620

</li>

621

622

623

624

625

<a href="widget-build.html">Creating Custom Widget Classes With Extensions</a>

626

</li>

627

628

629

630

631

<a href="widget-plugin.html">Creating a Widget Plugin</a>

632

</li>

633

634

635

636

637

<a href="widget-tooltip.html">Creating a Simple Tooltip Widget With Extensions</a>

638

</li>

639

640

641

642

643

<a href="widget-parentchild-listbox.html">Creating a Hierarchical ListBox Widget</a>

644

</li>

645

646

647

</ul>

648

</div>

649

</div>

650

651

652

653

</div>

654

</div>

655

</div>

656

</div>

657

658

659

660

661

</body>

662

</html>

Older »