~smagoun/whoopsie/whoopsie-lp1017637

<p>This example provides an introduction to the Attribute utility, showing how you can use it to add attribute support to your own custom classes.</p>

<p>

It is geared towards users who want to create their own classes from scratch and add Attribute support. In most cases you should consider extending the <a href="../base/index.html"><code>Base</code></a> class when you need managed attribute support,

instead of augmenting Attribute directly, especially if you expect your class to be extended. <a href="../base/index.html"><code>Base</code></a> does the work described in this example for you, in addition to making it easier for users to extend you class.

</p>

</div>

<button type="button" class="do">Create First Instance</button> Construct o1, with default attribute values

</div>

<button type="button" class="do">Update First Instance</button> Update the first instance, using set

</div>

<button type="button" class="do">Create Second Instance</button> Create the second instance, passing initial values to the constructor

</div>

// Get a new instance of YUI and

// load it with the required set of modules

YUI().use("node", "attribute", function(Y) {

// Setup custom class which we want to

// add managed attribute support to

function MyClass(cfg) {

// When constructed, setup the initial attributes for the instance, by calling the addAttrs method.

var attrs = {

// Add 3 attributes, foo, bar and foobar

"foo" : {

value:5

"bar" : {

value:"Hello World!"

"foobar" : {

value:true

}

};

this.addAttrs(attrs, cfg);

}

100

// Augment custom class with Attribute

101

Y.augment(MyClass, Y.Attribute);

102

103

function displayValues(o, title, node) {

104

var str =

105

'<div class="myclass"><div class="myclass-title">'

106

+ title +

107

'</div><ul class="myclass-attrs"><li>foo: '

108

+ o.get("foo")

109

+ '</li><li>bar: '

110

+ o.get("bar")

111

+ '</li><li>foobar: '

112

+ o.get("foobar")

113

+ '</li></ul></div>';

114

115

Y.one(node).set("innerHTML", str);

116

}

117

118

Y.on("click", function() {

119

120

// Create a new instance, but don't provide any initial attribute values.

121

var o1 = new MyClass();

122

123

// Display current values

124

displayValues(o1, "o1 with default values, set during construction", "#createo1 .example-out");

125

126

Y.on("click", function() {

127

128

// Update values, using the "set" method

129

o1.set("foo", 10);

130

o1.set("bar", "Hello New World!");

131

o1.set("foobar", false);

132

133

displayValues(o1, "o1 values updated using set, after construction", "#updateo1 .example-out");

134

135

}, "#updateo1 .do");

136

137

}, "#createo1 .do");

138

139

Y.on("click", function() {

140

141

var o2 = new MyClass({

142

foo: 7,

143

bar: "Aloha World!",

144

foobar: false

145

});

146

147

displayValues(o2, "o2 values set during construction", "#createo2 .example-out");

148

149

}, "#createo2 .do");

150

});

151

</script>

152

153

</div>

154

155

<h2>Setting Up Your Own Class To Use Attribute</h2>

156

157

<p>In this example, we'll show how you can use the Attribute utility to add managed attributes to your own object classes. Later examples will show how you can configure more advanced attribute properties, and work with attribute change events.</p>

158

159

<h3>Creating A YUI Instance</h3>

160

161

<p>Before we get into attribute, a quick note on how we set up the instance of YUI we'll use for the examples. For all of the attribute examples, we'll setup our own instance of the YUI object and download the files we require on demand using the code pattern shown below:</p>

162

163

164

165

// Create our local YUI instance, to avoid

166

// modifying the global YUI object

167

168

YUI({...}).use("attribute", "node", function(Y) {

169

170

// Example code is written inside this function,

171

// which gets passed our own YUI instance, Y, loaded

172

// with the modules we asked for - "attribute" and "node"

173

174

});

175

</script></pre>

176

177

178

<p>The call to <code>YUI()</code> will create and return a new instance of the global YUI object for us to use. However this instance does not yet have all the modules we need for the examples.</p>

179

180

<p>To load the modules, we invoke <code>use()</code> and pass it the list of modules we'd like populated on our new YUI instance - in this case, <code>attribute</code> and <code>node</code>.

181

182

The YUI instance will pull down the source files for modules if they don't already exist on the page, plus any or their dependencies.

183

When the source files are done downloading, the callback function which we pass in as the 3rd argument to <code>use()</code>, is invoked. Our custom YUI instance, <code>Y</code>, is passed to the callback, populated with the classes which make up the requested modules.</p>

184

185

<p>This callback function is where we'll write all our example code. By working inside the callback function, we don't pollute the global namespace and we're also able to download the files we need on demand, rather than have them be on the page up front.</p>

186

187

<p>The configuration object passed to <code>YUI()</code> when creating the instance is used to specify how (<em>combined, separate, debug, min etc.</em>) we want the files downloaded, and from where. The API documentation for the <a href="http://yuilibrary.com/yui/docs/api/YUI.html">YUI object</a>, provides more information about the configuration options available.</p>

188

189

<h3>Defining Your Custom Class</h3>

190

191

<p>The first step in the example is to create the constructor function for our new class, to which we want to add attribute support. In our example, this class is called <code>MyClass</code>.

192

193

We then augment <code>MyClass</code> with <code>Y.Attribute</code>, so that it receives all of <code>Attribute's</code> methods:</p>

194

195

<pre class="code prettyprint">function MyClass(cfg) {

196

...

197

}

198

199

Y.augment(MyClass, Y.Attribute);</pre>

200

201

202

<h3>Adding Attributes</h3>

203

204

<p>We can now set up any attributes we need for <code>MyClass</code> using the <code>addAttrs</code> method. For the basic example we add 3 attributes - <code>foo</code>,<code>bar</code>, and <code>foobar</code>, and provide an initial <code>value</code> for each.

205

206

The same object literal we use to provide the initial value for the attribute will also be used in the other examples to configure attribute properties such as <code>readOnly</code> or <code>writeOnce</code>, and define <code>getter</code>, <code>setter</code> and <code>validator</code> methods for the attribute.</p>

207

208

<p>In this example, the default set of attributes which <code>MyClass</code> will support gets passed to <code>addAttrs</code> to set up the attributes for each instance during construction.</p>

209

210

The complete definition for <code>MyClass</code> is shown below:</p>

211

212

<pre class="code prettyprint">// Setup custom class which we want to add managed attribute support to

213

function MyClass(cfg) {

214

215

// When constructed, setup the initial attributes for the

216

// instance, by calling the addAttrs method.

217

var attrs = {

218

// Add 3 attributes, foo, bar and foobar

219

"foo" : {

220

value:5

221

222

223

"bar" : {

224

value:"Hello World!"

225

226

227

"foobar" : {

228

value:true

229

}

230

};

231

232

this.addAttrs(attrs, cfg);

233

}

234

235

// Augment custom class with Attribute

236

Y.augment(MyClass, Y.Attribute);</pre>

237

238

239

<p>The <code>addAttrs</code> method, in addition to the default attribute configuration, also accepts an object literal (associative array) of name/value pairs which can be used to over-ride the default initial values of the attributes. This is useful for classes which wish to allow the user to set the value of attributes as part of object construction, as shown by the use of the <code>cfg</code> argument above.</p>

240

241

<p>

242

As mentioned previously, if you expect your class to be extended, <a href="../base/index.html">Base</a> provides a more convenient way for you to define the same attribute configuration statically for your class, so that it can be easily modified by extended classes. Base will take care of isolating the static configuration, so that it isn't modified across instances.

243

</p>

244

245

<h3>Using Attributes</h3>

246

247

<p>Now that we have <code>MyClass</code> defined with a set of attributes it supports, users can get and set attribute values on instances of <code>MyClass</code>:</p>

248

249

<p>We construct the first instance, <code>o1</code>, without setting any initial attribute values in the constructor, but use Attribute's <code>set()</code> method to set values after construction:</p>

250

251

<pre class="code prettyprint">// Create a new instance, but don't provide any initial attribute values.

252

var o1 = new MyClass();

253

254

// Display current values

255

displayValues(o1, "o1 with default values, set during construction",

256

"#createo1 .example-out");

257

258

...

259

260

// Update values, using the "set" method

261

o1.set("foo", 10);

262

o1.set("bar", "Hello New World!");

263

o1.set("foobar", false);

264

265

displayValues(o1, "o1 values updated using set, after construction",

266

"#updateo1 .example-out");</pre>

267

268

269

<p>For the second instance that, <code>o2</code> we set the initial values of the attributes, using the constructor configuration argument:</p>

270

271

<pre class="code prettyprint">var o2 = new MyClass({

272

foo: 7,

273

bar: "Aloha World!",

274

foobar: false

275

});</pre>

276

277

278

<p>The <code>displayValues()</code> method uses Attribute's <code>get()</code> method to retrieve the current values of the attributes, to display:</p>

279

280

<pre class="code prettyprint">function displayValues(o, title, node) {

281

var str =

282

'<div class="myclass"><div class="myclass-title">'

283

+ title +

284

':</div><ul class="myclass-attrs"><li>foo:'

285

+ o.get("foo")

286

+ '</li><li>bar:'

287

+ o.get("bar")

288

+ '</li><li>foobar:'

289

+ o.get("foobar")

290

+ '</li></ul></div>';

291

292

// Use the Y.one() method to get the first element which

293

// matches the selector passed in, to output the string to...

294

Y.one(node).set("innerHTML", str);

295

}</pre>

296

297

298

<h2>Complete Example Source</h2>

299

300

301

<button type="button" class="do">Create First Instance</button> Construct o1, with default attribute values

302

303

</div>

304

305

<button type="button" class="do">Update First Instance</button> Update the first instance, using set

306

307

</div>

308

309

<button type="button" class="do">Create Second Instance</button> Create the second instance, passing initial values to the constructor

310

311

</div>

312

313

314

315

// Get a new instance of YUI and

316

// load it with the required set of modules

317

318

YUI().use("node", "attribute", function(Y) {

319

320

// Setup custom class which we want to

321

// add managed attribute support to

322

323

function MyClass(cfg) {

324

325

// When constructed, setup the initial attributes for the instance, by calling the addAttrs method.

326

var attrs = {

327

// Add 3 attributes, foo, bar and foobar

328

"foo" : {

329

value:5

330

331

332

"bar" : {

333

value:"Hello World!"

334

335

336

"foobar" : {

337

value:true

338

}

339

};

340

341

this.addAttrs(attrs, cfg);

342

}

343

344

// Augment custom class with Attribute

345

Y.augment(MyClass, Y.Attribute);

346

347

function displayValues(o, title, node) {

348

var str =

349

'<div class="myclass"><div class="myclass-title">'

350

+ title +

351

'</div><ul class="myclass-attrs"><li>foo: '

352

+ o.get("foo")

353

+ '</li><li>bar: '

354

+ o.get("bar")

355

+ '</li><li>foobar: '

356

+ o.get("foobar")

357

+ '</li></ul></div>';

358

359

Y.one(node).set("innerHTML", str);

360

}

361

362

Y.on("click", function() {

363

364

// Create a new instance, but don't provide any initial attribute values.

365

var o1 = new MyClass();

366

367

// Display current values

368

displayValues(o1, "o1 with default values, set during construction", "#createo1 .example-out");

369

370

Y.on("click", function() {

371

372

// Update values, using the "set" method

373

o1.set("foo", 10);

374

o1.set("bar", "Hello New World!");

375

o1.set("foobar", false);

376

377

displayValues(o1, "o1 values updated using set, after construction", "#updateo1 .example-out");

378

379

}, "#updateo1 .do");

380

381

}, "#createo1 .do");

382

383

Y.on("click", function() {

384

385

var o2 = new MyClass({

386

foo: 7,

387

bar: "Aloha World!",

388

foobar: false

389

});

390

391

displayValues(o2, "o2 values set during construction", "#createo2 .example-out");

392

393

}, "#createo2 .do");

394

});

395

</script></pre>

396

397

</div>

398

</div>

399

</div>

400

401

402

403

404

405

406

407

408

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

409

</div>

410

411

412

413

414

415

416

<a href="attribute-basic.html">Basic Attribute Configuration</a>

417

</li>

418

419

420

421

422

<a href="attribute-rw.html">Read-Only and Write-Once Attributes</a>

423

</li>

424

425

426

427

428

<a href="attribute-event.html">Attribute Change Events</a>

429

</li>

430

431

432

433

434

<a href="attribute-basic-speeddate.html">Attribute Based Speed Dating</a>

435

</li>

436

437

438

439

440

<a href="attribute-event-speeddate.html">Attribute Event Based Speed Dating</a>

441

</li>

442

443

444

445

446

<a href="attribute-getset.html">Attribute Getters, Setters and Validators</a>

447

</li>

448

449

450

</ul>

451

</div>

452

</div>

453

454

455

456

</div>

457

</div>

458

</div>

459

</div>

460

461

462

463

464

</body>

465

</html>

Older »