Styling the AOL Video Search API Function

by Jeremy Matzan
April 9, 2007

As you've seen in a previous article, adding the AOL video search code to a web page is straightforward. From a coding standpoint, the process is more or less "cut and paste," but from a design standpoint, things are more complicated. How do you change the style elements of your AOL video search page, once you've successfully implemented the API? This article will show you how to apply your site's existing cascading style sheet (CSS) to the AOL video search API, or design your own style sheet for a specific video search page.

Working with the Code

The first step is to take a look at the code that you have to work with and figure out what you can do with it. In this case, we'll start out with an excellent example from the article "Building a Simple AOL Video Search API Application." The HTML code given in the article is as follows:

<html>
<head>
<title>AOL Video Search</title>
<script type="text/javascript" 
     src="http://api.searchvideo.com/AOLVideoSearchAPIv3.js">
</script>
<script type="text/javascript" src="application.js">
</script>
</head>
<body>
<form name="vidsearchform">
<input type="text" name="searchterms">
<input type="submit" name="searchsubmit" value="search videos" disabled>
</form>
<div id="status">html loaded, starting application...</div>
<div id="results"></div>
</body>
</html>

Figure 1 shows how this unstyled page looks in a browser after at search has been executed.

Figure 1. Unstyled AOL Video Search web page

The application logic has been abstracted from the HTML and content and isolated to the application.js file. From a design standpoint this is excellent, because it allows you to style the page without having to worry about harming the page's functionality. However, there is one significant flaw in the above HTML file--it's missing a document type definition (DTD). Without a DTD, web browsers don't know how to best render your markup, and are therefore forced to make guesses about the HTML and CSS standards you are using. For the most part, web browsers are pretty good at blindly rendering HTML style elements as long as you keep them simple and standards-compliant, but once you get into the positioning of elements and other more complex style attributes, you will run into a variety of browser compatibility issues. The quickest and easiest way to solve this problem is to insert a DTD before the <html> tag. For this example we'll use the XHTML 1.0 Transitional document type, which encourages you to relegate all style attributes to an external CSS file, but doesn't prevent you from "cheating" now and then by using rogue HTML style tags in the HTML file. XHTML 1.0 requires that you close all tags, and that they use only lowercase letters. The code sample above already conforms to these rules, so the only thing you have to do is add this line to the top of the file:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

That DTD should be at the top of every page on your website; this ensures that web browsers will render them predictably and uniformly.

Next, let's add a little more content to the page so that there's something to work with other than just the search form. We'll put in a page heading, some introductory text, and a caption above the search window that explains what it does:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>AOL Video Search</title>
<script type="text/javascript"
     src="http://api.searchvideo.com/AOLVideoSearchAPIv3.js">
</script>
<script type="text/javascript" src="application.js">
</script>
</head>
<body>
<h1>Welcome to the video search page</h1>
<p id="introduction">This page enables you to search the videos
stored in the videos.aol.com database. To search, type in some key
words in the field below, then click the Search Videos button.</p>
<form name="vidsearchform">
<input type="text" name="searchterms">
<input type="submit" name="searchsubmit" 
   value="search videos" disabled>
</form>
<div id="status">html loaded, starting application...</div>
<div id="results"></div>
</body>
</html>

Even with all of this new content, the page still looks pretty plain and nondescript. That's where CSS comes in. The point is not to make the page look pretty--though that may be your eventual goal--but rather to make it easier to use by bringing the appropriate level of distinction to each area of the page.

Recognizing Stylable Elements

The next step is to take a look at the HTML and figure out what elements can be styled. Nearly every HTML element can be modified in some way with style tags or a style sheet. The exceptions are code tags like those that precede PHP, JavaScript, and other similar languages. High-level tags can't be styled, either, meaning <html> and <head>, and though it technically can have some style attributes, there is generally no reason to use them in the <title> tag. The <body> tag can be styled if you so choose, and may be the best way to add a background to the entire page. Everything else is fair game.

Starting at the top, the first element you might want to style is the <body> tag. Moving downward, <h1> can be styled, and the <p id="introduction"> tag is already assigned an ID, which you'll specify in your CSS file later. There is little you can or should do with the <form> tag, and since it is required by the JavaScript file to fit certain parameters, you're better off leaving it alone unless you're good enough with JavaScript that you can hack the form without messing up the program logic. The <input> tag, on the other hand, can be heavily modified to do a variety of interesting things with text. Some of them you won't want to mess with; others may be necessary to enhance the form's usability.

Lastly, there are two <div> tags that define some feedback messages. These already have IDs, so there's no further work to be done in this HTML file to style it. To say that <div> elements can be heavily styled is an understatement.

So far we've only dealt with the search portion of the page. Once you enter a search term into the text box and click the button, the results will be displayed below it in a plain, unembellished, hard-to-read manner (see Figure 1). In order to fix this, you'll have to go into your application.js file and look for this function:

function displayResults()
{
    var outputhtml = "";

    for (var i=0; i < AOLVS.VideoSet.totalResultsReturned; i++)
    {
        outputhtml += "<div>";
        outputhtml += "<a href='" +
            AOLVS.VideoSet.Video[i].videoUrl + "'>";
        outputhtml += AOLVS.VideoSet.Video[i].title + "</a>";
        outputhtml += "<p>" +
            AOLVS.VideoSet.Video[i].description + "</p>";
        outputhtml += "</div>";
    }
    outputhtml += (AOLVS.VideoSet.totalResultsReturned == 0) ? 
        "<div>No videos found.</div>" : 
        "<div>(end of results)</div>";
    document.getElementById("results").innerHTML = outputhtml;
}

This function pieces together some HTML fragments to display dynamically retrieved results. As such, it's a bit hard to read in its pre-rendered format, but if you focus on the HTML tags, you can see the basic structure of each item in the result list. It starts out with a plain <div> tag, a plain link, and then puts the video's description into a plain <p> tag. Lastly, the status message is displayed after the results--the user is either informed that no results were returned, or he is notified that this is the end of the results list. These messages are both displayed in plain text inside of <div> tags.

Making the Code CSS-Friendly

Most of the code you've seen so far can either be modified directly through a CSS file (the <body> and <h1> tags, for instance); are modified in place (the <input> tag); or have IDs that will match up to a CSS entry. The reason why <body> doesn't need an ID is because it can only appear once per page. The <h1> tag will be redefined in the CSS file, but it doesn't need an ID because heading tags were meant to be nestable and therefore consistent. In other words, you want all of your top-level (h1) headings to have a consistent style, and any headings nested inside of them (h2, h3, etc., up to h6) need to be consistent as well. So if you want to use a different heading style on this page, it's better to use <h2> than to define two different kinds of <h1>. The <input> tag doesn't have an ID because we're only changing the size of the text box. Although doing this outside of a CSS file is "cheating" a little, it makes the code more readable and doesn't interfere with the JavaScript that depends on it.

To change the size of the text box, all you need to do is specify a character length with the size property. Let's make it 20 characters long (feel free to change this number to your preference):

<input type="text" name="searchterms" size="20">

Contrast these exceptions with the <p> and <div> tags on our example page. There are several <div> and <p> tags on the video search results page. If you were to redefine <div> in the CSS file--which is indeed possible--you'd have the same style across all of these tags, and that doesn't make for a very nice page design. Therefore you must assign a different ID or class to each instance of <div> and <p> where you want the style to be different, then define style properties in the CSS file. The difference between an ID and a class is frequency of use; IDs are only used once, whereas classes can be reused many times. An ID identifies a specific, unique element; a class identifies a class of elements with a common style. So if you use a particular style only once on a page, give its HTML tag an ID; if you will use it more than once, make it a class instead. There is no harm in using only classes, if you prefer.

So those plain-Jane HTML tags in the displayResults() function need to be assigned classes. Let's do that right now:

function displayResults()
{
    var outputhtml = "";

    for (var i=0; i < AOLVS.VideoSet.totalResultsReturned; i++)
    {
	outputhtml += "<div class='result_return'>";
	outputhtml += "<a href='" + AOLVS.VideoSet.Video[i].videoUrl + "'>";
	outputhtml += AOLVS.VideoSet.Video[i].title + "</a>";
	outputhtml += "<p class='result_description'>" +
	    AOLVS.VideoSet.Video[i].description + "</p>";
	outputhtml += "</div>";
    }
    outputhtml += (AOLVS.VideoSet.totalResultsReturned == 0) ? 
        "<div class='result_message'>No videos found.</div>" :
	"<div class='result_message'>(end of results)</div>";

    document.getElementById("results").innerHTML = outputhtml;
}

In the above example, the <div> and <p> tags have been assigned descriptive class names. Notice that while you would usually use double quotation marks for style definitions, this is in a JavaScript function that uses double quotes for other things, so you must use single quotes for the class declarations. You could do it the other way around if you wanted--single quotes for JavaScript, double for HTML, but doing it as shown above involves fewer changes to the JavaScript file.

The program's functionality has not changed at all, and at this point, neither has the page's style. All you've done is prepare the code for use with a style sheet. There is one more step in this process, and that is declaring the style sheet in the HTML file. Add this line in the <head> section of your page, above the <body> tag:

<link rel="stylesheet" type="text/css" href="video_search.css" />

The above line will load a file in the current working directory called video_search.css. If you want to name it something else, feel free, but make sure it has a .css extension. Wave goodbye to your HTML page and JavaScript file--you don't need to modify them anymore beyond this point. Now it's time to create a CSS file to assign style properties--positioning, sizing, graphics, coloring, and font--to the elements you want to change.

Creating a New Style Sheet

If you already have a CSS file for your site, skip to the next section.

A style sheet is a plain text file with tag, class, and ID definitions. At first it'll probably look confusing, but after you've made a few of your own definitions you'll see how easy and straightforward it is. So open up a text editor and start adding your tags, IDs, and classes to it, starting from the top and working your way down. Classes are defined with a dot notation, as in:

div.result_return

IDs are defined with the # symbol:

div#status

All of your CSS style properties need to be enclosed in a single set of braces--{ and }--in each definition, and instead of using the = sign to assign values to CSS properties, you use a colon. Otherwise, the layout of a CSS file is identical to the style tags you would put directly into an HTML file. Here's an example:

body {
    background: #FFFFFF;
}

p#introduction{
    font-weight: bold;
}

div#status {
    color: #B22222;
}

div#results {

}

div.result_return {
    border: solid thin;
}

p.result_description {
    font-style: italic;
}

div.result_message {
    text-align: center;
    font-weight: bold;
    font-style: italic;
    font-size: 3em;
}

As you can see, we're not doing much with style in this example--just adding a border to each result and bringing some distinction to the feedback messages. I've even left one of the styles completely blank, the reason being that I couldn't think of anything useful to add to it. But if I think of something later, I've got the placeholder there and can easily fill in the blanks. Most of the above CSS properties should be fairly self-explanatory, but there are dozens more options to choose from. This article will not go into further detail about style sheets and CSS properties, but if you would like to learn more, the W3Schools website provides an excellent CSS tutorial and a reference table.

Reusing Your Current Style Sheet

If your site has an existing style sheet, you can copy and paste most of the above style definitions into it without any trouble. The only one that you can't reuse is the body definition, since your existing CSS file probably already has one. You may want to adjust the values in the new style definitions to match the look and feel of your site; there should be no unusual barriers to accomplishing this.

Searching for Videos in Style

Once you've got everything in order, open your video search page with a web browser. You don't have to upload it to your server to see it in action; as long as your HTML, CSS, and JavaScript files are all in the same directory, you can run the page directly from your web browser without any loss of functionality. Try searching for a video and notice how much easier it is to read. Figure 2 shows an example search results page with CSS styles applied.

Figure 2. CSS-styled AOL Video Search web page

Conclusion

There's still a lot of work to be done if you want to make this page prettier, but just by adding a few style tags, you've dramatically increased the readability of your video search page, and therefore increased its usability as well.

References

"Building a Simple AOL Video Search API Application," by Paul Sobocinski, AOL Developer Network, January 16, 2007
W3Schools CSS2 tutorial
W3Schools CSS2 reference table
The CSS Zen Garden

» Submitted by Developer Network on April 9, 2007 - 12:20pm.

Love it!

Submitted by drbrown on April 22, 2008 - 8:47pm.

Bst Rgds,
Michael B.