A web site is defined as much by how it looks as by what it does. And Ajax raises the bar in the area of user interface and visual design. There is very much an expectation today that your site should look “mahvelous.” So any good Ajax library worth its salt should provide us lots of ways of improving the look of a site. Not only does Dojo provide many full-blown widgets, as we explored in Part II, “Dojo Widgets,” but it also provides techniques for working with individual DOM elements that may not even be part of a widget. This chapter explores ways of identifying DOM elements and then manipulating them in some way—usually by changing some visual aspect.
Dojo widgets, which we’ve already discussed in Part II, are certainly part of the DOM. But what about DOM elements that aren’t associated with widgets? They require some attention also. Let’s do a quick review to remind us what the DOM is. It stands for Document Object Model and is the browser’s internal representation of the web page. We think of a browser as a piece of software that takes an HTML file and displays the page to the computer monitor. This is known as rendering in display terminology. However, that understanding of the browser is actually not quite correct.
What a browser really does is take an HTML file and convert it into an internal representation of the file called a Document Object Model and then renders the DOM. Each HTML tag is converted to one or more DOM elements. This may sound like a distinction without a difference, but it is actually quite important in the Ajax world. After the DOM is built, it doesn’t have to be static. We can manipulate elements in the DOM, and the browser will instantly rerender the DOM and change the display that the user sees. Now, not all DOM changes necessarily cause the display to change, but that is most typical. Because Ajax applications rely so heavily on manipulating the DOM, it is important for developers to be able to identify DOM elements and to manipulate them. It is possible to do that using JavaScript alone, but we’ll use Dojo to make it easier. Let’s talk first about how to find DOM elements.
The DOM for a typical page can easily contain hundreds and sometimes even thousands of elements, also known as element nodes or just plain nodes. If we need to perform some operation on a subset of elements, we need a way to quickly identify those elements. The DOM provides us a technique for iterating through itself that involves getting all the child nodes for each node (beginning with the root node) and looping through them. When a node also has children, we can iterate through those as well. Eventually we could walk through the entire DOM tree, testing each element node for whatever properties we are looking for. This brute force method isn’t very elegant and doesn’t perform very well. Are there any alternatives?
One technique is to provide direct access to a DOM element by specifying its id within the HTML as shown below here:
<div id="target"></div>
We can then use the document.getElementById("target") function to reference the specific DOM element. However, this technique is limited because we can only find a single element. What about when we want to find a group of elements that possess some common property? There is another DOM method available to us, document.getElementsByTag(), which returns an array of the elements for a specific HTML tag such as <p> for paragraph elements. But this function is limited to only allowing us to specify a tag. What if we want all the elements that use a particular CSS style?
Cascading Style Sheets (CSS) already provide a method for finding DOM elements by using a technique it calls selectors. Selectors are strings that identify DOM elements that styles should be applied to. The selector syntax is very rich and can be used to find elements based on a variety of properties. Following is an example of a very simple selector that might be part of your CSS style sheet:
h1 {color: blue}This rule finds all the DOM elements for the <h1> tags and sets their color style property to blue, making the text within the element blue. The “h1” part of the rule is the selector, which tells the browser which set of DOM elements that the rule applies to. Selectors are very powerful, but they can only be used when applying styles in CSS.
Wouldn’t it be nice if we could somehow use the CSS selector syntax to retrieve a list of elements to be used for other purposes? Yes, it would be nice, but that is not part of the JavaScript language. However, it turns out that Dojo can give us that capability. The dojo.query() method takes a selector string as an argument and returns a list of unique DOM elements that match the string. Although this is an extremely powerful technique, the function call is very simple. But there is a little problem. You need to understand the selector syntax to use dojo.query(). So even though it isn’t formally a part of Dojo, let’s spend some time getting to know the selector syntax. This will be a valuable exercise given that we’ll not only be able to use our knowledge in dojo.query(), but we’ll also be able to better use CSS selectors for their original purpose—applying styles in style sheets!
There are many types of selectors, and the syntax can be somewhat challenging for the more advanced ones. But it isn’t important to understand every type of selector. We’ll get tremendous power by just knowing the basics. So let’s start our review of selectors with the simplest types and work our way upward from there.
Let’s review some simple CSS selectors just to get a feel for them. The most basic selectors correspond to HTML tags, such as in the following example:
p {color: blue}Remember, this selector is just the “p” that begins the line, not the rest of the style definition. This selector finds all the elements in the DOM created from the <p> tags in the HTML. If additional elements of type <p> were added to the DOM using JavaScript, they would be found also.
Selectors can be put together by separating them with a comma. This is the equivalent of combining the two sets of elements identified by each individual selector. Any overlap between the sets would be removed. The new set would not repeat an individual DOM element even if it had been identified in each individual selector. The following example shows selector grouping:
p, h1, h2 {color: blue}This would identify a set of all <p>,<h1>, and <h2> DOM elements.
Selectors may identify DOM elements by the id of the element. Place the “#” character in front of the element id as in the following example:
#target {color: blue}This example would find the DOM element whose id is “target,” which could be specified in the HTML sample shown here:
<div id="target"></div>
Style properties are often grouped together and named. The following example defines a class called “plainText,” which can be applied to any element associated with that class. Use the “.” character at the beginning of the class name.
.plainText {color: blue}This example would find the DOM element whose class is “plainText” that could be specified in the HTML sample shown here:
<div id="target" class="plainText"></div>
It is also possible that the class might have been assigned programmatically using JavaScript.
Sometimes it is useful to only select an element if it is part of some other element or element branch. These are called structural selectors. Just list the types separated by spaces with the highest level element type first. For example, you may want to find paragraph elements but only if they are part of a div element. The following example shows how you would do this.
div p {color: blue}This example would find the DOM element of type p but only if it is a child or descendent of a div type. In the following HTML code, the first <p> element would be found, but not the second.
<div><p>Hello</p></div>
<p>Good-bye</p>Element nodes in the DOM can have attributes associated with them. Sometimes you may want to find all the elements that have a particular attribute or have a particular value for an attribute. The technique for creating attribute selectors is to include the attribute name in square brackets:
[height] {color: blue}This example would find all DOM elements that have a height attribute regardless of the actual value assigned to height.
One of the most common uses for this selector is to find all the DOM elements that need to be converted to Dojo widgets. Remember, when we want to replace an element with a widget, we assign the attribute dojoType to the widget as the following code demonstrates for a dijit.form.ValidationTextBox widget.
<input type="text" id="firstName" name="firstName"
dojoType="dijit.form.ValidationTextBox"
required="true"
/>The dojo.parser needs to find all the elements containing an attribute of dojoType. The following code is taken from the Dojo source code for dojo.parser and shows the use of an attribute selector to find all the elements that need to be transformed to Dojo widgets.
var list = d.query('[dojoType]', rootNode);There are many additional selectors available to us. I’ve included a table from the specification to give you a flavor of them. Some of the selectors allow a style to be applied to a specific part of an element (such as the first line). These don’t apply to dojo.query because it is used to find the element and not to apply the style.
The specification describes more complex selectors, and I’d recommend that you read the specification for more detail.[1]
Table 16.1. Other CSS Selectors
Pattern | Meaning | Type of Selector |
|---|---|---|
* | Matches any element. | Universal selector |
E | Matches any E element (i.e., an element of type E). | Type selectors |
E F | Matches any F element that is a descendant of an E element. | Descendant selectors |
E > F | Matches any F element that is a child of an element E. | Child selectors |
E:first-child | Matches element E when E is the first child of its parent. | The :first-child pseudo-class |
E:link E:visited | Matches element E if E is the source anchor of a hyperlink of which the target is not yet visited (:link) or already visited (:visited). | The link pseudo-classes |
E:active E:hover E:focus | Matches E during certain user actions. | The dynamic pseudo-classes |
E:lang(c) | Matches element of type E if it is in (human) language c (the document language specifies how language is determined). | The :lang() pseudo-class |
E + F | Matches any F element immediately preceded by an element E. | Adjacent selectors |
E[foo] | Matches any E element with the “foo” attribute set (whatever the value). | Attribute selectors |
E[foo=“warning”] | Matches any E element whose “foo” attribute value is exactly equal to “warning.” | Attribute selectors |
E[foo~=“warning”] | Matches any E element whose “foo” attribute value is a list of space-separated values, one of which is exactly equal to “warning.” | Attribute selectors |
E[lang|=“en”] | Matches any E element whose “lang” attribute has a hyphen-separated list of values beginning (from the left) with “en.” | Attribute selectors |
DIV.warning | HTML only. The same as DIV[class~=“warning”]. | Class selectors |
E#myid | Matches any E element id equal to “myid.” | ID selectors |
Dojo also provides support for the CSS 3 Specification that includes some additional selector types that are beyond the scope of this discussion. Again, more information can be found in the specification.[2]
The technique for using a selector to find a set of DOM elements using Dojo is straightforward. Just pass the selector as a string to the dojo.query function. For example, to find all the <h1> elements, use the following code.
elementList = dojo.query("h1");More complex selectors require a more complex selector string, but the syntax for getting the elements is still the same. To find all the paragraph elements that are descendents of a div element, use the code shown here:
elementList = dojo.query("div p");And the syntax doesn’t get any more complicated—although the selector strings do! Here’s another example. This one uses the class attribute selector just described to find all the elements that are associated with the class “plainText.”
elementList = dojo.query(".plainText");The dojo.query function is part of base Dojo. This means that you don’t need to include a dojo.require statement to bring the function into your page. Just call the function from your code.
What can you do with the elements from the DOM after you find them using dojo.query? The short answer is that you can do anything with them you want. Typically though, you would probably want to change some style property, move the elements, make them visible, hide them, or perform some kind of special effect. All these things can be done using some special features of Dojo known as animation and effects.
For me, the term “animation” brings to mind Saturday mornings as a child, being glued to the television, watching hour after hour of cartoons. And actually, in terms of explaining animation in Dojo, this may be an apt metaphor. Thinking about cartoons will help us understand some things about animation.
A cartoon is a series of fixed images that when, presented in sequence, provide the illusion of movement or action. It turns out that this is exactly the same process used by Dojo. Let me give you an example. A well-known web design company in Chicago, 37signals, developed a method of highlighting DOM elements whenever they changed due to an Ajax request. The method requires that the background color of the element be changed to yellow and then the background color should slowly fade back to white (or whatever the original background color was). They called this the Yellow Fade Technique (YFT) for obvious reasons.
Exactly how is the effect performed? We simply set the background color of the element to yellow. The following code shows how we would do this for an element whose id is “div1”:
document.getElementById("div1").style.background = #FFFF00;To fade the background color back to the original background color, we just have to do a little math. Remember that the Red/Blue/Green (RGB) color scheme used by the web consists of hexadecimal representations of each of the colors. So yellow is represented in the values in Table 16.2.
We’ll use the decimal values instead of hexadecimal. So the three colors are represented by the range of numbers from 0 (no color at all) to 255 (full color). I like to think of each color as a flashlight with 256 different power settings.
It never strikes me as intuitive, but in the world of computer monitors, red and green mixed together is yellow! Let’s say the original background color was white (RGB value: 255,255,255). To produce the fade, we simply need to iterate through a series of fixed values for color until we reach the value we are looking for.
For example, starting with the color yellow and fading back to white, we would loop through the following values for background color:
255, 255, 0
255, 255, 1
255, 255, 2
And so on and so on, all the way to 255, 255, 255.
At each iteration we would set the new background color and pause for a bit before moving on to the next value. Think of the browser as showing us 256 distinct images, each having a different background color for the element we’re working with. We’ll call each image a frame (as Dojo does), and by iterating quickly through the frames, it would appear as through the background is fading from yellow to white. So we might use the following code to perform out looping:
for (i = 0; i < 256; i++) {
color = "rgb('256, 256", + i + "')";
document.getElementById("div1").style.background = color;
}The problem with this code is that the frames will go by so quickly that we won’t even get a chance to see them. It will look like the last frame just suddenly appeared. In other words, the yellow background will appear for only a few milliseconds or not at all. Also while the JavaScript is performing the loop, no other code execution is possible. This could be a more serious problem when we use a different property that might include many more iterations.
Using a special JavaScript function called setTimeOut can solve both these problems. It allows us to specify a function to be executed and a delay before that function is run. This allows other JavaScript to run while the browser is waiting for the time-out function to run again. We’ll modify our code to use this new function:
var FADE_BLUE = 0;
function yellowFade() {
el = document.getElementById("fade_target");
color = "rgb("255, 255, " + FADE_BLUE + ")";
FADE_BLUE = FADE_BLUE + 1;
el.style.background = color;
if (FADE_BLUE >= 256) {
return;
} else {
setTimeout(yellowFade, 1);
}The function yellowFade would have to been called from somewhere the first time, but once it starts it runs for a single value of FADE_BLUE and then kicks off another iteration by calling the setTimeout function, which will run one millisecond later. If you run this code you’ll find that the effect is rather slow because the browser doesn’t run the code right away; it takes a little longer than a single millisecond to start the next iteration. A better approach would be to lengthen the delay and to increase the increment size for changing the color. Not too complicated, but more than we really want to deal with every time we create some kind of visual effect. Isn’t there an easier way? We’ll see shortly that Dojo provides a wrapper around this technique in the form of the dojo.animateProperty function. It hides the details of changing the property values and running the setTimeout function. Let’s explore how we can use this new Dojo function to simplify the creation of animations.
Certainly it is possible to use JavaScript to create very complex visual effects just by using the technique of changing a style property value repeatedly over a period of time. So we already have in our hands the tool we need to build wonderful special effects. However, Dojo can make this technique much easier to use by providing a simple function call to do all the necessary coding for us. Dojo provides a function, dojo.animateProperty, which does this all for us.
Table 16.3. Description of dojo.animateProperty Function
Method Signature: |
|
Summary: | This function will iterate over values of a property on a DOM element beginning with the current value (or a stated value) of the property and extending to the specified ending value in the arguments. The effect of the iteration is to produce a visual change to the element. This function doesn’t perform the animation. It actually returns an object that represents the animation. To run the animation, execute the |
Parameter: node | Id of a DOM element or a DOM node reference. |
Parameter: properties | An object containing properties with names corresponding to actual properties within the DOM element’s style object. For example, this object could have a property called Each property object may have a |
Parameter: duration | The time in milliseconds the animation will take to run. This parameter is optional. |
Parameter: rate | The time in milliseconds to wait before advancing to next frame. This parameter is optional. |
Following is an example of its use.
var animation = dojo.animateProperty({
node: dojo.byId("target"),
duration: 1500,
properties: {
backgroundColor: { end: "white" }
}
});
animation.play();This example iterates over a color property from whatever the current background color is to the color “white,” spanning a time of 1.5 seconds. To the user it looks like the element’s background color slowly fades to white. The preceding example achieves the same effect as we built manually in section 16.3.1 by iterating the style.background property ourselves. However, I think you’ll agree that using the Dojo function simplifies the code that we have to write.
And although our example is fairly simple, we can use dojo.animateProperty to provide more complex animations that cycle through multiple style properties at once. Following is an example from the Dojo documentation that shows just that:
dojo.animateProperty({
node: node, duration:2000,
properties: {
width: { start: '200', end: '400', unit:"px" },
height: { start:'200', end: '400', unit:"px" },
paddingTop: { start:'5', end:'50', unit:"px" }
}
}).play()This more complex effect will vary three different properties over a period of two seconds. We now have the tool to create almost any visual effect we can think of but, even better, Dojo has pre-packaged some standard effects for us.
Some animations are so common that Dojo provides shortcut functions to create them. They could be built by running one or more complex dojo.animateProperty function calls and a varying a number of properties at the same time, but by having a simple Dojo function with a descriptive name, we can achieve the same goal more directly. For example, it is often useful in an Ajax application to move a DOM element from one position on the page to another. We could do this by using dojo.animateProperty and varying the top and left properties, but instead we can use the dojo.fx.slideTo function and specify only the final position rather than the starting and ending values of each property. This and other common effects are contained in the dojo.fx package. Let’s discuss these functions now.
This function allows you to “slide” a DOM element around the screen. Rather than just redrawing it in a new location, this effect shows the element at intermediate locations so that it appears to move.
Table 16.4. Description of dojo.fx.slideTo Function
Method Signature: |
|
Summary: | This function returns an animation object that will move a DOM element from its current position to a new position specified by the arguments. |
Parameter: node | DOM element to be moved. |
Parameter: left | The left position to which the element should be moved. This represents the value of the |
Parameter: top | The top position to which the element should be moved. This represents the |
Parameter: unit | The units that the left and top properties are specified in (i.e. |
Following is an example of its use.
dojo.fx.slideTo({
node: dojo.byId("target"),
left:"100",
top:"50",
unit:"px" }).play()This example moves a DOM element whose id is “target” from whatever its current position is to a new position where the elements upper left corner is 50 pixels from the top border of the browser window and 100 pixels from the left border of the browser window. Remember that this function simply returns an animation object. To run the animation you, must execute its play method as shown in the example.
This function may sound like it has something to do with riding a surfboard, but it does not. However, like a surfer who “wipes out,” the DOM element that this effect operates on also disappears beneath the waves. Think of this effect as causing the DOM element to disappear beginning from the bottom of the element to the top. Another way to picture this effect is to imagine what would happen if you placed an eraser at the bottom of the element and “wiped up.” You would be wiping out the element.
Table 16.5. Description of dojo.fx.wipeOut Function
Method Signature: |
|
Summary: | Returns an animation that will shrink the element from its current height to 1px and then hide it. |
Parameter: node | DOM element on which the “wipe out” effect will be performed. |
Parameter: duration | Length of time in milliseconds over which the effect will occur. |
Parameter: onEnd | Function to be executed after the effect is run. |
Following is an example of its use.
dojo.fx.wipeOut({
node: dojo.byId("target"),
duration: 500
}).play()This code causes the DOM element to disappear over a period of half a second (500 milliseconds). The way that it works internally is that the element’s height is changed from the original height to a new height of zero over the duration of the effect and then hidden. The original element takes up no space on the page after it is hidden so any elements below it are moved up as it disappears.
This function is the inverse of the previous function. It causes an element to reappear after it has been wiped out using the dojo.fx.wipeOut function. However, the resulting look might not be exactly what you imagined. The resulting element might have a smaller height than it did originally. The reason for this is that there are two ways to set the height of an element. The first uses the height style property and is used to explicitly set the height. The second technique is to let the browser figure out what the height should be based on the content of the element. The Dojo documentation refers to this as the “natural” height. After the element’s height is set to zero using dojo.fx.wipeOut, Dojo doesn’t remember the original height, so it allows the browser to recalculate it using the “natural” method, which may be different than the original height.
Table 16.6. Description of dojo.fx.wipeIn Function
| |
Summary: | Returns an animation that will expand the node defined in “node” to its natural height and make it visible. |
Parameters: node | DOM element on which the effect will be performed. |
Parameters: duration | Length of time in milliseconds over which the effect will occur. |
Parameters: onEnd | Function to be executed after the effect is run. |
Following is an example of its use.
dojo.fx.wipeIn({
node: dojo.byId("target"),
duration: 500
}).play()This causes the DOM element to reappear over a period of half a second.
This effect causes the element to gradually disappear. It is similar to dojo.fx.wipeOut in that by the end of the effect the element is no longer visible, but the technique for achieving that end is different. In this effect, the element becomes less and less opaque until it is completely invisible. However, it still takes up room on the page so that surrounding elements don’t get rearranged. It uses the opacity style property of the element that can range from 1 (completely opaque) to 0 (completely transparent). Notice that this effect is in Dojo base and not the dojo.fx package, so no dojo.require statement is necessary to make it available.
Table 16.7. Description of dojo.fx.fadeOut Function
Method Signature: |
|
Summary: | Returns an animation that will increase the opacity of the specified element until it is completely transparent. |
Parameter: node | DOM element on which the effect will be performed. |
Parameter: duration | Length of time in milliseconds over which the effect will occur. |
Parameter: onEnd | Function to be executed after the effect is run. This parameter is optional. |
Following is an example of its use.
dojo.fadeOut({
node: dojo.byId("target"),
duration: 500
}).play()This example will fade the element specified in node over a period of half a second.
This effect is the reverse of the dojo.fadeOut effect. It causes an element that is currently invisible to gradually become visible. It uses the reverse technique that dojo.fadeOut uses. It changes the opacity style property of the element from 0 (fully transparent) to 1 (fully opaque). The element, even when invisible, still takes up space on the page, so no rearranging of surrounding elements is necessary. Notice that this effect is in Dojo base and not the dojo.fx package, so no dojo.require statement is necessary to make it available.
Table 16.8. Description of dojo.fx.fadeIn Function
Method Signature: |
|
Summary: | Returns an animation that will decrease the opacity of the specified element until it is completely visible. |
Parameters: node | DOM element on which the effect will be performed. |
Parameters: duration | Length of time in milliseconds over which the effect will occur. |
Parameters: onEnd | Function to be executed after the effect is run. |
Following is an example of its use.
dojo.fadeIn({
node: dojo.byId("target"),
duration: 500
}).play()This example will gradually make a transparent element visible over a period of half a second.
This function is not an effect in itself. But it does allow you to use multiple effects together. Given a series of effects, this function will execute each one in order. The effects are executed one at a time until the last effect is complete.
Table 16.9. Description of dojo.fx.chain Function
Method Signature: |
|
Summary: | This function will run a series of animations one at a time, starting a new animation only after the prior animation is complete. |
Parameters: animations | An array of animation objects to be executed serially and in order. |
Following is an example of its use.
dojo.fx.chain([
dojo.fx.wipeOut({ node:node }),
dojo.fx.wipeIn({ node:otherNode })
]).play()This example will hide the first element and then show the second element.
This function allows you to combine multiple effects. But while dojo.chain runs the effects serially, this function runs the effects in parallel so they are executing at the same time. This function starts each effect in the order specified, and then they run essentially in parallel.
Following is an example of its use.
dojo.fx.combine([
dojo.fx.wipeOut({ node:node }),
dojo.fx.wipeIn({ node:otherNode })
]).play()This example will hide the first element and show the second element at the same time.
Many visual effects have a sort of “equal and opposite” effect that can be associated with them. For example, dojo.fadeOut makes a DOM element disappear, and dojo.fadeIn brings it back. We can think of one function as hiding the DOM element and the other function as showing the element. This is such a common idiom that the Dojo team decided to encapsulate it in a function, dojo.fx.Toggler. You provide an effect that “shows” the element and a separate effect that “hides” it. The Toggler object has two methods, show and hide, which you can run to execute the associated effect. These effects don’t have to work on the same style properties. The “show” effect could change the background color property while the hide effect could change the height property.
Table 16.11. Description of dojo.fx.Toggler Function
Method Signature: |
|
Summary: | This function will toggle effects on a single DOM element. The arguments are passed as a single object with properties. As with the other effects, this function returns an animation object. To run the effect, the |
Parameters: node | DOM element on which the effect will be performed. |
Parameters: hideFunc | Function to be executed that will “hide” the element. |
Parameters: showFunc | Function to be executed that will “show” the element. |
Following is an example of its use.
var t = dojo.fx.Toggler({
node: dojo.byId("target"),
hideFunc: dojo.fx.wipeOut,
showFunc: dojo.fx.wipeIn
});
t.hide();
t.show();This example will hide the element and then show the element—usually these wouldn’t be done together.
We’ve reviewed many of the building blocks for Dojo applications in the past chapters. After we put them all together into a complete application, we might find that we have a few errors. The next chapter will discuss tools and techniques in Dojo for finding these errors and debugging our applications.
[1] http://www.w3.org/TR/REC-CSS2/selector.html Copyright © World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
[2] The CSS 3 Specification can be viewed at the following link: http://www.w3.org/TR/2001/CR-css3-selectors-20011113/