WordPress.org

Make WordPress Core

Changeset 30244


Ignore:
Timestamp:
11/05/2014 07:36:27 PM (6 years ago)
Author:
wonderboymusic
Message:

Improve wp.Uploader documentation.

Props ericlewis.
See #30260.

Location:
trunk/src
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/async-upload.php

    r29355 r30244  
    11<?php
    22/**
    3  * Accepts file uploads from swfupload or other asynchronous upload methods.
     3 * Server-side file upload handler from wp-plupload, swfupload or other asynchronous upload methods.
    44 *
    55 * @package WordPress
  • trunk/src/wp-includes/js/plupload/wp-plupload.js

    r29917 r30244  
    1111
    1212    /**
    13      * An object that helps create a WordPress uploader using plupload.
     13     * A WordPress uploader.
    1414     *
    15      * @param options - object - The options passed to the new plupload instance.
    16      *    Accepts the following parameters:
    17      *    - container - The id of uploader container.
    18      *    - browser   - The id of button to trigger the file select.
    19      *    - dropzone  - The id of file drop target.
    20      *    - plupload  - An object of parameters to pass to the plupload instance.
    21      *    - params    - An object of parameters to pass to $_POST when uploading the file.
    22      *                  Extends this.plupload.multipart_params under the hood.
     15     * The Plupload library provides cross-browser uploader UI integration.
     16     * This object bridges the Plupload API to integrate uploads into the
     17     * WordPress back-end and the WordPress media experience.
    2318     *
    24      * @param attributes - object - Attributes and methods for this specific instance.
     19     * @param {object} options           The options passed to the new plupload instance.
     20     * @param {object} options.container The id of uploader container.
     21     * @param {object} options.browser   The id of button to trigger the file select.
     22     * @param {object} options.dropzone  The id of file drop target.
     23     * @param {object} options.plupload  An object of parameters to pass to the plupload instance.
     24     * @param {object} options.params    An object of parameters to pass to $_POST when uploading the file.
     25     *                                   Extends this.plupload.multipart_params under the hood.
    2526     */
    2627    Uploader = function( options ) {
     
    4445        }
    4546
     47        // Arguments to send to pluplad.Uploader().
    4648        // Use deep extend to ensure that multipart_params and other objects are cloned.
    4749        this.plupload = $.extend( true, { multipart_params: {} }, Uploader.defaults );
    4850        this.container = document.body; // Set default container.
    4951
    50         // Extend the instance with options
     52        // Extend the instance with options.
    5153        //
    5254        // Use deep extend to allow options.plupload to override individual
     
    6163        }
    6264
    63         // Ensure all elements are jQuery elements and have id attributes
    64         // Then set the proper plupload arguments to the ids.
     65        // Ensure all elements are jQuery elements and have id attributes,
     66        // then set the proper plupload arguments to the ids.
    6567        for ( key in elements ) {
    6668            if ( ! this[ key ] ) {
     
    9597        }
    9698
     99        // Initialize the plupload instance.
    97100        this.uploader = new plupload.Uploader( this.plupload );
    98101        delete this.plupload;
     
    102105        delete this.params;
    103106
     107        /**
     108         * Custom error callback.
     109         *
     110         * Add a new error to the errors collection, so other modules can track
     111         * and display errors. @see wp.Uploader.errors.
     112         *
     113         * @param  {string}        message
     114         * @param  {object}        data
     115         * @param  {plupload.File} file     File that was uploaded.
     116         */
    104117        error = function( message, data, file ) {
    105118            if ( file.attachment ) {
     
    116129        };
    117130
     131        /**
     132         * After the Uploader has been initialized, initialize some behaviors for the dropzone.
     133         *
     134         * @param {plupload.Uploader} uploader Uploader instance.
     135         */
    118136        this.uploader.bind( 'init', function( uploader ) {
    119137            var timer, active, dragdrop,
     
    133151            }
    134152
    135             // 'dragenter' doesn't fire correctly,
    136             // simulate it with a limited 'dragover'
     153            // 'dragenter' doesn't fire correctly, simulate it with a limited 'dragover'.
    137154            dropzone.bind( 'dragover.wp-uploader', function() {
    138155                if ( timer ) {
     
    153170                // dropzone are repositioned.
    154171                //
    155                 // See https://core.trac.wordpress.org/ticket/21705
     172                // @see https://core.trac.wordpress.org/ticket/21705
    156173                timer = setTimeout( function() {
    157174                    active = false;
     
    159176                }, 0 );
    160177            });
    161            
     178
    162179            self.ready = true;
    163180            $(self).trigger( 'uploader:ready' );
     
    174191        }
    175192
     193        /**
     194         * After files were filtered and added to the queue, create a model for each.
     195         *
     196         * @event FilesAdded
     197         * @param {plupload.Uploader} uploader Uploader instance.
     198         * @param {Array}             files    Array of file objects that were added to queue by the user.
     199         */
    176200        this.uploader.bind( 'FilesAdded', function( up, files ) {
    177201            _.each( files, function( file ) {
     
    196220                image = /(?:jpe?g|png|gif)$/i.exec( file.name );
    197221
    198                 // Did we find an image?
     222                // For images set the model's type and subtype attributes.
    199223                if ( image ) {
    200224                    attributes.type = 'image';
     
    205229                }
    206230
    207                 // Create the `Attachment`.
     231                // Create a model for the attachment, and add it to the Upload queue collection
     232                // so listeners to the upload queue can track and display upload progress.
    208233                file.attachment = wp.media.model.Attachment.create( attributes );
    209 
    210234                Uploader.queue.add( file.attachment );
    211235
     
    222246        });
    223247
     248        /**
     249         * After a file is successfully uploaded, update its model.
     250         *
     251         * @param {plupload.Uploader} uploader Uploader instance.
     252         * @param {plupload.File}     file     File that was uploaded.
     253         * @param {Object}            response Object with response properties.
     254         * @return {mixed}
     255         */
    224256        this.uploader.bind( 'FileUploaded', function( up, file, response ) {
    225257            var complete;
     
    253285        });
    254286
     287        /**
     288         * When plupload surfaces an error, send it to the error handler.
     289         *
     290         * @param {plupload.Uploader} uploader Uploader instance.
     291         * @param {Object}            error    Contains code, message and sometimes file and other details.
     292         */
    255293        this.uploader.bind( 'Error', function( up, pluploadError ) {
    256294            var message = pluploadL10n.default_error,
     
    284322    Uploader.uuid = 0;
    285323
     324    // Map Plupload error codes to user friendly error messages.
    286325    Uploader.errorMap = {
    287326        'FAILED':                 pluploadL10n.upload_failed,
     
    325364        },
    326365
     366        /**
     367         * Make a few internal event callbacks available on the wp.Uploader object
     368         * to change the Uploader internals if absolutely necessary.
     369         */
    327370        init:     function() {},
    328371        error:    function() {},
     
    371414    });
    372415
     416    // Create a collection of attachments in the upload queue,
     417    // so that other modules can track and display upload progress.
    373418    Uploader.queue = new wp.media.model.Attachments( [], { query: false });
     419
     420    // Create a collection to collect errors incurred while attempting upload.
    374421    Uploader.errors = new Backbone.Collection();
    375422
Note: See TracChangeset for help on using the changeset viewer.