Changeset 30244

Timestamp:

11/05/2014 07:36:27 PM (11 years ago)

Author:

wonderboymusic

Message:

Improve wp.Uploader documentation.

Props ericlewis.
See #30260.

Location:

trunk/src

Files:

• wp-admin/async-upload.php (modified) (1 diff)
• wp-includes/js/plupload/wp-plupload.js (modified) (17 diffs)

trunk/src/wp-admin/async-upload.php

@@ -1 +1 @@
 <?php
 /**
- * Accepts file uploads from swfupload or other asynchronous upload methods.
+ * Server-side file upload handler from wp-plupload, swfupload or other asynchronous upload methods.
  *
  * @package WordPress

trunk/src/wp-includes/js/plupload/wp-plupload.js

@@ -11 +11 @@
 
     /**
-     * An object that helps create a WordPress uploader using plupload.
+     * A WordPress uploader.
      *
-     * @param options - object - The options passed to the new plupload instance.
-     *    Accepts the following parameters:
-     *    - container - The id of uploader container.
-     *    - browser   - The id of button to trigger the file select.
-     *    - dropzone  - The id of file drop target.
-     *    - plupload  - An object of parameters to pass to the plupload instance.
-     *    - params    - An object of parameters to pass to $_POST when uploading the file.
-     *                  Extends this.plupload.multipart_params under the hood.
+     * The Plupload library provides cross-browser uploader UI integration.
+     * This object bridges the Plupload API to integrate uploads into the
+     * WordPress back-end and the WordPress media experience.
      *
-     * @param attributes - object - Attributes and methods for this specific instance.
+     * @param {object} options           The options passed to the new plupload instance.
+     * @param {object} options.container The id of uploader container.
+     * @param {object} options.browser   The id of button to trigger the file select.
+     * @param {object} options.dropzone  The id of file drop target.
+     * @param {object} options.plupload  An object of parameters to pass to the plupload instance.
+     * @param {object} options.params    An object of parameters to pass to $_POST when uploading the file.
+     *                                   Extends this.plupload.multipart_params under the hood.
      */
     Uploader = function( options ) {
@@ -44 +45 @@
         }
 
+        // Arguments to send to pluplad.Uploader().
         // Use deep extend to ensure that multipart_params and other objects are cloned.
         this.plupload = $.extend( true, { multipart_params: {} }, Uploader.defaults );
         this.container = document.body; // Set default container.
 
-        // Extend the instance with options
+        // Extend the instance with options.
         //
         // Use deep extend to allow options.plupload to override individual
@@ -61 +63 @@
         }
 
-        // Ensure all elements are jQuery elements and have id attributes
-        // Then set the proper plupload arguments to the ids.
+        // Ensure all elements are jQuery elements and have id attributes,
+        // then set the proper plupload arguments to the ids.
         for ( key in elements ) {
             if ( ! this[ key ] ) {
@@ -95 +97 @@
         }
 
+        // Initialize the plupload instance.
         this.uploader = new plupload.Uploader( this.plupload );
         delete this.plupload;
@@ -102 +105 @@
         delete this.params;
 
+        /**
+         * Custom error callback.
+         *
+         * Add a new error to the errors collection, so other modules can track
+         * and display errors. @see wp.Uploader.errors.
+         *
+         * @param  {string}        message
+         * @param  {object}        data
+         * @param  {plupload.File} file     File that was uploaded.
+         */
         error = function( message, data, file ) {
             if ( file.attachment ) {
@@ -116 +129 @@
         };
 
+        /**
+         * After the Uploader has been initialized, initialize some behaviors for the dropzone.
+         *
+         * @param {plupload.Uploader} uploader Uploader instance.
+         */
         this.uploader.bind( 'init', function( uploader ) {
             var timer, active, dragdrop,
@@ -133 +151 @@
             }
 
-            // 'dragenter' doesn't fire correctly,
-            // simulate it with a limited 'dragover'
+            // 'dragenter' doesn't fire correctly, simulate it with a limited 'dragover'.
             dropzone.bind( 'dragover.wp-uploader', function() {
                 if ( timer ) {
@@ -153 +170 @@
                 // dropzone are repositioned.
                 //
-                // See https://core.trac.wordpress.org/ticket/21705
+                // @see https://core.trac.wordpress.org/ticket/21705
                 timer = setTimeout( function() {
                     active = false;
@@ -159 +176 @@
                 }, 0 );
             });
-            
+
             self.ready = true;
             $(self).trigger( 'uploader:ready' );
@@ -174 +191 @@
         }
 
+        /**
+         * After files were filtered and added to the queue, create a model for each.
+         *
+         * @event FilesAdded
+         * @param {plupload.Uploader} uploader Uploader instance.
+         * @param {Array}             files    Array of file objects that were added to queue by the user.
+         */
         this.uploader.bind( 'FilesAdded', function( up, files ) {
             _.each( files, function( file ) {
@@ -196 +220 @@
                 image = /(?:jpe?g|png|gif)$/i.exec( file.name );
 
-                // Did we find an image?
+                // For images set the model's type and subtype attributes.
                 if ( image ) {
                     attributes.type = 'image';
@@ -205 +229 @@
                 }
 
-                // Create the `Attachment`.
+                // Create a model for the attachment, and add it to the Upload queue collection
+                // so listeners to the upload queue can track and display upload progress.
                 file.attachment = wp.media.model.Attachment.create( attributes );
-
                 Uploader.queue.add( file.attachment );
 
@@ -222 +246 @@
         });
 
+        /**
+         * After a file is successfully uploaded, update its model.
+         *
+         * @param {plupload.Uploader} uploader Uploader instance.
+         * @param {plupload.File}     file     File that was uploaded.
+         * @param {Object}            response Object with response properties.
+         * @return {mixed}
+         */
         this.uploader.bind( 'FileUploaded', function( up, file, response ) {
             var complete;
@@ -253 +285 @@
         });
 
+        /**
+         * When plupload surfaces an error, send it to the error handler.
+         *
+         * @param {plupload.Uploader} uploader Uploader instance.
+         * @param {Object}            error    Contains code, message and sometimes file and other details.
+         */
         this.uploader.bind( 'Error', function( up, pluploadError ) {
             var message = pluploadL10n.default_error,
@@ -284 +322 @@
     Uploader.uuid = 0;
 
+    // Map Plupload error codes to user friendly error messages.
     Uploader.errorMap = {
         'FAILED':                 pluploadL10n.upload_failed,
@@ -325 +364 @@
         },
 
+        /**
+         * Make a few internal event callbacks available on the wp.Uploader object
+         * to change the Uploader internals if absolutely necessary.
+         */
         init:     function() {},
         error:    function() {},
@@ -371 +414 @@
     });
 
+    // Create a collection of attachments in the upload queue,
+    // so that other modules can track and display upload progress.
     Uploader.queue = new wp.media.model.Attachments( [], { query: false });
+
+    // Create a collection to collect errors incurred while attempting upload.
     Uploader.errors = new Backbone.Collection();