<![CDATA[*****************************************************************************
* Using AJAX with JavaScript, jQuery and JSON to graph data *
*****************************************************************************
+------------------+
| HTML / PHP files |
+------------------+
Location: /Canvas/html
Filename: top10.html
----------------------
Purpose: the launch page for the application
Features: 1) A section for an HTML5 Canvas with absolute positioning
2) Two other sections reserved for future use with the same
positioning. Intention would be to Ajax fetch previous and
next data, so that the three sections (all with canvas elemnts)
can be displayed or hidden to speed up the application.
3) The use of hidden <input> elements to conveniently store some
data for convenient access.
Filename: ScrapingTop40.html
------------------------------
Purpose: To display some relevant HTML from http://top40-charts.com/, which
was screen scraped to get data.
Notes: The HTML author of this site did not write the easiest HTML to
scrape, i.e., invalid HTML structures, limited to no use of id
attributes, etc. However the data was free. The other possible
choice was Billboard's site, but for free, you could only get the
top 3 songs, not the top 10.
Filename: generateJSON.php
----------------------------
Purpose: Read contents of the top40-charts site, grab the title and artist
of the top 10 pop songs for 19 weeks in a row, and output JSON data
Parameters: Querystring parameter for the date of the starting chart
Features: 1) If the querystring is not set, it will begin scraping with the
current chart, othewise it will start on the specified date.
2) Includes a PHP library to manipulate the HTML DOM. The
technique used is to load all HTML elements of a given type
e.g., $html->find("option") to place all <option>s into an
array or $html->find("a[onClick]"); to load anchor tags that
have an onClick attrbute similarly.
Filename: generatePrettyJSON.php
----------------------------------
Purpose: Display JSON in an easy to read format.
Features: 1) PHP require_once to include the generateJSON.php file above
2) Use of <pre> tags and the PHP print_r method to display formatted
JSON below the compact, unformatted version.
Filename: simple_html_dom.php
-------------------------------
Purpose: Provide a set of tools for HTML DOM manipulation, especially useful
for screen scraping.
Notes: External library.
Filename: documentation.php
-----------------------------
Purpose: Display this text file (README.txt) in a browser.
Features: 1) Use of CSS embedded styles to override the CSS stylesheet
2) PHP's file_get_contents function to grab this text
3) Use of CSS overflow to produce scrollbars
+---------------------------+
| JavaScript / jQuery files |
+---------------------------+
Location: /Canvas/js
Filename: song.js
-------------------
Purpose: Establish the JavaScript Song object and related functions
Features: 1) Use of JS constructor functions including instance methods
2) A loaded array of HTML colors (with official HTML color names)
which will be used to distinguish different #1 songs.
3) A randomizer to select a different color on each reload.
4) A "match color" function based on RGB values within a certain
range. A range is needed because when lines of a color are drawn
on an HTML canvas, aliasing is used to smooth the edges.
5) An object related to Song called SongMeta, which has its own
constructor with less parameters for when we do not yet know a
song's position in the Top 40. (No constructor overloading in
loosely typed JS.) Created for efficiency, because we don't
want to make dozens of Song objects for songs that never reach
the top 10. (If only we could have scraped Billboard top 10,
which features a useful "peak position" column!)
Filename: songList.js
-----------------------
Purpose: Establish the JavaSript SongList object that wil be sent to the
graphing functions.
Features: 1) An array of Songs
2) Typical instance methods like addSong, removeSong and getSong
which returns a Song based on its clor
Filename: canvas.js
---------------------
Purpose: Establish the JavaScript Canvas object to avoid namespace pollution
Features: 1) The packaging of many global variables related to a Canvas into
an object
2) Its constructor receives a jQuery object, so that attributes of
<canvas> can be utilized. Note that a jQuery object differs from
a JavaScipt object. The real JavaScript object is actually the
zeroth elment of a jQuery object.
Filename: listeners.js
------------------------
Purpose: Add listeners using jQuery to HTML elements to separate content
from code.
Features: 1) Combined use of mousedown and onclick listeners for Ajax calls.
Since the screen scraping takes time, we want to show a message
in a <span> tag that says please wait, and a classic Windows 7
style loading animated gif. All of this code cannot be placed in
the onclick, as JS will wait until all code is completed. Thus
the message to users doesn't appear fast enough. Since mousedown
occurs before onclick, we can take advantage of that to allow
mousedown to let the user know that the system is processing the
Ajax.
2) Mouseover listeners that will display a floating 'popup' window
when you hover in the canvas over a color that the system
recognizes as a Song color.
3) A function to calculate the actual week of the chart data such
that it can be added to the popup. This function is based on the
mathematics of creating the grid-like <canvas>.
4) Demonstration of nifty JS Date functions from a date library.
5) Onclick Easter eggs.
Filename: graph.js
--------------------
Purpose: Perform all the graphing on the canvas, some of which is the
result of receipt and parsing of the JSON data.
Features: 1) Creation of the Canvas object
2) A function to get the chart data by initiating the Ajax request
followed up with a callback to the function that needs to receive
the JSON data.
3) The callback function which parses the JSON into a JS structure
and uses te data in this structure to build Song objects, add
them to a SongList, and graph the #1 songs.
4) Multiple functions that calculate and process postioning of the
moue over the canvas.
Filename: Ajaxfunctions.js
----------------------------
Purpose: Provide helper functions for Ajax calls.
Note: Library downloaded from elvis.rowan.edu
Filename: date.js
-------------------
Purpose: Provide helper functions for working with JS dates
Note: Library downloaded from GitHub
+------------------+
| CSS files |
+------------------+
Location: /Canvas/css
Filename: pop.js
------------------
Purpose: Provide styling for the web pages of the application
Features: 1) Absolute positioning
2) Shadows and rounded corners
3) Google fonts
4) <span> tags that look and feel like buttons, including
a mouseover cursor of the hand
]]>
