University of Washington, CSE 190 M, Spring 2008
Homework Assignment 5: Baby Names Redux
Part A (unfinished milestone) due Wednesday, May 7, 2008, 11:00pm electronically
Part B (complete program) due Tuesday, May 13, 2008, 11:00pm electronically

This assignment tests your understanding of fetching data from files and web applications using Ajax (Asynchronous JavaScript and XML). You must match in appearance and behavior the following web page:

---

• 

---

Every 10 years, the Social Security Administration provides data about the 1000 most popular boy and girl names for children born in the US, at http://www.ssa.gov/OACT/babynames/. Your task for this assignment is to write the JavaScript code for a web page to display the baby names, popularity rankings, and meanings.

You do not need to submit any .html or .css file. We will provide you with the HTML (names.html) and CSS (names_style.css) code to use. Turn in the following file:

• names_script.js, the JavaScript code for your web page

This program uses Ajax to fetch data from the Webster server. Please note that Ajax can only connect to a web server from a page located on that same server. This means that you must upload your page to Webster and test it by viewing it on Webster. If you try to fetch data from Webster while viewing the page from your local hard drive, the request will fail with an exception.

Data:

Your program will read its data from a web application located at the following URL:

https://webster.cs.washington.edu/babynames.php

This web application accepts three different types of queries, specified using a query string with a parameter named type. Each type of query returns text or XML as its output. (You can test queries by typing in their URLs in your web browser's address bar and seeing the result.) If you submit an invalid query, such as one missing a necessary parameter, your request will return a status of 400 rather than the default 200. If you submit a query for an unknown name, your request will return a status of 404.

1. The first type of query is list, which returns plain text containing all baby names on file, with each on its own line. The following query would return the results below (shortened by ...):

   https://webster.cs.washington.edu/babynames.php?type=list
   

   Aaliyah
   Aaron
   Abagail
   ...
   

2. The second type of query is rank, which returns an XML document about that baby name's popularity rank in each decade. The rank query requires a second parameter named name.

   The overall XML document tag is called <baby> that contains an attribute named name that represents the baby's first name. Inside each <baby> tag are many <rank> tags, one for each decade of survey data. Each <rank> tag contains an attribute named year that represents the relevant year of data. The text inside the <rank> tag is that baby name's popularity in that decade.

   The data has 11 rankings per name, one per decade from 1900 to 2000, from 1 (popular) to 999 (unpopular). A rank of 0 means the name was not in the top 1000. The following query would return the results below:

   https://webster.cs.washington.edu/babynames.php?type=rank&name=morgan
   

   <baby name="Morgan">
       <rank year="1900">430</rank>
       <rank year="1910">477</rank>
       <rank year="1920">526</rank>
       ...
       <rank year="2000">25</rank>
   </baby>
   

   Though the provided web service always returns data starting at 1900 and running until 2000, you should not rely on the starting year being 1900. Your code should examine the XML to determine this.

3. The third type of query is meaning, which returns text about that baby name's origin and meaning. The meaning query also requires a second parameter named name. For example, the following query would return the results below:

   https://webster.cs.washington.edu/babynames.php?type=meaning&name=martin
   

   MARTIN m English, French, German, Scandinavian, Russian, Romanian, Czech, Slovak, Slovene, Hungarian, Bulgarian From the Roman name Martinus, which was derived from Martis, the genitive case of the name of Roman god MARS.

   All names returned by the list query have ranking data, but not all will have meaning data. In such a case, do not display any text in the Origin/meaning area (and clear any text that used to be there).

You may assume that all XML and text data sent to your program is valid and does not contain any errors. You may also assume that the web app is reachable at the time your code runs.

Appearance and Behavior:

The HTML page given to you shows a main heading followed by a selection box (a select element with id of babyselect). When the page first loads, the box is empty and disabled. But in the background the page should fetch the name data from the web application as described in this document, fill itself with an option for each name, and enable itself. You can enable an onscreen element by setting the disabled property of its DOM element object to false.

There is also a large 670x250px shaded bar graph section in the center of the page that is initially blank. If a name is selected from the selection box, this shaded section is filled with bars representing that name's popularity for each year in the data. Any data from a previous name should be cleared from the graph. There is no specified behavior if the user selects the "Select a name..." option in the list.

The bars are positioned absolutely with respect to the overall shaded graph section. Each ranking bar's width is 50px; its height is one fourth as many px as the "inverse ranking" for that decade. The inverse ranking is defined to be 1000 minus the ranking. For example, the ranking of 880 leads to a bar with a height of 30 (one fourth of 1000 - 880, or 120). Their x-coordinates are such that the first bar's left edge is 10px from the left edge of the graph section, and there are 10px horizontal space between adjacent bars. For example, the first bar's left corner is at x=10, the second is at x=70, the third at x=130, and so on. All ranking bars' y positions are such that their bottoms exactly touch the bottom of the shaded graph area.

Within each ranking bar appears the ranking number for that name in that decade. The numbers appear in an 18pt sans-serif font, top-aligned and horizontally centered within the bars. Some less popular rankings (around 900 and up) have numbers that drop below the graph region's black border; this is expected behavior for non-CSE-majors.

The provided CSS file contains a class named ranking that contains all necessary properties for these bars, except the x/y positions and height, which differ for each bar. Create a DOM element for each bar and assign this class to it. The element itself is the bar, and its inner text content is the ranking.

Above each ranking bar, at the top of the shaded graph region, are labels representing the corresponding years. These are positioned vertically 1.5em from the top of the shaded region and centered horizontally within the ranking bar's width. The provided CSS file contains a class named year that contains all necessary properties for these elements other than their x positions, which differ for each year label.

Underneath the ranking bars appears a paragraph of text explaining the meaning of the name shown. When a new name is chosen, that name's meaning information is loaded asynchronously and appears underneath the graph. Inject the relevant text into the paragraph with id of meaning.

All other style elements on the page are subject to the preference of the web browser. The screenshots in this document were taken on Windows XP in Firefox 2.0, which may differ from your system.

For CSE Majors:

CSE majors must do at least two (2) of the following additional features. Please choose which features you want to implement and place a comment at the top of your JS file stating which features you have implemented. If you have another feature you'd like to do that is not on the following list, please ask the instructor and we may allow it to substitute for one of the features below.

• better loading feedback: The page as currently described does not give the user very good feedback while it is loading its data, both initially (loading the list of names) and subsequently (when a name is chosen and that name's XML data must be fetched). Consider adding code to display a "Loading" message, loading styles on the page (such as "graying out" items or putting placeholder text into them), or even an hourglass mouse cursor (achieved by using the CSS cursor property).

  To help you test this functionality, the babynames.php service can accept an optional query parameter named delay, whose value should be an integer representing a number of seconds of delay that the server should wait before sending its response. For example, requesting the following URL would retrieve the rankings for the name "Stefanie" after a delay of 10 seconds:

  https://webster.cs.washington.edu/babynames.php?type=rank&name=stefanie&delay=10
  

• ability to compare multiple names: By default the page displays data about one name at a time. Consider adding code so that if a second name is chosen, the previous data remains, with the new data superimposed in a different color. This provides a way to compare the relative popularity of the two names over time. You should add some sort of "Clear" button so that the user can erase previously shown names.
• error messages: If something goes wrong with any Ajax request, show a descriptive error message about what went wrong. Do this by listening to the onFailure message in the Ajax.Request object as described in the slides.
• display low rankings better: The default implementation will show numbers in the 950-1000 range at an awkward position, hanging downward below the bottom of the overall graph display area. Write code to ensure that no name's ranking hangs below the bottom of this area.
• auto-complete babies' names: Use the DOM to remove the select box from the page and replace it with an input text box where the user can type a name. As the user types a partial name, use Scriptaculous to display any names in the data set that contain or start with the partial text. The program should fetch the rank/meaning data for the name when the user selects a name from the auto-complete list and/or clicks a Search button you inject into the page.
• Other: If you have an idea for a creative addition to this program, please ask us and we may approve it for credit.

Please note that you must make any additional features without modifying the XHTML or CSS files directly; each must be done entirely through JavaScript code. Regardless of how many of these additions you choose to implement, your main program behavior and appearance should still work as specified. CSE non-majors may also choose to implement these features, but they will receive no bonus for doing so. Such features in a non-major's program will be ignored for grading so long as they do not break any existing core functionality.

Implementation and Grading:

We suggest the following development strategy for this assignment:

• Use Ajax to fetch and displays all babies' names in the page's top select box.
• Display a baby's name's meaning in the bottom meaning area when a name is selected in the top select box.
• Grab the popularity rankings for a name when it is selected and display each one in some simple way, such as by alerting them.
• Display the rankings properly using the colored bars.

Submit your assignment online from the turnin area of the course web site. For reference, our solution has 84 lines of JavaScript.

Fetch the necessary data for the program using Ajax. We strongly suggest using Prototype's Ajax.Request and Ajax.Updater objects to do this rather than the raw XMLHttpRequest object, but either approach is acceptable if the code is not redundant. You should process XML data by examining the request's XML tree using the XML DOM.

Your JavaScript code should follow reasonable stylistic guidelines similar to those you would follow on a CSE 14x programming assignment. In particular, you should pass the JSLint validator, minimize the number of global variables, utilize parameters and return values properly, correctly utilize the XHTML DOM objects, correctly use indentation and spacing, and place a comment header at the top of your JavaScript file and atop every function explaining that function's behavior. You should only use material that has been discussed during the first five weeks of the course, unless given explicit permission from the instructor.

Two aspects of your JavaScript style deserve particular emphasis. You should minimize redundant code. You should also exercise good procedural decomposition, breaking down lengthy operations into multiple functions, including use of parameters and returns over global variables whenever possible.

Part of your grade will also come from successfully uploading your files to the Webster web server at the following URL:

• https://webster.cs.washington.edu/your_uw_netid/hw5/names.html

Please do not place a solution to this assignment online on a publicly accessible (un-passworded) web site.

Except where otherwise noted, this document's contents are © Copyright 2008 Marty Stepp / Jessica Miller and licensed under Creative Commons Attribution 2.5 License.