WordPress.org
Get WordPress

Make WordPress Core

Ticket #42955: media-views-attachments-documentation.diff

File media-views-attachments-documentation.diff, 11.3 KB (added by ireneyoast, 8 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 73edcec8f4..2098b01ffc 100644
    var View = wp.media.View, 
    55/**
    66 * wp.media.view.Attachments
    77 *
     8 * Represents the overview of attachments in the Media Library.
     9 *
     10 * @since 4.2.0
     11 *
    812 * @memberOf wp.media.view
    913 *
    1014 * @class
    1115 * @augments wp.media.View
    1216 * @augments wp.Backbone.View
    1317 * @augments Backbone.View
     18 *
     19 * @access private
    1420 */
    1521Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{
    1622        tagName:   'ul',
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    2026                tabIndex: -1
    2127        },
    2228
     29        /**
     30         * Binds events to scrolling to trigger the scroll function.
     31         *
     32         * Binds events to the collection this view represents when adding or removing attachments
     33         * or resetting the entire collection.
     34         *
     35         * @since 4.2.0
     36         *
     37         * @constructs
     38         * @memberof wp.media.view
     39         *
     40         * @augments wp.media.View
     41         * @augments wp.Backbone.View
     42         * @augments Backbone.View
     43         *
     44         * @listens collection:add
     45         * @listens collection:remove
     46         * @listens collection:reset
     47         * @listens controller:library:selection:add
     48         * @listens scrollElement:scroll
     49         * @listens this:ready
     50         * @listens controller:open
     51         */
    2352        initialize: function() {
    2453                this.el.id = _.uniqueId('__attachments-view-');
    2554
     55                /**
     56                 * @param refreshSensitivity The time in milliseconds to throttle the scroll handler.
     57                 * @param refreshThreshold   The amount of pixels that should be scrolled before loading more attachments
     58                 *                           from the server.
     59                 * @param AttachmentView     The view class to be used for models in the collection.
     60                 * @param sortable           A jQuery sortable options object ( http://api.jqueryui.com/sortable/ ).
     61                 * @param resize             A boolean indicating whether or not to listen to resize events.
     62                 * @param idealColumnWidth   The width in pixels which a column should have when calculating the
     63                 *                           total number of columns.
     64                 */
    2665                _.defaults( this.options, {
    2766                        refreshSensitivity: wp.media.isTouchDevice ? 300 : 200,
    2867                        refreshThreshold:   3,
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    4281                        });
    4382                }, this );
    4483
     84                /*
     85                 * Find the view to be removed, delete it and call the remove function to clear
     86                 * any set event handlers.
     87                 */
    4588                this.collection.on( 'remove', function( attachment ) {
    4689                        var view = this._viewsByCid[ attachment.cid ];
    4790                        delete this._viewsByCid[ attachment.cid ];
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    69112                        this.on( 'ready', this.bindEvents );
    70113                        this.controller.on( 'open', this.setColumns );
    71114
    72                         // Call this.setColumns() after this view has been rendered in the DOM so
    73                         // attachments get proper width applied.
     115                        /*
     116                         * Call this.setColumns() after this view has been rendered in the
     117                         * DOM so attachments get proper width applied.
     118                         */
    74119                        _.defer( this.setColumns, this );
    75120                }
    76121        },
    77122
     123        /**
     124         * Listens to the resizeEvent on the window.
     125         *
     126         * Listens to the resizeEvent on the window and adjusts the amount of columns accordingly.
     127         * First removes any existing event handlers to prevent duplicate listeners.
     128         *
     129         * @since 4.2.0
     130         *
     131         * @listens window:resize
     132         *
     133         * @returns {void}
     134         */
    78135        bindEvents: function() {
    79136                this.$window.off( this.resizeEvent ).on( this.resizeEvent, _.debounce( this.setColumns, 50 ) );
    80137        },
    81138
     139        /**
     140         * Focuses the first item in the collection.
     141         *
     142         * @since 4.2.0
     143         *
     144         * @returns {void}
     145         */
    82146        attachmentFocus: function() {
    83147                this.$( 'li:first' ).focus();
    84148        },
    85149
     150        /**
     151         * Restores focus to the selected item in the collection.
     152         *
     153         * @since 4.2.0
     154         *
     155         * @returns {void}
     156         */
    86157        restoreFocus: function() {
    87158                this.$( 'li.selected:first' ).focus();
    88159        },
    89160
     161        /**
     162         * Event handler for arrow key presses.
     163         * Focuses the attachment in the direction of the used arrow key if it exists.
     164         *
     165         * @since 4.2.0
     166         *
     167         * @param {KeyboardEvent} event The keyboard event that triggered this function.
     168         *
     169         * @returns {void}
     170         */
    90171        arrowEvent: function( event ) {
    91172                var attachments = this.$el.children( 'li' ),
    92173                        perRow = this.columns,
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    97178                        return;
    98179                }
    99180
    100                 // Left arrow
     181                // Left arrow = 37.
    101182                if ( 37 === event.keyCode ) {
    102183                        if ( 0 === index ) {
    103184                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    105186                        attachments.eq( index - 1 ).focus();
    106187                }
    107188
    108                 // Up arrow
     189                // Up arrow = 38.
    109190                if ( 38 === event.keyCode ) {
    110191                        if ( 1 === row ) {
    111192                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    113194                        attachments.eq( index - perRow ).focus();
    114195                }
    115196
    116                 // Right arrow
     197                // Right arrow = 39.
    117198                if ( 39 === event.keyCode ) {
    118199                        if ( attachments.length === index ) {
    119200                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    121202                        attachments.eq( index + 1 ).focus();
    122203                }
    123204
    124                 // Down arrow
     205                // Down arrow = 40.
    125206                if ( 40 === event.keyCode ) {
    126207                        if ( Math.ceil( attachments.length / perRow ) === row ) {
    127208                                return;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    130211                }
    131212        },
    132213
     214        /**
     215         * Clears any set event handlers.
     216         *
     217         * @since 4.2.0
     218         *
     219         * @returns {void}
     220         */
    133221        dispose: function() {
    134222                this.collection.props.off( null, null, this );
    135223                if ( this.options.resize ) {
    136224                        this.$window.off( this.resizeEvent );
    137225                }
    138226
    139                 /**
    140                  * call 'dispose' directly on the parent class
    141                  */
     227                // Call 'dispose' directly on the parent class.
    142228                View.prototype.dispose.apply( this, arguments );
    143229        },
    144230
     231        /**
     232         * Calculates the amount of columns.
     233         *
     234         * Calculates the amount of columns and sets it on the data-columns attribute
     235         * of .media-frame-content.
     236         *
     237         * @since 4.2.0
     238         *
     239         * @returns {void}
     240         */
    145241        setColumns: function() {
    146242                var prev = this.columns,
    147243                        width = this.$el.width();
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    155251                }
    156252        },
    157253
     254        /**
     255         * Initializes jQuery sortable on the list.
     256         *
     257         * Initializes jQuery sortable on the list if jQuery sortable exists and sortable has
     258         * been passed to the options.
     259         *
     260         * @since 4.2.0
     261         *
     262         * @fires collection:reset
     263         *
     264         * @returns {void}
     265         */
    158266        initSortable: function() {
    159267                var collection = this.collection;
    160268
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    166274                        // If the `collection` has a `comparator`, disable sorting.
    167275                        disabled: !! collection.comparator,
    168276
    169                         // Change the position of the attachment as soon as the
    170                         // mouse pointer overlaps a thumbnail.
     277                        // Change the position of the attachment as soon as the mouse pointer overlaps a thumbnail.
    171278                        tolerance: 'pointer',
    172279
    173280                        // Record the initial `index` of the dragged model.
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    175282                                ui.item.data('sortableIndexStart', ui.item.index());
    176283                        },
    177284
    178                         // Update the model's index in the collection.
    179                         // Do so silently, as the view is already accurate.
     285                        /*
     286                         * Update the model's index in the collection.
     287                         * Do so silently, as the view is already accurate.
     288                         */
    180289                        update: function( event, ui ) {
    181290                                var model = collection.at( ui.item.data('sortableIndexStart') ),
    182291                                        comparator = collection.comparator;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    200309                                // Fire the `reset` event to ensure other collections sync.
    201310                                collection.trigger( 'reset', collection );
    202311
    203                                 // If the collection is sorted by menu order,
    204                                 // update the menu order.
     312                                // If the collection is sorted by menu order, update the menu order.
    205313                                collection.saveMenuOrder();
    206314                        }
    207315                }, this.options.sortable ) );
    208316
    209                 // If the `orderby` property is changed on the `collection`,
    210                 // check to see if we have a `comparator`. If so, disable sorting.
     317                /*
     318                 * If the `orderby` property is changed on the `collection`,
     319                 * check to see if we have a `comparator`. If so, disable sorting.
     320                 */
    211321                collection.props.on( 'change:orderby', function() {
    212322                        this.$el.sortable( 'option', 'disabled', !! collection.comparator );
    213323                }, this );
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    216326                this.refreshSortable();
    217327        },
    218328
     329        /**
     330         * Disables jQuery sortable if collection has a comparator or collection.orderby equals menuOrder.
     331         *
     332         * @since 4.2.0
     333         *
     334         * @returns {void}
     335         */
    219336        refreshSortable: function() {
    220337                if ( ! this.options.sortable || ! $.fn.sortable ) {
    221338                        return;
    222339                }
    223340
    224                 // If the `collection` has a `comparator`, disable sorting.
    225341                var collection = this.collection,
    226342                        orderby = collection.props.get('orderby'),
    227343                        enabled = 'menuOrder' === orderby || ! collection.comparator;
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    230346        },
    231347
    232348        /**
     349         * Creates a new view for an attachment and adds it to _viewsByCid.
     350         *
     351         * @since 4.2.0
     352         *
    233353         * @param {wp.media.model.Attachment} attachment
    234          * @returns {wp.media.View}
     354         *
     355         * @returns {wp.media.View} The created view.
    235356         */
    236357        createAttachmentView: function( attachment ) {
    237358                var view = new this.options.AttachmentView({
    … … Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ 
    244365                return this._viewsByCid[ attachment.cid ] = view;
    245366        },
    246367
     368        /**
     369         * Creates views for every attachment in collection.
     370         *
     371         * Creates views for every attachment in collection if the collection is not empty,
     372         * otherwise clears all views and loads more attachments.
     373         *
     374         * @since 4.2.0
     375         *
     376         * @returns {void}
     377         */
    247378        prepare: function() {
    248                 // Create all of the Attachment views, and replace
    249                 // the list in a single DOM operation.
    250379                if ( this.collection.length ) {
    251380                        this.views.set( this.collection.map( this.createAttachmentView, this ) );
    252 
    253                 // If there are no elements, clear the views and load some.
    254381                } else {
    255382                        this.views.unset();
    256383                        this.collection.more().done( this.scroll );
    257384                }
    258385        },
    259386
     387        /**
     388         * Triggers the scroll function to check if we should query for additional attachments right away.
     389         *
     390         * @since 4.2.0
     391         *
     392         * @returns {void}
     393         */
    260394        ready: function() {
    261                 // Trigger the scroll event to check if we're within the
    262                 // threshold to query for additional attachments.
    263395                this.scroll();
    264396        },
    265397
     398        /**
     399         * Event handler for scroll events.
     400         *
     401         * Shows the spinner if we're close to the bottom. Loads more attachments from
     402         * server if we're {refreshThreshold} times away from the bottom.
     403         *
     404         * @since 4.2.0
     405         *
     406         * @returns {void}
     407         */
    266408        scroll: function() {
    267409                var view = this,
    268410                        el = this.options.scrollElement,
    269411                        scrollTop = el.scrollTop,
    270412                        toolbar;
    271413
    272                 // The scroll event occurs on the document, but the element
    273                 // that should be checked is the document body.
     414                /*
     415                 * The scroll event occurs on the document, but the element
     416                 * that should be checked is the document body.
     417                 */
    274418                if ( el === document ) {
    275419                        el = document.body;
    276420                        scrollTop = $(document).scrollTop();