From 9fcd82f172a16c7772df7f229532dc8db2c09c5b Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Sun, 16 Sep 2007 02:36:42 +0000
Subject: [PATCH] mujma: ENHANCEMENTS: Added comments. (merged from
 branches/gsoc)

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/cms/trunk@42067 467b73ca-7a2a-4603-9d3b-597d59a354a9
---
 javascript/CMSMain_upload.js          |  7 ++
 javascript/TinyMCEImageEnhancement.js | 56 +++++++++++++++-
 javascript/Upload.js                  | 92 ++++++++++++++++++++++++---
 3 files changed, 144 insertions(+), 11 deletions(-)

diff --git a/javascript/CMSMain_upload.js b/javascript/CMSMain_upload.js
index 26bfbc40..d0b2456d 100644
--- a/javascript/CMSMain_upload.js
+++ b/javascript/CMSMain_upload.js
@@ -1,3 +1,6 @@
+/**
+ * If one of methods is not commented look for comment in Upload.js 
+*/
 CMSMain_upload = Class.create();
 CMSMain_upload.prototype = {
     initialize: function() {
@@ -18,6 +21,10 @@ CMSMain_upload.prototype = {
             });
     },
     
+    /**
+     * Builds UI, called only when Upload object will be able to create flash uploader. 
+    */
+    
     extendForm: function() {
         if(this.iframe.contentDocument == undefined) this.iframe.contentDocument = document.frames[0].document;//IE HACK   
         element = this.iframe.contentDocument.getElementById('Form_UploadForm');
diff --git a/javascript/TinyMCEImageEnhancement.js b/javascript/TinyMCEImageEnhancement.js
index 15c7f1da..f7f8295d 100644
--- a/javascript/TinyMCEImageEnhancement.js
+++ b/javascript/TinyMCEImageEnhancement.js
@@ -1,3 +1,6 @@
+/**
+ * If one of methods is not commented look for comment in Upload.js.
+*/
 TinyMCEImageEnhancement = Class.create();
 TinyMCEImageEnhancement.prototype = {
     initialize: function() {
@@ -31,6 +34,10 @@ TinyMCEImageEnhancement.prototype = {
         Event.observe($('UploadFiles'),'click',this.onUpload.bind(this));
     },   
     
+    /**
+     * Method creates HTML element, only reason for this method is DRY. 
+    */
+    
     addElement: function(tag, className, parent, properties) {
         var e = document.createElement(tag);
         Element.addClassName(e,className);
@@ -41,8 +48,6 @@ TinyMCEImageEnhancement.prototype = {
         
     onUpload: function(event) {
         Event.stop(event);
-        
-        
         if(!this.processInProgress) {
 	        if(this.getParentID() != 'root') {
 	            this.upload.browse();
@@ -52,6 +57,10 @@ TinyMCEImageEnhancement.prototype = {
 	    }
     },
     
+    /**
+     * Called when user clicks "add folder" anchor. 
+    */
+    
     onAddFolder: function(event) {
         Event.stop(event);
         Element.hide('AddFolder');
@@ -59,6 +68,10 @@ TinyMCEImageEnhancement.prototype = {
         this.applyIE6Hack();
     },
     
+    /**
+     * Called when user clicks "ok" anchor/ adds folder with given name. 
+    */
+    
     onFolderOk: function(event) {
         Event.stop(event);
         var folderName = $('NewFolderName').value;
@@ -75,6 +88,10 @@ TinyMCEImageEnhancement.prototype = {
         
     },
     
+    /**
+     * Method retrieves folder id and sends request which changes folder name. 
+    */
+    
     onFolderGetSuccess: function(transport) {
         var t1 = transport.responseText.indexOf('TreeNode(');
         var t2 = transport.responseText.indexOf(',');
@@ -99,6 +116,10 @@ TinyMCEImageEnhancement.prototype = {
         new Ajax.Request('admin/assets/index/' + this.getParentID() + '?executeForm=EditForm', options);
     },
     
+    /**
+     * When folder name has been changed we need to refresh folder list and return to initial state of UI. 
+    */
+    
     onFolderAddSuccess: function(transport) {
         statusMessage('Creating new folder');
         document.getElementsBySelector("div.TreeDropdownField.single")[2].itemTree = null;
@@ -108,6 +129,10 @@ TinyMCEImageEnhancement.prototype = {
         this.removeIE6Hack();                               
     },
     
+    /**
+     * If user doesn't want to add folder return to default UI. 
+    */
+    
     onFolderCancel: function(event) {
         Event.stop(event);
         $('NewFolderName').value = '';
@@ -116,7 +141,9 @@ TinyMCEImageEnhancement.prototype = {
         this.removeIE6Hack();
     },
     
-    
+    /**
+     * Called on window.onload
+    */
     
     onWindowLoad: function() {
         if($('FolderID') != null) {
@@ -155,6 +182,12 @@ TinyMCEImageEnhancement.prototype = {
         }
     },
     
+    /**
+     * Iterates over all uploaded images and add them to TinyMCE editor
+     *
+     * @param transport object
+    */
+    
     insertImages: function(transport) {
         //HACK FOR STRANGE ERROR OCCURING UNDER SAFARI
         if(transport.responseText == '') {
@@ -172,6 +205,13 @@ TinyMCEImageEnhancement.prototype = {
         this.processInProgress = false;
     },
     
+    /**
+     * Adds particular image to TinyMCE. Most of code has been copied from tiny_mce_improvements.js / ImageThumbnail.onclick
+     * Sorry for not following DRY, I didn't want to break smth in tiny_mce_improvements.
+     * 
+     *  @param target object
+    */
+    
     addToTinyMCE: function(target) {
 		var formObj = $('Form_EditorToolbarImageForm');
         var altText = formObj.elements.AltText.value;
@@ -192,6 +232,11 @@ TinyMCEImageEnhancement.prototype = {
         TinyMCE_AdvancedTheme._insertImage(relativeHref, altText, 0, null, null, destWidth, destHeight, null, null, cssClass);
     },
     
+    /**
+     * Under IE6 when we click on "add folder" anchor, rest of anchors loose their correct position
+     *
+    */
+    
     applyIE6Hack: function() {
         if(BrowserDetect.browser == 'Explorer') {
 	        elements = [$('FolderOk'),$('FolderCancel'),$('UploadFiles'),$('PipeSeparator')];
@@ -211,6 +256,11 @@ TinyMCEImageEnhancement.prototype = {
 	    }
     },
     
+    /**
+     * Returns id of upload folder.
+     *
+    */
+    
     getParentID: function() {
         return  $('Form_EditorToolbarImageForm_FolderID').value == '' ? 'root' : $('Form_EditorToolbarImageForm_FolderID').value;
     }
diff --git a/javascript/Upload.js b/javascript/Upload.js
index 6da2a8d7..7d77772a 100644
--- a/javascript/Upload.js
+++ b/javascript/Upload.js
@@ -1,5 +1,11 @@
 Upload = Class.create();
 Upload.prototype = {
+    
+    /**
+     * Sets configuration data provided from user if smth is missing sets default value.
+     *
+     * @param params object contains all configuration data for upload.
+    */
     initialize: function(params) {
         this.filesUploaded = 0;
         this.filesToUpload = 0;
@@ -20,14 +26,18 @@ Upload.prototype = {
         this.onLoad();
     },
     
+    /**
+     * Creates SWFUpload object for uploading files.  
+     * 
+    */
     onLoad: function() {
         path = this.getBasePath();
-        sessId = this.getSessionId();
+        sessId = this.getSessionId();//Because flash doesn't send proper cookies, we need to set session id in URL. 
         this.swfu = new SWFUpload({
                 upload_target_url: path + '/assets/index/root?executeForm=UploadForm&PHPSESSID=' + sessId,   // Relative to the SWF file
                 file_post_name: 'Files',
-                file_size_limit : this.fileSizeLimit,  // 30 MB
-                file_types : this.fileTypes, // or you could use something like: '*.doc;*.wpd;*.pdf',
+                file_size_limit : this.fileSizeLimit,
+                file_types : this.fileTypes,
                 file_types_description : this.fileTypesDescription,
                 file_upload_limit : this.fileUploadLimit,
                 begin_upload_on_queue : this.beginUploadOnQueue,
@@ -42,23 +52,28 @@ Upload.prototype = {
                 file_validation_handler : Prototype.emptyFunction,
                 file_cancelled_handler: Prototype.emptyFunction,
                 
-                ui_container_id: 'abc1',
-                degraded_container_id: 'abc2', 
-                
-                
- 
                 flash_url : 'jsparty/SWFUpload/SWFUpload.swf',    // Relative to this file
                 ui_function: this.buildUI.bind(this),
                 debug: false
             });
     },
     
+    /**
+     * Retrieves base path from URL.
+     * TODO: Use base tag. 
+    */
+    
     getBasePath: function() {
         var path = 'http://' + window.location.host + window.location.pathname;
         if(path[path.length-1] == '/') path = path.substring(0,path.length-1);
         return path;
     },
     
+    /**
+     * Retrieves sessionId from cookie. 
+     * 
+    */
+
     getSessionId: function() {
         var start = document.cookie.indexOf('PHPSESSID')+10;
         var end = document.cookie.indexOf(';',start);
@@ -66,16 +81,35 @@ Upload.prototype = {
         return document.cookie.substring(start,end);
     },
     
+    /**
+     * Calls method defined by user, method should create user interface. 
+     * 
+    */
+    
     buildUI: function() {
         this.customBuildUI();	        
     },
     
+    /**
+     * Called when new file is added to the queue
+     * 
+     * @param file object 
+     * @param queueLength int
+    */
+    
     uploadFileQueuedCallback: function(file,queueLength) {
         this.filesToUpload++;
         this.fileQueued(file, queueLength);
         this.addFileParam(file);
     },
     
+    /**
+     * Called when uploading of particular file has finished
+     * 
+     * @param file object 
+     * @param servedData string
+    */
+   
     uploadFileCompleteCallback: function(file,serverData) {
         this.filesUploaded++;
         var toEval = serverData.substr(serverData.indexOf('<script'));
@@ -85,11 +119,22 @@ Upload.prototype = {
         this.fileComplete(file, serverData);
     },
     
+    /**
+     * Called during uploading file. 
+     *
+     * @param file object 
+     * @param bytes_complete int
+    */
+    
     uploadFileProgressCallback: function(file, bytes_complete) {
         this.uploadInProgress = true;
         this.fileProgress(file, bytes_complete);
     },
     
+    /**
+     * Called when whole queue has been uploaded or cancelled. 
+    */
+    
     uploadQueueCompleteCallback: function() {
         this.queueComplete();
         this.uploadInProgress = false;
@@ -97,6 +142,13 @@ Upload.prototype = {
         this.filesToUpload = 0;
     },
     
+    /**
+     * Called on error.
+     * @param error_code int
+     * @param file object
+     * @param message string
+    */
+
     uploadErrorCallback: function(error_code, file, message) {
         this.swfu.cancelQueue();
         switch(error_code) {
@@ -128,6 +180,13 @@ Upload.prototype = {
                 alert('You have encountered an error. File hasn\'t has been uploaded. Please hit the "Refresh" button in your web browser');
         }
     },
+    
+    /**
+     * Because we are on top of standard upload we need to add some POST vars that 
+     * normally are being sent as part of form.
+     *
+     * @param file object
+    */
      
     addFileParam: function(file) {
         this.swfu.addFileParam(file.id,'ID',this.folderID);
@@ -136,19 +195,36 @@ Upload.prototype = {
         this.swfu.addFileParam(file.id,'MAX_FILE_SIZE','31457280');
     },
     
+    /**
+     * Starts file explorer. 
+     *
+    */
+    
     browse: function() {
         this.swfu.browse();
     },
     
+    /**
+     *  Starts upload
+     * 
+    */
+    
     startUpload: function() {
         this.swfu.startUpload();
     },
     
+    /**
+     * Cancels uploading of file. 
+    */
+    
     cancelUpload: function(fileId) {
         this.filesToUpload--;
         this.swfu.cancelUpload(fileId);
     },
     
+    /*
+     * Getters and setters.
+    */   
     setFolderID: function(id) {
         this.folderID = id;
     },