WordPress.org
Get WordPress

Make WordPress Core

Ticket #42832: attachments.js.diff

File attachments.js.diff, 11.1 KB (added by maartenleenders, 9 years ago)

  • src/wp-includes/js/media/views/attachments.js 

    diff --git src/wp-includes/js/media/views/attachments.js src/wp-includes/js/media/views/attachments.js
index 73edcec8f..32798ed5d 100644
    var View = wp.media.View,  
    55/**
    66 * wp.media.view.Attachments
    77 *
     8 * Represents the overview of attachments in the Media Library.
     9 *
    810 * @memberOf wp.media.view
    911 *
    1012 * @class
    1113 * @augments wp.media.View
    1214 * @augments wp.Backbone.View
    1315 * @augments Backbone.View
     16 *
     17 * @access private
    1418 */
    1519Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{
    1620        tagName:   'ul',
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    2024                tabIndex: -1
    2125        },
    2226
     27        /**
     28         * Binds events to the collection this view represents when adding or removing attachments
     29         * or resetting the entire collection.
     30         *
     31         * @summary Binds events to scrolling to trigger the scroll function.
     32         *
     33         * @constructs
     34         * @memberof wp.media.view
     35         *
     36         * @augments wp.media.View
     37         * @augments wp.Backbone.View
     38         * @augments Backbone.View
     39         *
     40         * @listens collection:add
     41         * @listens collection:remove
     42         * @listens collection:reset
     43         * @listens controller:library:selection:add
     44         * @listens scrollElement:scroll
     45         * @listens this:ready
     46         * @listens controller:open
     47         */
    2348        initialize: function() {
    2449                this.el.id = _.uniqueId('__attachments-view-');
    2550
     51                /**
     52                 * @param refreshSensitivity The time in milliseconds to throttle the scroll handler.
     53                 * @param refreshThreshold   The amount of pixels that should be scrolled before loading more attachments
     54                 *                           from the server.
     55                 * @param AttachmentView     The view class to be used for models in the collection.
     56                 * @param sortable           A jQuery sortable options object ( http://api.jqueryui.com/sortable/ ).
     57                 * @param resize             A boolean indicating whether or not to listen to resize events.
     58                 * @param idealColumnWidth   The width in pixels which a column should have when calculating the
     59                 *                           total number of columns.
     60                 */
    2661                _.defaults( this.options, {
    2762                        refreshSensitivity: wp.media.isTouchDevice ? 300 : 200,
    2863                        refreshThreshold:   3,
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    4277                        });
    4378                }, this );
    4479
     80                /*
     81                 * Find the view to be removed, delete it and call the remove function to clear
     82                 * any set event handlers.
     83                 */
    4584                this.collection.on( 'remove', function( attachment ) {
    4685                        var view = this._viewsByCid[ attachment.cid ];
    4786                        delete this._viewsByCid[ attachment.cid ];
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    69108                        this.on( 'ready', this.bindEvents );
    70109                        this.controller.on( 'open', this.setColumns );
    71110
    72                         // Call this.setColumns() after this view has been rendered in the DOM so
    73                         // attachments get proper width applied.
     111                        /*
     112                         * Call this.setColumns() after this view has been rendered in the
     113                         * DOM so attachments get proper width applied.
     114                         */
    74115                        _.defer( this.setColumns, this );
    75116                }
    76117        },
    77118
     119        /**
     120         * Listens to the resizeEvent on the window and adjusts the amount of columns accordingly.
     121         * First removes any existing event handlers to prevent duplicate listeners.
     122         *
     123         * @summary Listens to the resizeEvent on the window
     124         *
     125         * @listens window:resize
     126         *
     127         * @returns {void}
     128         */
    78129        bindEvents: function() {
    79130                this.$window.off( this.resizeEvent ).on( this.resizeEvent, _.debounce( this.setColumns, 50 ) );
    80131        },
    81132
     133        /**
     134         * Focuses the first item in the collection.
     135         *
     136         * @returns {void}
     137         */
    82138        attachmentFocus: function() {
    83139                this.$( 'li:first' ).focus();
    84140        },
    85141
     142        /**
     143         * Restores focus to the selected item in the collection.
     144         *
     145         * @returns {void}
     146         */
    86147        restoreFocus: function() {
    87148                this.$( 'li.selected:first' ).focus();
    88149        },
    89150
     151        /**
     152         * Event handler for arrow key presses.
     153         * Focuses the attachment in the direction of the used arrow key if it exists.
     154         *
     155         * @param {KeyboardEvent} event The keyboard event that triggered this function.
     156         *
     157         * @returns {void}
     158         */
    90159        arrowEvent: function( event ) {
    91160                var attachments = this.$el.children( 'li' ),
    92161                        perRow = this.columns,
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    97166                        return;
    98167                }
    99168
    100                 // Left arrow
     169                // Left arrow = 37.
    101170                if ( 37 === event.keyCode ) {
    102171                        if ( 0 === index ) {
    103172                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    105174                        attachments.eq( index - 1 ).focus();
    106175                }
    107176
    108                 // Up arrow
     177                // Up arrow = 38.
    109178                if ( 38 === event.keyCode ) {
    110179                        if ( 1 === row ) {
    111180                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    113182                        attachments.eq( index - perRow ).focus();
    114183                }
    115184
    116                 // Right arrow
     185                // Right arrow = 39.
    117186                if ( 39 === event.keyCode ) {
    118187                        if ( attachments.length === index ) {
    119188                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    121190                        attachments.eq( index + 1 ).focus();
    122191                }
    123192
    124                 // Down arrow
     193                // Down arrow = 40.
    125194                if ( 40 === event.keyCode ) {
    126195                        if ( Math.ceil( attachments.length / perRow ) === row ) {
    127196                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    130199                }
    131200        },
    132201
     202        /**
     203         * Clears any set event handlers.
     204         *
     205         * @returns {void}
     206         */
    133207        dispose: function() {
    134208                this.collection.props.off( null, null, this );
    135209                if ( this.options.resize ) {
    136210                        this.$window.off( this.resizeEvent );
    137211                }
    138212
    139                 /**
    140                  * call 'dispose' directly on the parent class
    141                  */
     213                // Call 'dispose' directly on the parent class.
    142214                View.prototype.dispose.apply( this, arguments );
    143215        },
    144216
     217        /**
     218         * Calculates the amount of columns and sets it on the data-columns attribute
     219         * of .media-frame-content.
     220         *
     221         * @summary Calculates the amount of columns.
     222         *
     223         * @returns {void}
     224         */
    145225        setColumns: function() {
    146226                var prev = this.columns,
    147227                        width = this.$el.width();
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    155235                }
    156236        },
    157237
     238        /**
     239         * Initializes jQuery sortable on the list if jQuery sortable exists and sortable has
     240         * been passed to the options.
     241         *
     242         * @summary Initializes jQuery sortable on the list.
     243         *
     244         * @fires collection:reset
     245         *
     246         * @returns {void}
     247         */
    158248        initSortable: function() {
    159249                var collection = this.collection;
    160250
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    166256                        // If the `collection` has a `comparator`, disable sorting.
    167257                        disabled: !! collection.comparator,
    168258
    169                         // Change the position of the attachment as soon as the
    170                         // mouse pointer overlaps a thumbnail.
     259                        // Change the position of the attachment as soon as the mouse pointer overlaps a thumbnail.
    171260                        tolerance: 'pointer',
    172261
    173262                        // Record the initial `index` of the dragged model.
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    175264                                ui.item.data('sortableIndexStart', ui.item.index());
    176265                        },
    177266
    178                         // Update the model's index in the collection.
    179                         // Do so silently, as the view is already accurate.
     267                        /*
     268                         * Update the model's index in the collection.
     269                         * Do so silently, as the view is already accurate.
     270                         */
    180271                        update: function( event, ui ) {
    181272                                var model = collection.at( ui.item.data('sortableIndexStart') ),
    182273                                        comparator = collection.comparator;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    200291                                // Fire the `reset` event to ensure other collections sync.
    201292                                collection.trigger( 'reset', collection );
    202293
    203                                 // If the collection is sorted by menu order,
    204                                 // update the menu order.
     294                                // If the collection is sorted by menu order, update the menu order.
    205295                                collection.saveMenuOrder();
    206296                        }
    207297                }, this.options.sortable ) );
    208298
    209                 // If the `orderby` property is changed on the `collection`,
    210                 // check to see if we have a `comparator`. If so, disable sorting.
     299                /*
     300                 * If the `orderby` property is changed on the `collection`,
     301                 * check to see if we have a `comparator`. If so, disable sorting.
     302                 */
    211303                collection.props.on( 'change:orderby', function() {
    212304                        this.$el.sortable( 'option', 'disabled', !! collection.comparator );
    213305                }, this );
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    216308                this.refreshSortable();
    217309        },
    218310
     311        /**
     312         * Disables jQuery sortable if collection has a comparator or collection.orderby equals menuOrder.
     313         *
     314         * @returns {void}
     315         */
    219316        refreshSortable: function() {
    220317                if ( ! this.options.sortable || ! $.fn.sortable ) {
    221318                        return;
    222319                }
    223320
    224                 // If the `collection` has a `comparator`, disable sorting.
    225321                var collection = this.collection,
    226322                        orderby = collection.props.get('orderby'),
    227323                        enabled = 'menuOrder' === orderby || ! collection.comparator;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    230326        },
    231327
    232328        /**
     329         * Creates a new view for an attachment and adds it to _viewsByCid.
     330         *
    233331         * @param {wp.media.model.Attachment} attachment
    234          * @returns {wp.media.View}
     332         *
     333         * @returns {wp.media.View} The created view.
    235334         */
    236335        createAttachmentView: function( attachment ) {
    237336                var view = new this.options.AttachmentView({
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{  
    244343                return this._viewsByCid[ attachment.cid ] = view;
    245344        },
    246345
     346        /**
     347         * Creates views for every attachment in collection if the collection is not empty,
     348         * otherwise clears all views and loads more attachments.
     349         *
     350         * @summary Creates views for every attachment in collection.
     351         *
     352         * @returns {void}
     353         */
    247354        prepare: function() {
    248                 // Create all of the Attachment views, and replace
    249                 // the list in a single DOM operation.
    250355                if ( this.collection.length ) {
    251356                        this.views.set( this.collection.map( this.createAttachmentView, this ) );
    252 
    253                 // If there are no elements, clear the views and load some.
    254357                } else {
    255358                        this.views.unset();
    256359                        this.collection.more().done( this.scroll );
    257360                }
    258361        },
    259362
     363        /**
     364         * Triggers the scroll function to check if we should query for additional attachments right away.
     365         *
     366         * @returns {void}
     367         */
    260368        ready: function() {
    261                 // Trigger the scroll event to check if we're within the
    262                 // threshold to query for additional attachments.
    263369                this.scroll();
    264370        },
    265371
     372        /**
     373         * Event handler for scroll events.
     374         * Shows the spinner if we're close to the bottom.
     375         * Loads more attachments from server if we're {refreshThreshold} times away from the bottom.
     376         *
     377         * @summary Event handler for scroll events.
     378         *
     379         * @returns {void}
     380         */
    266381        scroll: function() {
    267382                var view = this,
    268383                        el = this.options.scrollElement,
    269384                        scrollTop = el.scrollTop,
    270385                        toolbar;
    271386
    272                 // The scroll event occurs on the document, but the element
    273                 // that should be checked is the document body.
     387                /*
     388                 * The scroll event occurs on the document, but the element
     389                 * that should be checked is the document body.
     390                 */
    274391                if ( el === document ) {
    275392                        el = document.body;
    276393                        scrollTop = $(document).scrollTop();