~smagoun/whoopsie/whoopsie-lp1017637

The <code>YUI</code> module is the core of YUI 3. It must be included on all pages that use YUI, and it's the only dependency required to start writing YUI code. The YUI module contains loader functionality and a dependency calculator, allowing it to serve as a "seed" that can load other dependencies as needed.

</p>

</div>

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

<p>

The first step in using YUI is to load the YUI "seed". The seed is the bare minimum core code that's needed to allow YUI to dynamically load additional dependencies on demand. YUI is extremely modular, and the small seed file makes it easy to load only the modules you want to use on a given page.

</p>

<p>

Include the YUI seed file by adding this script tag to your HTML:

</p>

<p>

The seed file adds a single global variable to the page: the <code>YUI</code> object. To begin using YUI, you'll first create a new YUI instance and then tell that instance which YUI modules you want to use.

</p>

<pre class="code prettyprint"><div id="demo">Click me</div>

// Create a new YUI sandbox and load the "node" module.

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

// YUI will call this function and pass in the YUI instance (Y) once all

// modules have finished loading and are ready to use.

// We can now use Y.Node to get references to DOM elements using CSS

// selectors.

var demo = Y.one('#demo');

// And we can listen for DOM events.

demo.on('click', function (e) {

demo.set('text', 'You clicked me!');

});

</script></pre>

<p>

Calling <code>YUI()</code> creates a brand new YUI instance without any active modules. We then call <code>.use()</code> on that new instance and pass in a list of modules we want to use, in the form of string parameters. You can name as many modules as you like here. Finally, we pass a callback function that will be executed once all those modules have finished loading. The callback function receives the YUI instance as an argument, which we've named <code>Y</code>.

</p>

<p>

This pattern is called a "sandbox", and it's the most important concept to understand about YUI. It not only makes it easy to load dependencies on demand, it also ensures that your code (and YUI's code!) doesn't pollute the global scope of the page or interfere with other global JavaScript you may be using.

</p>

<p>

This also means that you can have multiple YUI sandboxes on the same page, and they won't interfere with each other (but they <em>will</em> avoid reloading module code that has already been loaded).

</p>

<h2 id="alternative-seed-files">Alternative Seed Files</h2>

<p>

In <a href="#getting-started">Getting Started</a>, we described the most common way to load YUI using what we call the "Loader Seed". This is a seed file that contains both the core of YUI and the code for the YUI Loader and all the metadata that's necessary to dynamically load additional YUI modules. Depending on your needs, you may want to use a different seed file to further optimize how you load YUI.

</p>

<p>

The base seed contains the YUI core and the <a href="../get/index.html">Get Utility</a>, but doesn't include Loader or any module metadata. The first time you call <code>YUI().use()</code>, it will automatically fetch Loader and the module metadata, and then will make a second request to fetch any additional modules you've asked for.

</p>

<p>

This results in a smaller initial seed file that can speed up the initial page load, but requires more requests overall to get an actual YUI instance up and running. Prior to version 3.4.0, this was the default YUI seed file.

</p>

100

101

102

<p>

103

The core seed contains only the YUI core, and isn't capable of dynamically loading other modules. This is the smallest of all the seed files, but requires you to manually load any dependencies you need before using them.

104

</p>

105

106

<h2 id="loading-modules">Loading Modules</h2>

107

108

<h3 id="dynamic-loading-with-use">Dynamic Loading with <code>use()</code></h3>

109

110

<p>

111

The <code>use()</code> method allows you to specify the modules that you want to load into your YUI instance.

112

</p>

113

114

<pre class="code prettyprint">YUI().use('node', 'event', function (Y) {

115

// The node and event modules are available on this YUI instance.

116

});</pre>

117

118

119

<p>

120

YUI modules aren't actually executed until they're used and attached to a YUI instance, and two different YUI instances can have two different sets of modules attached to them. Even if both instances use the same module, each instance gets its own "copy" of that module and isn't affected by changes made in another instance.

121

</p>

122

123

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

124

// We can blow away the Y.Node module in this outer YUI instance...

125

Y.Node = null;

126

127

YUI().use('node', function (Y2) {

128

// ...without affecting it inside another YUI instance...

129

console.log(typeof Y2.Node); // => "function"

130

});

131

});</pre>

132

133

134

<p>

135

You can also call <code>use()</code> on an existing YUI instance to attach more modules to that instance without needing to create a completely new YUI instance. This is useful for lazy-loading modules that aren't needed up front.

136

</p>

137

138

<pre class="code prettyprint">// First we create a YUI instance and use the node module.

139

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

140

// The calendar module is available here.

141

142

// Later, we decide we want to use the autocomplete module, so we attach it

143

// to the same instance.

144

Y.use('autocomplete', function () {

145

// The autocomplete module is available here, and the calendar module is

146

// still available as well since this is the same YUI instance.

147

});

148

});</pre>

149

150

151

<h3 id="understanding-yuiuse">Understanding <code>YUI().use()</code></h3>

152

153

<p>

154

The <code>YUI().use()</code> call might seem like magic, but it's actually doing something very simple. It's easier to understand what's going on if we break it into multiple steps.

155

</p>

156

157

<p>

158

First, calling <code>YUI()</code> creates a brand new YUI instance. This instance will later be passed on to our callback function as the <code>Y</code> argument, but if we wanted to, we could just stop here and start using it immediately without even calling <code>use()</code>.

159

</p>

160

161

<p>

162

Next, we call <code>use()</code> on the new YUI instance that was just created. We pass in a list of the modules we want to use, followed by a function that we want YUI to call once all those modules are available.

163

</p>

164

165

<p>

166

Finally, YUI loads any necessary modules, attaches them to the YUI instance (this is when the modules are actually executed), and then calls our callback function. The YUI instance passes itself to the callback function as an argument for convenience, so that we don't have to store the instance in a global variable.

167

</p>

168

169

<p>

170

The callback function passed to <code>use()</code> is executed asynchronously, which means that it doesn't block subsequent code while modules are being loaded.

171

</p>

172

173

<p>

174

Broken out into more verbose code, these three steps look like this:

175

</p>

176

177

<pre class="code prettyprint">// Step one: create a new YUI instance.

178

var Y = YUI();

179

180

// Step two: load and attach some modules in that instance. Note that we

181

// call Y.use() here and not YUI().use().

182

Y.use('node', 'event', function (Y) {

183

// Step three: do stuff with node and event.

184

185

// The Y object that gets passed to this function is exactly the same as the

186

// global Y object created in step one, so it's really only necessary when

187

// you don't store the YUI instance in a global variable.

188

});</pre>

189

190

191

<p>

192

Except for creating a global <code>Y</code> variable, that code does exactly the same thing

193

as this code:

194

</p>

195

196

<pre class="code prettyprint">YUI().use('node', 'event', function (Y) {

197

// Do stuff with node and event.

198

});</pre>

199

200

201

<p>

202

If you wanted to, you could create a global <code>Y</code> variable using the shorter style as well:

203

</p>

204

205

<pre class="code prettyprint">var Y = YUI().use('node', 'event', function (Y) {

206

// Do stuff with node and event.

207

});</pre>

208

209

210

<h3 id="module-states">Module States</h3>

211

212

<p>

213

Within any given YUI instance, there are three possible states for a module:

214

</p>

215

216

<ol>

217

<li><p><strong>Not loaded</strong>: The module code has not been downloaded yet and is not available to any YUI instance.</p></li>

218

219

<li><p><strong>Loaded</strong>: The module code has been downloaded, but has not been attached to this specific YUI instance. Other instances may be using it, but this instance isn't using it yet.</p></li>

220

221

<li><p><strong>Attached</strong>: The module code has been downloaded and is attached to this YUI instance. The module is ready to use.</p></li>

222

</ol>

223

224

<pre class="code prettyprint">/*

225

Since we haven't created an instance yet, all YUI modules are

226

in the 'Not loaded' state until they are requested.

227

228

229

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

230

//Now calender and all if it's dependencies are 'Loaded' and 'Attached' on this instance

231

});

232

233

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

234

//Now node and all of it's dependencies are 'Loaded' and 'Attached' on this instance

235

//Calender and it's un-used dependencies are in the 'Loaded' state on this instance

236

});</pre>

237

238

239

<h3 id="static-loading">Static Loading</h3>

240

241

<p>

242

To reach the "loaded" state, a module's JavaScript just needs to be included on the page after the YUI seed file. The <code>use()</code> method will do this for you automatically if necessary, but you could also load a module manually if you wanted to. We call this static loading (since it's the opposite of dynamic loading).

243

</p>

244

245

246

247

248

YUI().use('node-base', function (Y) {

249

// Since the node-base module has already been loaded statically, YUI

250

// doesn't need to download it again and can just execute and attach the

251

// module code here.

252

});

253

</script></pre>

254

255

256

<p>

257

If you want to take full manual control of your dependencies, you can statically load any modules you want to use and then pass <code>'*'</code> to <code>use()</code> instead of specifying a list of module names. This tells YUI to attach all loaded modules to your YUI instance without requiring you to name each module you want to attach.

258

</p>

259

260

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

261

// Any modules that were already loaded on the page statically will now be

262

// attached and ready to use. YUI will not automatically load any modules

263

// that weren't already on the page.

264

});</pre>

265

266

267

268

269

270

<h2 id="config">Configuring YUI</h2>

271

272

<p>

273

There are four primary ways to configure YUI and each has its own unique benefits. The YUI object is configured via properties on a simple JavaScript object.

274

</p>

275

276

<pre class="code prettyprint">{

277

debug: true,

278

combine: true,

279

comboBase: 'http://mydomain.com/combo?',

280

root: 'yui3/'

281

}</pre>

282

283

284

<p>

285

A complete list of configuration options is

286

<a href="http://yuilibrary.com/yui/docs/api/classes/config.html">available in the API Docs</a>.

287

</p>

288

289

<h3 id="instance-config">Instance Config</h3>

290

291

<p>

292

The most common way to specify config options for YUI is to pass them into the <code>YUI()</code> constructor when creating a new instance:

293

</p>

294

295

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

296

debug: true,

297

combine: true,

298

comboBase: 'http://mydomain.com/combo?',

299

root: 'yui3/'

300

}).use('node', function (Y) {

301

// ...

302

});</pre>

303

304

305

<p>

306

These config options will only apply to this specific instance of YUI.

307

</p>

308

309

<h3 id="yui_config">YUI_config</h3>

310

311

<p>

312

By setting options on the global variable <code>YUI_config</code>, you can configure every YUI

313

instance on the page even <em>before</em> YUI is loaded.

314

</p>

315

316

<pre class="code prettyprint">YUI_config = {

317

debug: true,

318

combine: true,

319

comboBase: 'http://mydomain.com/combo?',

320

root: 'yui3/'

321

};</pre>

322

323

324

<h3 id="yuiglobalconfig">YUI.GlobalConfig</h3>

325

326

<p>

327

By setting options on the <code>YUI.GlobalConfig</code> object, you can configure every YUI

328

instance on the page <em>after</em> YUI is loaded.

329

</p>

330

331

<pre class="code prettyprint">YUI.GlobalConfig = {

332

debug: true,

333

combine: true,

334

comboBase: 'http://mydomain.com/combo?',

335

root: 'yui3/'

336

};</pre>

337

338

339

<h3 id="yuiapplyconfig">YUI.applyConfig</h3>

340

341

<p>

342

The global <code>YUI.applyConfig()</code> method allows you to configure every YUI instance on the page, but it <em>merges</em> configs passed to it into each instance's existing config. This can be useful if your module is loaded onto the page in a <em>mashup</em>. The other configuration options do not merge, they are simply an object.

343

</p>

344

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

345

debug: true,

346

combine: true

347

});

348

YUI.applyConfig({

349

comboBase: 'http://mydomain.com/combo?',

350

root: 'yui3/'

351

});</pre>

352

353

354

<h2 id="yuiadd">Creating Custom Modules with <code>YUI.add()</code></h2>

355

356

<p>

357

<code>YUI.add()</code> is a static method that registers a reusable module—essentially, it adds a module to the set of modules available to be attached to a YUI instance via the <code>use()</code> method.

358

</p>

359

360

<p>

361

Defining a reusable YUI module is as simple as providing a name and a callback function to <code>YUI.add()</code>.

362

</p>

363

364

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

365

// Write your module code here, and make your module available on the Y

366

// object if desired.

367

Y.MyModule = {

368

sayHello: function () {

369

console.log('Hello!');

370

}

371

};

372

});</pre>

373

374

375

<p>

376

Note that there are no parentheses after <code>YUI</code> when calling <code>YUI.add()</code> as there are when calling <code>YUI().use()</code>. This is because <code>add()</code> is a static method of the global <code>YUI</code> object, not a method on a specific YUI instance. Modules are registered globally via <code>add()</code> and are later attached to a specific YUI instance via <code>use()</code>.

377

</p>

378

379

<p>

380

The <code>add()</code> method accepts two optional arguments after the callback function: a module version string and a config object. The most useful option in the config object is <code>requires</code>, which allows you to specify an array of other YUI modules that your module requires. YUI will then be sure to load these dependencies before executing your module.

381

</p>

382

383

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

384

// ...

385

}, '0.0.1', {

386

requires: ['node', 'event']

387

});</pre>

388

389

390

<p>

391

After your module has been added via <code>YUI.add()</code>, you can specify its name in a <code>use()</code> call to attach it to a YUI instance.

392

</p>

393

394

<pre class="code prettyprint">YUI().use('my-module', function (Y) {

395

// The Y instance here is the same Y instance that was passed into

396

// my-module's add() callback, so the Y.MyModule object that was created

397

// there is now available here as well.

398

Y.MyModule.sayHello();

399

});</pre>

400

401

402

<p>

403

A module's <code>add()</code> callback isn't executed until that module is attached to a YUI instance via <code>use()</code>. Each time a module is attached via <code>use()</code>, the module's <code>add()</code> callback will be executed, and will receive as an argument the same YUI instance that will later be passed to the <code>use()</code> callback.

404

</p>

405

406

407

<p>For more information on creating your custom modules, see our <a href="create.html">Creating YUI Modules</a> example.</p>

408

409

<h2 id="nodejs">Using YUI on Node.js</h2>

410

411

<p>As of version 3.5.0, YUI runs natively on <a href="http://nodejs.org/">Node.js</a> and comes with an official <a href="http://search.npmjs.org/#/yui">npm package</a> for easy installation. More information on using YUI on Node.js can be found in the <a href="nodejs.html">YUI on Node.js guide</a>.</p>

412

413

<h2 id="loader">Loader</h2>

414

<p><a href="loader.html">Loader</a>'s functionality is now built into the YUI Global Object

415

(as long as it's on the page) and puts its power behind the

416

<code>YUI().use</code> method.</p>

417

<p>If you request a module that is not loaded on the page

418

(or a dependency that is not loaded), loader will fetch a copy

419

of that module (and its dependencies) and attach them to your

420

YUI instance.</p>

421

422

<p>You can find <a href="loader.html">more information about Loader here</a>.</p>

423

424

<h3 id="async">New Async Loading in 3.5.0</h3>

425

426

<p>In <code>3.5.0</code>, we introduced asnychronous loading in Loader by default. This means that any script

427

<code>Loader</code> injects into the page will be loaded asnychronously. This will decrease load time and

428

improve performance by allowing the browser to fetch as many scripts at once as it can.

429

</p>

430

431

<p>If your custom modules are properly wrapped in a <code>YUI.add</code> callback, you will see no difference at all.

432

However, if you are loading custom modules that require ordered script loading

433

(depends on another dynamic, unwrapped module), you will need to change your module config to tell

434

<code>Loader</code> to <strong>not</strong> load these modules with the <code>async</code> flag. You can do this by adding

435

an <code>async: false</code> config to it's module definition and <code>Y.Get.script</code> will not load it asynchronously.

436

</p>

437

438

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

439

modules: {

440

one: {

441

aync: false,

442

fullpath: './one.js'

443

444

two: {

445

async: false,

446

fullpath: './two.js',

447

requires: [ 'one' ]

448

}

449

}

450

}).use('two'), function(Y) {

451

//Module one &amp; two are loaded now.

452

});</pre>

453

454

455

456

<p><code>Y.Lang</code> contains JavaScript language utilities and extensions that are used in the YUI library.

457

458

<p>Find more <a href="lang.html">information on <code>Y.Lang</code> here</a>.</p>

459

460

<h2 id="modulelist">Complete Module List</h2>

461

462

<p>

463

YUI provides more than 250 unique modules to use in your applications. <a href="modules.html">You can view a full list of modules here.</a>

464

</p>

465

</div>

466

</div>

467

</div>

468

469

470

471

472

473

474

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

475

</div>

476

477

478

479

<li>

480

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

481

</li>

482

<li>

483

<a href="#alternative-seed-files">Alternative Seed Files</a>

484

485

<li>

486

487

</li>

488

<li>

489

490

</li>

491

</ul>

492

</li>

493

<li>

494

<a href="#loading-modules">Loading Modules</a>

495

496

<li>

497

<a href="#dynamic-loading-with-use">Dynamic Loading with <code>use()</code></a>

498

</li>

499

<li>

500

<a href="#understanding-yuiuse">Understanding <code>YUI().use()</code></a>

501

</li>

502

<li>

503

<a href="#module-states">Module States</a>

504

</li>

505

<li>

506

<a href="#static-loading">Static Loading</a>

507

</li>

508

</ul>

509

</li>

510

<li>

511

<a href="#config">Configuring YUI</a>

512

513

<li>

514

<a href="#instance-config">Instance Config</a>

515

</li>

516

<li>

517

<a href="#yui_config">YUI_config</a>

518

</li>

519

<li>

520

<a href="#yuiglobalconfig">YUI.GlobalConfig</a>

521

</li>

522

<li>

523

<a href="#yuiapplyconfig">YUI.applyConfig</a>

524

</li>

525

</ul>

526

</li>

527

<li>

528

<a href="#yuiadd">Creating Custom Modules with <code>YUI.add()</code></a>

529

</li>

530

<li>

531

<a href="#nodejs">Using YUI on Node.js</a>

532

</li>

533

<li>

534

<a href="#loader">Loader</a>

535

536

<li>

537

<a href="#async">New Async Loading in 3.5.0</a>

538

</li>

539

</ul>

540

</li>

541

<li>

542

543

</li>

544

<li>

545

<a href="#modulelist">Complete Module List</a>

546

</li>

547

</ul>

548

</div>

549

</div>

550

551

552

553

554

555

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

556

</div>

557

558

559

560

561

562

563

564

</li>

565

566

567

568

569

<a href="yui-multi.html">Multiple Instances</a>

570

</li>

571

572

573

574

575

<a href="yui-loader-ext.html">YUI Loader - Dynamically Adding YUI and External Modules</a>

576

</li>

577

578

579

580

581

<a href="yui-extend.html">Create Class Hierarchies with `extend`</a>

582

</li>

583

584

585

586

587

<a href="yui-augment.html">Compose Classes of Objects with `augment`</a>

588

</li>

589

590

591

592

593

<a href="yui-mix.html">Add Behaviors to Objects with `mix`</a>

594

</li>

595

596

597

598

599

<a href="yui-merge.html">Combine Data Sets with `merge`</a>

600

</li>

601

602

603

604

605

<a href="yui-isa.html">Check Data Types with `Lang`</a>

606

</li>

607

608

609

610

611

<a href="yui-ua.html">Browser Detection with `UA`</a>

612

</li>

613

614

615

616

617

<a href="yui-yui2.html">Working with YUI 2 in 3</a>

618

</li>

619

620

621

622

623

<a href="yui-gallery.html">Natively use YUI Gallery Modules</a>

624

</li>

625

626

627

628

629

<a href="loader-resolve.html">Programatically use Loader</a>

630

</li>

631

632

633

634

635

<a href="parallel.html">Using Y.Parallel</a>

636

</li>

637

638

639

</ul>

640

</div>

641

</div>

642

643

644

645

</div>

646

</div>

647

</div>

648

</div>

649

650

651

652

653

</body>

654

</html>

Older »