Thoroughly comment code

pablobm · pablobm · commit 6aff57b42014 · 2012-01-08T13:50:55.000+01:00
diff --git a/README.md b/README.md
@@ -8,4 +8,8 @@ To run it, do:
 
 And the application should be accessible at `http://localhost:9292`.
 
+# What to look at?
+
+The important bit is the client code, found at `/public/index.html`
+
 If you want to know more, have a look at our [blog post covering HTML5 file uploads](http://blog.new-bamboo.co.uk/2010/7/30/html5-powered-ajax-file-uploads)
diff --git a/public/index.html b/public/index.html
@@ -6,50 +6,83 @@
 </head>
 <body>
 
+<!--
+  By default, we assume Ajax uploads are not supported.
+  Later we'll detect support and change this message if found.
+-->
 <p id="support-notice">Your browser does not support Ajax uploads :-(<br/>The form will be submitted as normal.</p>
 
+<!-- The form starts -->
 <form action="/" method="post" enctype="multipart/form-data" id="form-id">
-  <p><input id="file-id" type="file" name="our-file" /> <input type="button" value="Upload" id="upload-button-id" disabled="disabled" /></p>
+
+  <!-- The file to upload -->
+  <p><input id="file-id" type="file" name="our-file" />
+
+  <!--
+    Also by default, we disable the upload button.
+    If Ajax uploads are supported we'll enable it.
+  -->
+  <input type="button" value="Upload" id="upload-button-id" disabled="disabled" /></p>
+
+  <!-- A different field, just for the sake of the example -->
   <p><label>Some other field: <input name="other-field" type="text" id="other-field-id" /></label></p>
+
+  <!-- And finally a submit button -->
   <p><input type="submit" value="Submit" /></p>
+
   <script>
+// Function that will allow us to know if Ajax uploads are supported
 function supportAjaxUploadWithProgress() {
   return supportFileAPI() && supportAjaxUploadProgressEvents() && supportFormData();
 
+  // Is the File API supported?
   function supportFileAPI() {
     var fi = document.createElement('INPUT');
     fi.type = 'file';
     return 'files' in fi;
   };
 
+  // Are progress events supported?
   function supportAjaxUploadProgressEvents() {
     var xhr = new XMLHttpRequest();
     return !! (xhr && ('upload' in xhr) && ('onprogress' in xhr.upload));
   };
 
+  // Is FormData supported?
   function supportFormData() {
     return !! window.FormData;
   }
 }
 
+// Actually confirm support
 if (supportAjaxUploadWithProgress()) {
+  // Ajax uploads are supported!
+  // Change the support message and enable the upload button
   var notice = document.getElementById('support-notice');
   var uploadBtn = document.getElementById('upload-button-id');
   notice.innerHTML = "Your browser supports HTML uploads. Go try me! :-)";
   uploadBtn.removeAttribute('disabled');
 
+  // Init the Ajax form submission
   initFullFormAjaxUpload();
+
+  // Init the single-field file upload
   initFileOnlyAjaxUpload();
 }
 
 function initFullFormAjaxUpload() {
   var form = document.getElementById('form-id');
   form.onsubmit = function() {
+    // FormData receives the whole form
     var formData = new FormData(form);
+
+    // We send the data where the form wanted
     var action = form.getAttribute('action');
 
+    // Code common to both variants
     sendXHRequest(formData, action);
 
+    // Avoid normal form submission
     return false;
   }
 }
@@ -58,43 +91,60 @@
   var uploadBtn = document.getElementById('upload-button-id');
   uploadBtn.onclick = function (evt) {
     var formData = new FormData();
+
+    // Since this is the file only, we send it to a specific location
     var action = '/upload';
+
+    // FormData only has the file
     var fileInput = document.getElementById('file-id');
     var file = fileInput.files[0];
     formData.append('our-file', file);
 
+    // Code common to both variants
     sendXHRequest(formData, action);
-
-    return false;
   }
 }
 
+// Once the FormData instance is ready and we know
+// where to send the data, the code is the same
+// for both variants of this technique
 function sendXHRequest(formData, uri) {
+  // Get an XMLHttpRequest instance
   var xhr = new XMLHttpRequest();
+
+  // Set up events
   xhr.upload.addEventListener('loadstart', onloadstartHandler, false);
   xhr.upload.addEventListener('progress', onprogressHandler, false);
   xhr.upload.addEventListener('load', onloadHandler, false);
   xhr.addEventListener('readystatechange', onreadystatechangeHandler, false);
+
+  // Set up request
   xhr.open('POST', uri, true);
+
+  // Fire!
   xhr.send(formData);
 }
 
+// Handle the start of the transmission
 function onloadstartHandler(evt) {
   var div = document.getElementById('upload-status');
   div.innerHTML = 'Upload started!';
 }
 
+// Handle the end of the transmission
 function onloadHandler(evt) {
   var div = document.getElementById('upload-status');
   div.innerHTML = 'Upload successful!';
 }
 
+// Handle the progress
 function onprogressHandler(evt) {
   var div = document.getElementById('progress');
   var percent = evt.loaded/evt.total*100;
   div.innerHTML = 'Progress: ' + percent + '%';
 }
-  
+
+// Handle the response from the server
 function onreadystatechangeHandler(evt) {
   var status = null;
 
@@ -111,9 +161,12 @@
   }
 }
   </script>
+
+  <!-- Placeholders for messages set by event handlers -->
   <p id="upload-status"></p>
   <p id="progress"></p>
   <pre id="result"></pre>
+
 </form>
 </body>
 </html>
