This is the first of a series of posts related to learning and understanding baseJS: the mobile javascript framework. These posts are intended for anyone familiar with JavaScript who wants to start learning about baseJS and how it can help them develop webapps for the iPhone. In this post, we'll look at Element Selectors and Event Listeners.

Element Selectors

At its core, baseJS focuses on using the Selectors API as its primary method of getting elements from the DOM. If the Selectors API is not available, like in pre iPhone 2.0 frameworks, baseJS preloads the Sizzle selector engine before it will respond with the dom:loaded event that we will look over near the end of this post.

What does all of that mean? It means that you can use simple or complex CSS selectors to grab elements as NodeList. Take the following HTML as a section of code in our web page:

<div class="foo">This is an element with class 'foo'</div>
<p class="foo">And another element with class 'foo'</p>

A simple CSS class selector will do for grabbing all elements with class foo:

var foos = $('.foo');

We’ve now selected every element with class foo and stored them into a NodeList called foos. Note that a NodeList is basically an Array, thought it has one extra method called item().

You can now grab a specific element in the NodeList in two different ways. In this example, both methods return the first element that matches the class foo

var arraySelect = foos[0]; 
var itemSelect = foos.item(0);

From this point, you are able to modify your first element with the class foo as you please. For instance, the following removeClass() method is available in the baseJS API to remove a specific class from an element:

arraySelect.removeClass('foo');

Event Listeners

Event listeners are registered by using the built in DOM method on elements called addEventListener. The reason most frameworks have custom event listeners is because they need to support Internet Explorer’s proprietary method called attachEvent. Since we're not worried about IE, we can just jump on the built-in methods.

Example

Let’s assume that we have the following HTML and we want to intercept every click on it and alert the innerHTML of the link. I know, it’s impractical and you’d probably never do it, but it’s a nice “Hello World” example.

<a id="myLink" href="http://google.com">This is My Link</a>

Since this element has an id myLink, that would be the easiest selector for us to use to guarantee that we're getting the correct HTML element. Using the Element Selector $(), we can store the element into a variable like this:

var myLink = $('a#myLink').item(0);

Notice that I used the .item(0) method to select the first (and only) result that was sent back to the NodeList. baseJS is not like jQuery in the sense that everything is wrapped in the $ core method. So, now that we have our element, we can add an event listener to it, stop the event, and alert the innerHTML of the element.

First, let's review the addEventListener method:

element.addEventListener(type, listener, useCapture);

type

String

The type of event to listen for. One of 'click', 'mouseover', etc.

listener

Object or Function

The callback object or function that will receive the event. We’ll use a function.

useCapture

Boolean

Always set this to true to initiate capturing the event.

So, let’s put the element selector and event listener into context:

var myLink = $('a#myLink').item(0);
myLink.addEventListener('click', function(event) {
    event.stop(); // this stops the original HTML event from progressing (the href won't change the page)

    alert(event.target.innerHTML);
}, true); // always set useCapture to true because we DO want to capture the event

Now, this will work, assuming the page is loaded and the DOM is ready. If we aren't sure and we're firing this JavaScript right as the page loads, it's best to wrap this in a function that will be fired only after the DOM is loaded and ready.

We can do this by simply adding a wrapper function around the previous code that we'll call initialize() and setting up another event listener on the document and check for baseJS’s dom:loaded event before running the function:

baseJS fires a custom dom:loaded event after the DOM is done loading and it has loaded the Sizzle selector engine if it needs to.

function initialize() {
    var myLink = $('a#myLink').item(0);
    myLink.addEventListener('click', function(event) {
        event.stop();

        alert(event.innerHTML);
    }, true);
}

document.addEventListener('dom:loaded', initialize, true);

Wrapping Up

That's it for this beginning introduction to selectors and events in baseJS. If you haven't checked it out yet, head on over to the baseJS project page. If you'd like to know more, check out the baseJS API documentation and stay tuned for more posts.