YUI: getElementsBy

by K. Beau Beauchamp | Feb 3rd, 2010

YUI is one of the most powerful Javascript frameworks in existence today. Yet, far too many UI programmers are unaware of this true full-stack JavaScript framework and its amazing capabilities. Beau Beaucahmp discusses one of the more powerful DOM functions of the YUI library: the very cool getElementsBy DOM function.

Super-Awesome Power At Your Fingertips

If you’ve been programming in UI for any length of time then you’re familiar with Javascript’s built-in getElementById function that is used to return a single element within the DOM tree by simply passing in the element’s ID. YUI’s getElementsBy is quite simply getElementById on some serious steroids. Not only does this powerful function allow you to snap-up a single element, but it can grab a whole array of elements chosen and filtered any way you like, all in a single call.

But wait, there’s more! getElementsBy also allows you to manipulate each of the elements within your array with an optional function you supply!

Setting-up Your Page to Use YUI

First you’ll need to download and copy the core YUI files to a directory on your site. I usually like to have a /javascrpt or /js folder inside my document root that holds all of my JavaScript files. The core YUI files you’ll need will be found inside the /yui/build directory. I like to copy YUI’s /build folder to my /javascript folder and rename /build to /yui for convenience.

Now add for following code inside the <head> ... </head> tags of your page:

or you can have your page load the YUI files directly from YAHOO! using this script tag instead of the one above:

Now you’ll have all of the various YUI Core, DOM and Events functions at your command. Let’s look at what the getElementsBy function params look like:

var Dom = YAHOO.util.Dom;
var els = Dom.getElementsBy(
    function(el){ ... },
        tagname,
        parentroot,
        function(el){ ... }
);

All of the YUI functions live in the YAHOO namespace. As such, I like to pair down my code by assigning all of the Dom and Event functions to a simple reference var, like Dom. This way, I can access the YUI DOM functions with a simple Dom.getElementsBy() as we see in line 2.

Note that getElementsBy can work with or without returning anything. If you do return elements, note that unlike getElementById, getElementsBy always returns an array() of elements. Even if you will only be returning a single element, keep in mind that it will be referenced as els[0].

Line 3 is where the real fun begins. You begin gathering your elements with a simple boolean function that returns true or false. Let’s say I want to toggle a check or uncheck for every checkbox within a form. A good boolean function to use here would be return (el.type == 'checkbox');. Notice that el is an element that will get passed into this function to be tested. If the element has the attribute of type="checkbox" the function will return true and add the element to our els array.

Notice that only the first attribute of getElementsBy is necessary. The second and third parameters can be set to null. However, setting these parameters to null will cause getElementsBy to process EVERY ELEMENT on the page! This is not very efficient, especially for really large pages. That’s where the second and third parameters of this function come in handy. In line 4 of our code we can specify a specific tag name, such as input. In this way, the getElementsBy function will ignore all elements except input elements which it will then pass to the boolean function we built in the previous paragraph.

Even with this optimization, you still might want to further define where to begin your elements search. getElmentsBy allows you to optionally specify a third parameter, a root parent element to search within. If all of the elements you need to process are the children of a specific div for instance, passing in the ID string or element reference of the containing parent will limit even further where within the DOM getElementsBy needs to look.

So, with these three parameters supplied to our getElmentsBy function, we can collect a very specific set of elements, in our sample case we’re looking for all of the checkboxes, anywhere within the DOM of our page.

Putting getElementsBy to Work

Here’s where getElmentsBy becomes a real time saver. Normally, once you have built your array, you’d need to write code that loops through each of the elements within your array to do something with each element of the array; in our case we’re setting the checkbox elements to either be checked or unchecked. So why not just apply whatever function to each element as it is being added to the array built by getElmentsBy? Brilliant!

The final param of the getElmentsBy function is designed to do just that. Using this optional function, we can apply code to each of the elements being added to our final array. And we’re not just limited to checking or un-checking chekcboxes here. Anything you can do inside a function can be applied to any, all or some of the array elements.

Use this final function to selectively add an event listener, set element values and/or attributes (which is what we’re going to do with our checkboxes), or whatever.

var Dom = YAHOO.util.Dom;
var els = Dom.getElementsBy(
    function(el){
        return ( el.type === 'checkbox' );
    },
    'input',
    'myform',
    function(el){
        el.checked === true;
    }
);

One Call Does It All

So let’s show a simple function using getElmentsBy that checks or un-checks all of the checkboxes on a form.

Here’s the example:

and here’s the code:

Copy and save the page as myfile.html to see how it works!

Conclusion

While other JavaScript libraries indeed have similar functions, I really like the inherent flexibility of getElementsBy. The beauty of YUI is that it works like JavaScript is supposed to work, it’s written they way JavaScript is written. And you don’t have to memorize a whole new syntax or funky var language to use the power of YUI.

____________________________

K. Beau Beauchamp is a professional UI developer with over 15 year’s experience in graphic design, marketing communications and object-oriented UI programming. Beau can be contacted via email here.

Ж

Copyright © 2010 WebTigers