WordPress.org

Make WordPress Core

Changeset 42415


Ignore:
Timestamp:
12/21/2017 02:26:17 PM (2 years ago)
Author:
atimmer
Message:

Docs: Improve JSDoc for media/views/attachments.js.

Props maartenleenders, herregroen, jipmoors, ireneyoast.
Fixes #42832.

Location:
trunk/src/wp-includes/js
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/js/media-views.js

    r42411 r42415  
    66216621    Attachments;
    66226622
    6623 /**
    6624  * wp.media.view.Attachments
    6625  *
    6626  * @memberOf wp.media.view
    6627  *
    6628  * @class
    6629  * @augments wp.media.View
    6630  * @augments wp.Backbone.View
    6631  * @augments Backbone.View
    6632  */
    66336623Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{
    66346624    tagName:   'ul',
     
    66396629    },
    66406630
     6631    /**
     6632     * Represents the overview of attachments in the Media Library.
     6633     *
     6634     * The constructor binds events to the collection this view represents when
     6635     * adding or removing attachments or resetting the entire collection.
     6636     *
     6637     * @since 3.5.0
     6638     *
     6639     * @constructs
     6640     * @memberof wp.media.view
     6641     *
     6642     * @augments wp.media.View
     6643     *
     6644     * @listens collection:add
     6645     * @listens collection:remove
     6646     * @listens collection:reset
     6647     * @listens controller:library:selection:add
     6648     * @listens scrollElement:scroll
     6649     * @listens this:ready
     6650     * @listens controller:open
     6651     */
    66416652    initialize: function() {
    66426653        this.el.id = _.uniqueId('__attachments-view-');
    66436654
     6655        /**
     6656         * @param refreshSensitivity The time in milliseconds to throttle the scroll
     6657         *                           handler.
     6658         * @param refreshThreshold   The amount of pixels that should be scrolled before
     6659         *                           loading more attachments from the server.
     6660         * @param AttachmentView     The view class to be used for models in the
     6661         *                           collection.
     6662         * @param sortable           A jQuery sortable options object
     6663         *                           ( http://api.jqueryui.com/sortable/ ).
     6664         * @param resize             A boolean indicating whether or not to listen to
     6665         *                           resize events.
     6666         * @param idealColumnWidth   The width in pixels which a column should have when
     6667         *                           calculating the total number of columns.
     6668         */
    66446669        _.defaults( this.options, {
    66456670            refreshSensitivity: wp.media.isTouchDevice ? 300 : 200,
     
    66616686        }, this );
    66626687
     6688        /*
     6689         * Find the view to be removed, delete it and call the remove function to clear
     6690         * any set event handlers.
     6691         */
    66636692        this.collection.on( 'remove', function( attachment ) {
    66646693            var view = this._viewsByCid[ attachment.cid ];
     
    66886717            this.controller.on( 'open', this.setColumns );
    66896718
    6690             // Call this.setColumns() after this view has been rendered in the DOM so
    6691             // attachments get proper width applied.
     6719            /*
     6720             * Call this.setColumns() after this view has been rendered in the
     6721             * DOM so attachments get proper width applied.
     6722             */
    66926723            _.defer( this.setColumns, this );
    66936724        }
    66946725    },
    66956726
     6727    /**
     6728     * Listens to the resizeEvent on the window.
     6729     *
     6730     * Adjusts the amount of columns accordingly. First removes any existing event
     6731     * handlers to prevent duplicate listeners.
     6732     *
     6733     * @since 4.0.0
     6734     *
     6735     * @listens window:resize
     6736     *
     6737     * @returns {void}
     6738     */
    66966739    bindEvents: function() {
    66976740        this.$window.off( this.resizeEvent ).on( this.resizeEvent, _.debounce( this.setColumns, 50 ) );
    66986741    },
    66996742
     6743    /**
     6744     * Focuses the first item in the collection.
     6745     *
     6746     * @since 4.0.0
     6747     *
     6748     * @returns {void}
     6749     */
    67006750    attachmentFocus: function() {
    67016751        this.$( 'li:first' ).focus();
    67026752    },
    67036753
     6754    /**
     6755     * Restores focus to the selected item in the collection.
     6756     *
     6757     * @since 4.0.0
     6758     *
     6759     * @returns {void}
     6760     */
    67046761    restoreFocus: function() {
    67056762        this.$( 'li.selected:first' ).focus();
    67066763    },
    67076764
     6765    /**
     6766     * Handles events for arrow key presses.
     6767     *
     6768     * Focuses the attachment in the direction of the used arrow key if it exists.
     6769     *
     6770     * @since 4.0.0
     6771     *
     6772     * @param {KeyboardEvent} event The keyboard event that triggered this function.
     6773     *
     6774     * @returns {void}
     6775     */
    67086776    arrowEvent: function( event ) {
    67096777        var attachments = this.$el.children( 'li' ),
     
    67166784        }
    67176785
    6718         // Left arrow
     6786        // Left arrow = 37.
    67196787        if ( 37 === event.keyCode ) {
    67206788            if ( 0 === index ) {
     
    67246792        }
    67256793
    6726         // Up arrow
     6794        // Up arrow = 38.
    67276795        if ( 38 === event.keyCode ) {
    67286796            if ( 1 === row ) {
     
    67326800        }
    67336801
    6734         // Right arrow
     6802        // Right arrow = 39.
    67356803        if ( 39 === event.keyCode ) {
    67366804            if ( attachments.length === index ) {
     
    67406808        }
    67416809
    6742         // Down arrow
     6810        // Down arrow = 40.
    67436811        if ( 40 === event.keyCode ) {
    67446812            if ( Math.ceil( attachments.length / perRow ) === row ) {
     
    67496817    },
    67506818
     6819    /**
     6820     * Clears any set event handlers.
     6821     *
     6822     * @since 3.5.0
     6823     *
     6824     * @returns {void}
     6825     */
    67516826    dispose: function() {
    67526827        this.collection.props.off( null, null, this );
     
    67556830        }
    67566831
    6757         /**
    6758          * call 'dispose' directly on the parent class
    6759          */
     6832        // Call 'dispose' directly on the parent class.
    67606833        View.prototype.dispose.apply( this, arguments );
    67616834    },
    67626835
     6836    /**
     6837     * Calculates the amount of columns.
     6838     *
     6839     * Calculates the amount of columns and sets it on the data-columns attribute
     6840     * of .media-frame-content.
     6841     *
     6842     * @since 4.0.0
     6843     *
     6844     * @returns {void}
     6845     */
    67636846    setColumns: function() {
    67646847        var prev = this.columns,
     
    67746857    },
    67756858
     6859    /**
     6860     * Initializes jQuery sortable on the attachment list.
     6861     *
     6862     * Fails gracefully if jQuery sortable doesn't exist or isn't passed in the
     6863     * options.
     6864     *
     6865     * @since 3.5.0
     6866     *
     6867     * @fires collection:reset
     6868     *
     6869     * @returns {void}
     6870     */
    67766871    initSortable: function() {
    67776872        var collection = this.collection;
     
    67856880            disabled: !! collection.comparator,
    67866881
    6787             // Change the position of the attachment as soon as the
    6788             // mouse pointer overlaps a thumbnail.
     6882            /*
     6883             * Change the position of the attachment as soon as the mouse pointer overlaps a
     6884             * thumbnail.
     6885             */
    67896886            tolerance: 'pointer',
    67906887
     
    67946891            },
    67956892
    6796             // Update the model's index in the collection.
    6797             // Do so silently, as the view is already accurate.
     6893            /*
     6894             * Update the model's index in the collection. Do so silently, as the view
     6895             * is already accurate.
     6896             */
    67986897            update: function( event, ui ) {
    67996898                var model = collection.at( ui.item.data('sortableIndexStart') ),
     
    68196918                collection.trigger( 'reset', collection );
    68206919
    6821                 // If the collection is sorted by menu order,
    6822                 // update the menu order.
     6920                // If the collection is sorted by menu order, update the menu order.
    68236921                collection.saveMenuOrder();
    68246922            }
    68256923        }, this.options.sortable ) );
    68266924
    6827         // If the `orderby` property is changed on the `collection`,
    6828         // check to see if we have a `comparator`. If so, disable sorting.
     6925        /*
     6926         * If the `orderby` property is changed on the `collection`, check to see if we
     6927         * have a `comparator`. If so, disable sorting.
     6928         */
    68296929        collection.props.on( 'change:orderby', function() {
    68306930            this.$el.sortable( 'option', 'disabled', !! collection.comparator );
     
    68356935    },
    68366936
     6937    /**
     6938     * Disables jQuery sortable if collection has a comparator or collection.orderby
     6939     * equals menuOrder.
     6940     *
     6941     * @since 3.5.0
     6942     *
     6943     * @returns {void}
     6944     */
    68376945    refreshSortable: function() {
    68386946        if ( ! this.options.sortable || ! $.fn.sortable ) {
     
    68406948        }
    68416949
    6842         // If the `collection` has a `comparator`, disable sorting.
    68436950        var collection = this.collection,
    68446951            orderby = collection.props.get('orderby'),
     
    68496956
    68506957    /**
     6958     * Creates a new view for an attachment and adds it to _viewsByCid.
     6959     *
     6960     * @since 3.5.0
     6961     *
    68516962     * @param {wp.media.model.Attachment} attachment
    6852      * @returns {wp.media.View}
     6963     *
     6964     * @returns {wp.media.View} The created view.
    68536965     */
    68546966    createAttachmentView: function( attachment ) {
     
    68636975    },
    68646976
     6977    /**
     6978     * Prepares view for display.
     6979     *
     6980     * Creates views for every attachment in collection if the collection is not
     6981     * empty, otherwise clears all views and loads more attachments.
     6982     *
     6983     * @since 3.5.0
     6984     *
     6985     * @returns {void}
     6986     */
    68656987    prepare: function() {
    6866         // Create all of the Attachment views, and replace
    6867         // the list in a single DOM operation.
    68686988        if ( this.collection.length ) {
    68696989            this.views.set( this.collection.map( this.createAttachmentView, this ) );
    6870 
    6871         // If there are no elements, clear the views and load some.
    68726990        } else {
    68736991            this.views.unset();
     
    68766994    },
    68776995
     6996    /**
     6997     * Triggers the scroll function to check if we should query for additional
     6998     * attachments right away.
     6999     *
     7000     * @since 3.5.0
     7001     *
     7002     * @returns {void}
     7003     */
    68787004    ready: function() {
    6879         // Trigger the scroll event to check if we're within the
    6880         // threshold to query for additional attachments.
    68817005        this.scroll();
    68827006    },
    68837007
     7008    /**
     7009     * Handles scroll events.
     7010     *
     7011     * Shows the spinner if we're close to the bottom. Loads more attachments from
     7012     * server if we're {refreshThreshold} times away from the bottom.
     7013     *
     7014     * @since 3.5.0
     7015     *
     7016     * @returns {void}
     7017     */
    68847018    scroll: function() {
    68857019        var view = this,
     
    68887022            toolbar;
    68897023
    6890         // The scroll event occurs on the document, but the element
    6891         // that should be checked is the document body.
     7024        /*
     7025         * The scroll event occurs on the document, but the element that should be
     7026         * checked is the document body.
     7027         */
    68927028        if ( el === document ) {
    68937029            el = document.body;
  • trunk/src/wp-includes/js/media/views/attachments.js

    r41351 r42415  
    33    Attachments;
    44
    5 /**
    6  * wp.media.view.Attachments
    7  *
    8  * @memberOf wp.media.view
    9  *
    10  * @class
    11  * @augments wp.media.View
    12  * @augments wp.Backbone.View
    13  * @augments Backbone.View
    14  */
    155Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{
    166    tagName:   'ul',
     
    2111    },
    2212
     13    /**
     14     * Represents the overview of attachments in the Media Library.
     15     *
     16     * The constructor binds events to the collection this view represents when
     17     * adding or removing attachments or resetting the entire collection.
     18     *
     19     * @since 3.5.0
     20     *
     21     * @constructs
     22     * @memberof wp.media.view
     23     *
     24     * @augments wp.media.View
     25     *
     26     * @listens collection:add
     27     * @listens collection:remove
     28     * @listens collection:reset
     29     * @listens controller:library:selection:add
     30     * @listens scrollElement:scroll
     31     * @listens this:ready
     32     * @listens controller:open
     33     */
    2334    initialize: function() {
    2435        this.el.id = _.uniqueId('__attachments-view-');
    2536
     37        /**
     38         * @param refreshSensitivity The time in milliseconds to throttle the scroll
     39         *                           handler.
     40         * @param refreshThreshold   The amount of pixels that should be scrolled before
     41         *                           loading more attachments from the server.
     42         * @param AttachmentView     The view class to be used for models in the
     43         *                           collection.
     44         * @param sortable           A jQuery sortable options object
     45         *                           ( http://api.jqueryui.com/sortable/ ).
     46         * @param resize             A boolean indicating whether or not to listen to
     47         *                           resize events.
     48         * @param idealColumnWidth   The width in pixels which a column should have when
     49         *                           calculating the total number of columns.
     50         */
    2651        _.defaults( this.options, {
    2752            refreshSensitivity: wp.media.isTouchDevice ? 300 : 200,
     
    4368        }, this );
    4469
     70        /*
     71         * Find the view to be removed, delete it and call the remove function to clear
     72         * any set event handlers.
     73         */
    4574        this.collection.on( 'remove', function( attachment ) {
    4675            var view = this._viewsByCid[ attachment.cid ];
     
    7099            this.controller.on( 'open', this.setColumns );
    71100
    72             // Call this.setColumns() after this view has been rendered in the DOM so
    73             // attachments get proper width applied.
     101            /*
     102             * Call this.setColumns() after this view has been rendered in the
     103             * DOM so attachments get proper width applied.
     104             */
    74105            _.defer( this.setColumns, this );
    75106        }
    76107    },
    77108
     109    /**
     110     * Listens to the resizeEvent on the window.
     111     *
     112     * Adjusts the amount of columns accordingly. First removes any existing event
     113     * handlers to prevent duplicate listeners.
     114     *
     115     * @since 4.0.0
     116     *
     117     * @listens window:resize
     118     *
     119     * @returns {void}
     120     */
    78121    bindEvents: function() {
    79122        this.$window.off( this.resizeEvent ).on( this.resizeEvent, _.debounce( this.setColumns, 50 ) );
    80123    },
    81124
     125    /**
     126     * Focuses the first item in the collection.
     127     *
     128     * @since 4.0.0
     129     *
     130     * @returns {void}
     131     */
    82132    attachmentFocus: function() {
    83133        this.$( 'li:first' ).focus();
    84134    },
    85135
     136    /**
     137     * Restores focus to the selected item in the collection.
     138     *
     139     * @since 4.0.0
     140     *
     141     * @returns {void}
     142     */
    86143    restoreFocus: function() {
    87144        this.$( 'li.selected:first' ).focus();
    88145    },
    89146
     147    /**
     148     * Handles events for arrow key presses.
     149     *
     150     * Focuses the attachment in the direction of the used arrow key if it exists.
     151     *
     152     * @since 4.0.0
     153     *
     154     * @param {KeyboardEvent} event The keyboard event that triggered this function.
     155     *
     156     * @returns {void}
     157     */
    90158    arrowEvent: function( event ) {
    91159        var attachments = this.$el.children( 'li' ),
     
    98166        }
    99167
    100         // Left arrow
     168        // Left arrow = 37.
    101169        if ( 37 === event.keyCode ) {
    102170            if ( 0 === index ) {
     
    106174        }
    107175
    108         // Up arrow
     176        // Up arrow = 38.
    109177        if ( 38 === event.keyCode ) {
    110178            if ( 1 === row ) {
     
    114182        }
    115183
    116         // Right arrow
     184        // Right arrow = 39.
    117185        if ( 39 === event.keyCode ) {
    118186            if ( attachments.length === index ) {
     
    122190        }
    123191
    124         // Down arrow
     192        // Down arrow = 40.
    125193        if ( 40 === event.keyCode ) {
    126194            if ( Math.ceil( attachments.length / perRow ) === row ) {
     
    131199    },
    132200
     201    /**
     202     * Clears any set event handlers.
     203     *
     204     * @since 3.5.0
     205     *
     206     * @returns {void}
     207     */
    133208    dispose: function() {
    134209        this.collection.props.off( null, null, this );
     
    137212        }
    138213
    139         /**
    140          * call 'dispose' directly on the parent class
    141          */
     214        // Call 'dispose' directly on the parent class.
    142215        View.prototype.dispose.apply( this, arguments );
    143216    },
    144217
     218    /**
     219     * Calculates the amount of columns.
     220     *
     221     * Calculates the amount of columns and sets it on the data-columns attribute
     222     * of .media-frame-content.
     223     *
     224     * @since 4.0.0
     225     *
     226     * @returns {void}
     227     */
    145228    setColumns: function() {
    146229        var prev = this.columns,
     
    156239    },
    157240
     241    /**
     242     * Initializes jQuery sortable on the attachment list.
     243     *
     244     * Fails gracefully if jQuery sortable doesn't exist or isn't passed in the
     245     * options.
     246     *
     247     * @since 3.5.0
     248     *
     249     * @fires collection:reset
     250     *
     251     * @returns {void}
     252     */
    158253    initSortable: function() {
    159254        var collection = this.collection;
     
    167262            disabled: !! collection.comparator,
    168263
    169             // Change the position of the attachment as soon as the
    170             // mouse pointer overlaps a thumbnail.
     264            /*
     265             * Change the position of the attachment as soon as the mouse pointer overlaps a
     266             * thumbnail.
     267             */
    171268            tolerance: 'pointer',
    172269
     
    176273            },
    177274
    178             // Update the model's index in the collection.
    179             // Do so silently, as the view is already accurate.
     275            /*
     276             * Update the model's index in the collection. Do so silently, as the view
     277             * is already accurate.
     278             */
    180279            update: function( event, ui ) {
    181280                var model = collection.at( ui.item.data('sortableIndexStart') ),
     
    201300                collection.trigger( 'reset', collection );
    202301
    203                 // If the collection is sorted by menu order,
    204                 // update the menu order.
     302                // If the collection is sorted by menu order, update the menu order.
    205303                collection.saveMenuOrder();
    206304            }
    207305        }, this.options.sortable ) );
    208306
    209         // If the `orderby` property is changed on the `collection`,
    210         // check to see if we have a `comparator`. If so, disable sorting.
     307        /*
     308         * If the `orderby` property is changed on the `collection`, check to see if we
     309         * have a `comparator`. If so, disable sorting.
     310         */
    211311        collection.props.on( 'change:orderby', function() {
    212312            this.$el.sortable( 'option', 'disabled', !! collection.comparator );
     
    217317    },
    218318
     319    /**
     320     * Disables jQuery sortable if collection has a comparator or collection.orderby
     321     * equals menuOrder.
     322     *
     323     * @since 3.5.0
     324     *
     325     * @returns {void}
     326     */
    219327    refreshSortable: function() {
    220328        if ( ! this.options.sortable || ! $.fn.sortable ) {
     
    222330        }
    223331
    224         // If the `collection` has a `comparator`, disable sorting.
    225332        var collection = this.collection,
    226333            orderby = collection.props.get('orderby'),
     
    231338
    232339    /**
     340     * Creates a new view for an attachment and adds it to _viewsByCid.
     341     *
     342     * @since 3.5.0
     343     *
    233344     * @param {wp.media.model.Attachment} attachment
    234      * @returns {wp.media.View}
     345     *
     346     * @returns {wp.media.View} The created view.
    235347     */
    236348    createAttachmentView: function( attachment ) {
     
    245357    },
    246358
     359    /**
     360     * Prepares view for display.
     361     *
     362     * Creates views for every attachment in collection if the collection is not
     363     * empty, otherwise clears all views and loads more attachments.
     364     *
     365     * @since 3.5.0
     366     *
     367     * @returns {void}
     368     */
    247369    prepare: function() {
    248         // Create all of the Attachment views, and replace
    249         // the list in a single DOM operation.
    250370        if ( this.collection.length ) {
    251371            this.views.set( this.collection.map( this.createAttachmentView, this ) );
    252 
    253         // If there are no elements, clear the views and load some.
    254372        } else {
    255373            this.views.unset();
     
    258376    },
    259377
     378    /**
     379     * Triggers the scroll function to check if we should query for additional
     380     * attachments right away.
     381     *
     382     * @since 3.5.0
     383     *
     384     * @returns {void}
     385     */
    260386    ready: function() {
    261         // Trigger the scroll event to check if we're within the
    262         // threshold to query for additional attachments.
    263387        this.scroll();
    264388    },
    265389
     390    /**
     391     * Handles scroll events.
     392     *
     393     * Shows the spinner if we're close to the bottom. Loads more attachments from
     394     * server if we're {refreshThreshold} times away from the bottom.
     395     *
     396     * @since 3.5.0
     397     *
     398     * @returns {void}
     399     */
    266400    scroll: function() {
    267401        var view = this,
     
    270404            toolbar;
    271405
    272         // The scroll event occurs on the document, but the element
    273         // that should be checked is the document body.
     406        /*
     407         * The scroll event occurs on the document, but the element that should be
     408         * checked is the document body.
     409         */
    274410        if ( el === document ) {
    275411            el = document.body;
Note: See TracChangeset for help on using the changeset viewer.