Merge pull request #52 from r3c0d3x/patch-1

Fix small typos and add documentation for app.js

1 files changed, 81 insertions, 13 deletions

diff --git a/static/js/app.js b/static/js/app.js
index 0215599..3cdc6d7 100644
--- a/static/js/app.js
+++ b/static/js/app.js
@@ -20,8 +20,13 @@
  * SOFTWARE.
  */
 
-document.addEventListener('DOMContentLoaded', function () {
-
+document.addEventListener('DOMContentLoaded', function() {
+  /**
+   * Sets up the elements inside file upload rows.
+   * 
+   * @param {File} file
+   * @return {HTMLLIElement} row
+   */
   function addRow(file) {
     var row = document.createElement('li');
 
@@ -46,11 +51,18 @@ document.addEventListener('DOMContentLoaded', function () {
     return row;
   }
 
+  /**
+   * Updates the page while the file is being uploaded.
+   * 
+   * @param {ProgressEvent} evt
+   */
   function handleUploadProgress(evt) {
     var xhr = evt.target;
     var bar = xhr.bar;
     var percentIndicator = xhr.percent;
-
+    
+    /* If we have amounts of work done/left that we can calculate with 
+       (which, unless we're uploading dynamically resizing data, is always), calculate the percentage. */
     if (evt.lengthComputable) {
       var progressPercent = Math.floor((evt.loaded / evt.total) * 100);
       bar.setAttribute('value', progressPercent);
@@ -58,6 +70,13 @@ document.addEventListener('DOMContentLoaded', function () {
     }
   }
 
+  /**
+   * Complete the uploading process by checking the response status and, if the
+   * upload was successful, writing the URL(s) and creating the copy element(s)
+   * for the files.
+   * 
+   * @param {ProgressEvent} evt
+   */
   function handleUploadComplete(evt) {
     var xhr = evt.target;
     var bar = xhr.bar;
@@ -88,10 +107,13 @@ document.addEventListener('DOMContentLoaded', function () {
         copy.appendChild(glyph);
         url.appendChild(copy);
         copy.addEventListener("click", function(event) {
-          /*why create element?  text needs to be on screen to be selected
-            and thus copied.  only text we have on screen is the link without
-            the http[s]:// part.  so this creates an element with the full link
-            for a moment and then deletes. */
+          /* Why create an element?  The text needs to be on screen to be
+             selected and thus copied. The only text we have on-screen is the link
+             without the http[s]:// part. So, this creates an element with the
+             full link for a moment and then deletes it. 
+            
+             See the "Complex Example: Copy to clipboard without displaying
+             input" section at: https://stackoverflow.com/a/30810322 */
           var element = document.createElement('a');
           element.textContent = response.files[0].url;
           link.appendChild(element); 
@@ -106,7 +128,7 @@ document.addEventListener('DOMContentLoaded', function () {
         bar.innerHTML = 'Error: ' + response.description;
       }
     } else if (respStatus === 413) {
-      link.textContent = 'File Too big!';
+      link.textContent = 'File too big!';
       url.appendChild(link);
     } else {
       link.textContent = 'Server error!';
@@ -114,6 +136,12 @@ document.addEventListener('DOMContentLoaded', function () {
     }
   }
 
+  /**
+   * Updates the page while the file is being uploaded.
+   * 
+   * @param {File} file
+   * @param {HTMLLIElement} row
+   */
   function uploadFile(file, row) {
     var bar = row.querySelector('.file-progress');
     var percentIndicator = row.querySelector('.progress-percent');
@@ -134,20 +162,40 @@ document.addEventListener('DOMContentLoaded', function () {
     xhr.send(form);
   }
 
+  /**
+   * Prevents the browser for allowing the normal actions associated with an event.
+   * This is used by event handlers to allow custom functionality without
+   * having to worry about the other consequences of that action.
+   * 
+   * @param {Event} evt
+   */
   function stopDefaultEvent(evt) {
     evt.stopPropagation();
     evt.preventDefault();
   }
 
+  /**
+   * Adds 1 to the state and changes the text.
+   * 
+   * @param {Object} state
+   * @param {HTMLButtonElement} element
+   * @param {DragEvent} evt
+   */
   function handleDrag(state, element, evt) {
     stopDefaultEvent(evt);
     if (state.dragCount == 1) {
       element.textContent = 'Drop it here~';
     }
-
     state.dragCount += 1;
   }
 
+  /**
+   * Subtracts 1 from the state and changes the text back.
+   * 
+   * @param {Object} state
+   * @param {HTMLButtonElement} element
+   * @param {DragEvent} evt
+   */
   function handleDragAway(state, element, evt) {
     stopDefaultEvent(evt);
     state.dragCount -= 1;
@@ -156,6 +204,13 @@ document.addEventListener('DOMContentLoaded', function () {
     }
   }
 
+  /**
+   * Prepares files for uploading after being added via drag-drop.
+   * 
+   * @param {Object} state
+   * @param {HTMLButtonElement} element
+   * @param {DragEvent} evt
+   */
   function handleDragDrop(state, element, evt) {
     stopDefaultEvent(evt);
     handleDragAway(state, element, evt);
@@ -166,21 +221,36 @@ document.addEventListener('DOMContentLoaded', function () {
       uploadFile(file, row);
     }
   }
-
+  
+  /**
+   * Prepares the files to be uploaded when they're added to the <input> element.
+   * 
+   * @param {InputEvent} evt
+   */
   function uploadFiles(evt) {
     var len = evt.target.files.length;
+    // For each file, make a row, and upload the file.
     for (var i = 0; i < len; i++) {
       var file = evt.target.files[i];
       var row = addRow(file);
       uploadFile(file, row);
     }
   }
-
+  
+  /**
+   * Opens up a "Select files.." dialog window to allow users to select files to upload.
+   * 
+   * @param {HTMLInputElement} target
+   * @param {InputEvent} evt
+   */
   function selectFiles(target, evt) {
     stopDefaultEvent(evt);
     target.click();
   }
 
+  /* Set-up the event handlers for the <button>, <input> and the window itself
+     and also set the "js" class on selector "#upload-form", presumably to
+     allow custom styles for clients running javascript. */
   var state = { dragCount: 0 };
   var uploadButton = document.getElementById('upload-btn');
   window.addEventListener('dragenter', handleDrag.bind(this, state, uploadButton), false);
@@ -193,6 +263,4 @@ document.addEventListener('DOMContentLoaded', function () {
   uploadButton.addEventListener('click', selectFiles.bind(this, uploadInput));
   uploadButton.addEventListener('drop', handleDragDrop.bind(this, state, uploadButton), false);
   document.getElementById('upload-form').classList.add('js');
-
-  
 });