Bugfix and documentation.

- Fixed a bug in ts_api:list_timelines/2 and ts_api:list_entries/3, which
  respond only to GET requests but were looking for POST data.
- Added documentation for ts.js.

www/js/ts.js

@@ -1,121 +1,179 @@
+var user = [];
+var timelines = [];
+var activeTimeline = [];
+var entries = [];
+
+var lastEntryBar;
+
+/* Setup after the document is ready for manipulation. */
 $(document).ready(function(){
 
+    lastEntryBar = $("#last-entry");
+
+    // wire the login dialog using jQuery UI
     $("#login-dialog").dialog({
         autoOpen: false,
         height: 300,
         width: 300,
         modal: true,
-        buttons: {
-            Login: function(){login()}
-        }
+        buttons: { Login: function(){login()} }
     });
 
+    // try to load user information for an authenticated user
     $.ajax({
         url: "/ts_api/users/",
         type: "GET",
+
         error: function(jqXHR, textStatus, error) {
+            // assume there is no authenticated user, show login dialog
             $("#login-dialog").dialog("open"); },
+
         success: function(data, textStatus, jqXHR) {
+            // load the user information
             loadUser(data.user.username); }});
 
 })
 
-var user = []
-var timelines = []
-var activeTimeline = []
-
+/* Read the user's credentials from the login form and perform
+ *  an AJAX request to the API to set the session cookie.  */
 function login() {
+    // lookup the login dialog elements
     var name = $("#login-name");
     var pwd = $("#login-password");
 
+    // call the API via AJAX
     $.ajax({
         url: "/ts_api/login",
         processData: false,
         data: JSON.stringify({username: name.val(), password: pwd.val()}),
         type: "POST",
+
         error: function(jqXHR, textStatus, error) {
+            // assuming bad credentials (possible server error or bad request,
+            // we should check that, FIXME
             var tips = $(".validate-tips");
             tips.text("Incorrect username/password combination.");
             tips.addClass("ui-state-error");
             tips.slideDown();
         },
+
         success: function(data, textStatus, jqXHR) {
+            // load the user information and hide the login dialog
             loadUser(name.val());
             $("#login-dialog").dialog("close");
         }});
 }
 
+/* End the current user session and expire any session credentials we
+ * have aquired.  */
 function logout(event) {
     alert("TODO: log user out via AJAX.");
+    // TODO: wipe username, timeline, entry variables and displays
     event.preventDefault();
 }
 
+/* Load and display the user's information and timelines.  */
 function loadUser(username) {
+
+    // call the user_summary API function
     $.ajax({
         url: "/ts_api/app/user_summary/" + username,
         type: "GET",
+
         success: function(data, textStatus, jqXHR) {
+            // set the user variable
             user = data.user;
+
+            // set the timelines variable
             timelines = data.timelines;
+
+            // update the user id display
             $("#fullname").text(user.name);
             $("#username").text("- " + user.username);
 
+            // pre-populate the editable user-info fields
             // TODO: not working
             $("#fullname-input").text(user.name);
             $("#email-input").text(user.email);
 
+            // set the active timeline to the first in the list
+            // TODO: implement a mechanism to remember the last used timeline
+            // on the server side and respond to that here.
             activeTimeline = timelines[0];
 
+            // update the timeline display
             $("#timeline-name").text(activeTimeline.timeline_id + " |");
             $("#timeline-desc").text(activeTimeline.description);
 
-            loadTimeline(user, activeTimeline)
+            // TODO: populate the drop-down list for the available timeline
+            // choices
+
+            // load the entries for this timeline
+            loadEntries(user, activeTimeline)
         },
+
         error: function(jqXHR, textStatus, error) {
+            // TODO
             alert("TODO: handle error for user load.")
+            alert(jqXHR.responseText)
         }
     });
 }
 
-function loadTimeline(user, timeline) {
+/* Read the first 50 entries for a timeline.  */
+function loadEntries(user, timeline) {
+
+    // call the API list_entries function via AJAX
     $.ajax({
         url: "/ts_api/entries/" + user.username + "/" + timeline.timeline_id,
         type: "GET",
+
         success: function(data, textStatus, jqXHR) {
+            entries = data.entries;
             
+            // push the entries onto the page
+            displayEntries(entries)
         }
     });
 }
 
+/* Show/hide the editable user-info panel. */
 function toggleUserInfo(event) {
     $("#user-info").slideToggle("slow");
     event.preventDefault();
 }
 
+/* Show/hide the password change controls. */
 function showChangePwd(event) { $("#change-pwd").slideToggle("slow"); }
 
+/* Update the user information based on the editable user-info panel. */
 function updateUser(event) {
     alert("TODO: update user via AJAX.");
     event.preventDefault();
 }
 
+/* Show/hide the editable timeline-info panel. */
 function toggleTimelineInfo(event) {
     $("#timeline-info").slideToggle("slow");
     event.preventDefault();
 }
 
+/* Show the change timeline menu. */
 function showTimelineMenu(event) {
     alert("TODO: show other timelines via a popup menu");
     event.preventDefault();
 }
 
+/* Update the timeline details based on the editable timeline-info panel. */
 function updateTimeline(event) {
     alert("TODO: update timeline via AJAX.");
     event.preventDefault();
 }
 
+/* Show/hide the add notes panel. */
 function showNewNotes(event) { $("#add-notes").slideToggle("slow"); }
 
+/* Create a new entry based on the user's input in the new-entry panel. */
 function newEntry(event) {
     alert("TODO: create entry vi AJAX");
     event.preventDefault();