YUI Library Examples: Attribute: Basic Configuration

Attribute: Basic Configuration

Setting Up Your Own Class To Use Attribute

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 walk you through listening for attribute change events and some of the more advanced attribute configuration properties.

Creating A YUI Instance

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:

<script type="text/javascript"> // Create our local YUI instance, to avoid // modifying the global YUI object YUI({...}).use("node", "attribute", function(Y) { // Example code is written inside this function, // which gets passed our own YUI instance, Y, loaded // with the modules we asked for - "node" and "attribute" }); </script>

The call to YUI() 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.

To load the modules, we invoke use() and pass it the list of modules we'd like populated on our new YUI instance - in this case, node and attribute. The YUI instance will pull down the source files for node and attribute if they don't already exist on the page. When the source files are done downloading, the callback function which we pass in as the 3rd argument to use() is invoked, and is passed our custom YUI instance, Y, populated with the classes which make up the node and attribute modules.

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

NOTE: The configuration object passed to YUI() when creating the instance, is used to specify how (combined, separate, debug, min etc.) we want the files downloaded and from where. The API documentation for the YUI object, provides more information about the configuration options available.

Defining Your Custom Class

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 MyClass. We then augment MyClass with the Y.Attribute class, so that it receives all of Attribute's methods:

function MyClass(cfg) { ... } Y.augment(MyClass, Y.Attribute);

Adding Attributes

We can now setup any attributes we need for MyClass. We can setup multiple attributes in one call using the using the _initAtts method (a protected method, designed to be used by the augmented class, as opposed to end users of your class). For the basic example we add 3 attributes - foo,bar, and foobar, and provide an initial value for each. The same object literal we use to provide the value for the attribute will also be used in the other examples to configure specific types of attributes using properties such as readOnly, writeOnce, validator etc..

For convenience (not required), we define the set of attributes which MyClass supports as a static property on our MyClass constructor. This static property is passed to _initAtts to setup the attributes, as part of MyClass's constructor. The complete definition for MyClass is shown below:

function MyClass(cfg) { // When constructed, setup the // initial attributes for the // instance, by calling the // protected _initAtts method this._initAtts(MyClass.ATTRIBUTES, cfg); } // Setup static property to hold attribute config MyClass.ATTRIBUTES = { // Add 3 attributes, foo, bar and foobar "foo" : { value:5 }, "bar" : { value:"Hello World!" }, "foobar" : { value:true } }; // Augment custom class with Attribute Y.augment(MyClass, Y.Attribute);

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

Using Attributes

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

// Create a new instance of MyClass, without over-riding // any initial values var o1 = new MyClass(); // Print out the current values of foo, bar, foobar var print = YUI.example.print; print("<strong>o1 values set during construction:</strong>"); print("foo:" + o1.get("foo")); print("bar:" + o1.get("bar")); print("foobar:" + o1.get("foobar")); // Set the values of foo, bar and foobar using // the set method provided by Attribute o1.set("foo", 10); o1.set("bar", "Hello New World!"); o1.set("foobar", false); // Print out the new values of foo, bar, foobar print("<strong>o1 new values:</strong>"); print("new foo:" + o1.get("foo")); print("new bar:" + o1.get("bar")); print("new foobar:" + o1.get("foobar"));

For the second instance that we create in the example we set the values of the attributes, using the contructor configuration argument:

var o2 = new MyClass({ foo: 7, bar: "Aloha World!", foobar: false });

So, in this example, we see how we can setup a new class with Attribute support allowing the end user to get and set attribute values on the instances they create.