Modifying HTML with jQuery

The philquotes module's hook_block() implementation (in philquotes.module) creates a block of HTML that looks as follows:

<h2 class="title">Pithy Quote</h2> <div class="content">

<div id="philquotes-text">

The only principle that does not inhibit progress is: anything goes. </div>

<div id="philquotes-origin">

P. Feyerabend, Against Method </div> </div>

Two of the <div/> elements above, those with IDs philquotes-text and philquotes-origin, are created by the module's theme function, theme_philquotes_quote() .

Now we will begin writing some JavaScript code. This code will be part of our module, and it will go in its own file. Following standard naming conventions, the file will be stored in drupal/sites/all/modules/philquotes/philquotes.js.

The first thing that we want to do with our JavaScript is insert a Next link at the end of this block, just after the quote's origin.

jQuery provides the tools to do this simply and efficiently. With jQuery, this is a two-step process:

1. Find the philquotes-origin element

2. Insert a link after the element

The code is as follows:

$("#philquotes-origin").after("<a>Next &raquo;</a>");

This one line of code, at first glance, might appear to be both clean and confusing. Since we will be using jQuery several times in this chapter, we will devote a little time here to see what is going on.

The above line contains two function calls. The first function call looks like this: $("#philquotes-origin"). The function name, here, is $(). In JavaScript, the dollar sign ($) is a legal character when used in variable and function names. That means countMy$() and and give$away() are both valid function names in JavaScript. So is $(). By default, the jQuery library uses this function as a way to access the jQuery object. (You can also use the longer version, jQuery(), if you prefer.)

The $() function can be called several different ways, but the most common use of the function is to pass it a query, in the form of a CSS selector. (See http://docs. jquery.com/Selectors for a list of supported selectors.)

When jQuery is called this way, it searches the DOM tree for the current HTML and returns a jQuery object that contains a list of elements that match the query.

Looking back at our code above, the $("#philquotes-origin") call returns a jQuery object. Since the selector, #philquotes-origin, refers to an element ID, it will match no more than one element. According to our earlier HTML, it should match this element:

<div id="philquotes-origin">

P. Feyerabend, Against Method </div>

So our first call to $() returned a jQuery object. Making use of the fluent interface, we simply call the after() method on that returned object:

$("#philquotes-origin").after("<a>Next &raquo;</a>");

The after() method inserts content after the referenced element. In this case, it will put the content after the <div/> element above. So if we ran this query on a page with a quote on it, the resulting HTML would look like as follows:

<h2 class="title">Pithy Quote</h2> <div class="content">

<div id="philquotes-text">

The jQuery library is well documented. In addition to complete API documentation, there are also many tutorials on the topic. The best place to start is with the official jQuery documentation page: http://docs. jquery.com/Main_Page.

The only principle that does not inhibit progress is: anything goes. </div>

<div id="philquotes-origin">

P. Feyerabend, Against Method </div>

While we don't make use of it in the code above, the after() function also returns a reference to the jQuery object, so we could continue chaining if we wanted.

I ■ Using your browser's "View Source" feature will not show the newly I

inserted element. To see the source as it is modified by JavaScript, you I

will need FireBug or some other JavaScript development tool.

The jQuery object has a number of similar functions to after(). The html() function inserts HTML inside the selected element. The before() function inserts HTML before the selected element.

Getter or Setter?

One aspect of jQuery that can be startling at first is that one method may serve as both a getter and setter (or, an accessor and a mutator). That means that html("<br/>") will insert content into the current element and return a jQuery object, while html() (with no arguments) will not change anything, but will return the contents of the element.

What we have accomplished so far is the insertion of a small piece of HTML into our existing document. However, this little query alone may not work. Why?

There are two reasons:

• First, the browser may not support the requisite JavaScript. If this is the case, we don't want to insert this element at all.

• Second, the browser may execute the query before it has finished loading the HTML. In such a case, the query might not even find the philequotes-origin element.

We need to fix these two problems before moving on.

0 0

Post a comment