diff --git src/wp-includes/js/media/views/attachments.js src/wp-includes/js/media/views/attachments.js index 73edcec8f..32798ed5d 100644 --- src/wp-includes/js/media/views/attachments.js +++ src/wp-includes/js/media/views/attachments.js @@ -5,12 +5,16 @@ var View = wp.media.View, /** * wp.media.view.Attachments * + * Represents the overview of attachments in the Media Library. + * * @memberOf wp.media.view * * @class * @augments wp.media.View * @augments wp.Backbone.View * @augments Backbone.View + * + * @access private */ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ tagName: 'ul', @@ -20,9 +24,40 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ tabIndex: -1 }, + /** + * Binds events to the collection this view represents when adding or removing attachments + * or resetting the entire collection. + * + * @summary Binds events to scrolling to trigger the scroll function. + * + * @constructs + * @memberof wp.media.view + * + * @augments wp.media.View + * @augments wp.Backbone.View + * @augments Backbone.View + * + * @listens collection:add + * @listens collection:remove + * @listens collection:reset + * @listens controller:library:selection:add + * @listens scrollElement:scroll + * @listens this:ready + * @listens controller:open + */ initialize: function() { this.el.id = _.uniqueId('__attachments-view-'); + /** + * @param refreshSensitivity The time in milliseconds to throttle the scroll handler. + * @param refreshThreshold The amount of pixels that should be scrolled before loading more attachments + * from the server. + * @param AttachmentView The view class to be used for models in the collection. + * @param sortable A jQuery sortable options object ( http://api.jqueryui.com/sortable/ ). + * @param resize A boolean indicating whether or not to listen to resize events. + * @param idealColumnWidth The width in pixels which a column should have when calculating the + * total number of columns. + */ _.defaults( this.options, { refreshSensitivity: wp.media.isTouchDevice ? 300 : 200, refreshThreshold: 3, @@ -42,6 +77,10 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ }); }, this ); + /* + * Find the view to be removed, delete it and call the remove function to clear + * any set event handlers. + */ this.collection.on( 'remove', function( attachment ) { var view = this._viewsByCid[ attachment.cid ]; delete this._viewsByCid[ attachment.cid ]; @@ -69,24 +108,54 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ this.on( 'ready', this.bindEvents ); this.controller.on( 'open', this.setColumns ); - // Call this.setColumns() after this view has been rendered in the DOM so - // attachments get proper width applied. + /* + * Call this.setColumns() after this view has been rendered in the + * DOM so attachments get proper width applied. + */ _.defer( this.setColumns, this ); } }, + /** + * Listens to the resizeEvent on the window and adjusts the amount of columns accordingly. + * First removes any existing event handlers to prevent duplicate listeners. + * + * @summary Listens to the resizeEvent on the window + * + * @listens window:resize + * + * @returns {void} + */ bindEvents: function() { this.$window.off( this.resizeEvent ).on( this.resizeEvent, _.debounce( this.setColumns, 50 ) ); }, + /** + * Focuses the first item in the collection. + * + * @returns {void} + */ attachmentFocus: function() { this.$( 'li:first' ).focus(); }, + /** + * Restores focus to the selected item in the collection. + * + * @returns {void} + */ restoreFocus: function() { this.$( 'li.selected:first' ).focus(); }, + /** + * Event handler for arrow key presses. + * Focuses the attachment in the direction of the used arrow key if it exists. + * + * @param {KeyboardEvent} event The keyboard event that triggered this function. + * + * @returns {void} + */ arrowEvent: function( event ) { var attachments = this.$el.children( 'li' ), perRow = this.columns, @@ -97,7 +166,7 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ return; } - // Left arrow + // Left arrow = 37. if ( 37 === event.keyCode ) { if ( 0 === index ) { return; @@ -105,7 +174,7 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ attachments.eq( index - 1 ).focus(); } - // Up arrow + // Up arrow = 38. if ( 38 === event.keyCode ) { if ( 1 === row ) { return; @@ -113,7 +182,7 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ attachments.eq( index - perRow ).focus(); } - // Right arrow + // Right arrow = 39. if ( 39 === event.keyCode ) { if ( attachments.length === index ) { return; @@ -121,7 +190,7 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ attachments.eq( index + 1 ).focus(); } - // Down arrow + // Down arrow = 40. if ( 40 === event.keyCode ) { if ( Math.ceil( attachments.length / perRow ) === row ) { return; @@ -130,18 +199,29 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ } }, + /** + * Clears any set event handlers. + * + * @returns {void} + */ dispose: function() { this.collection.props.off( null, null, this ); if ( this.options.resize ) { this.$window.off( this.resizeEvent ); } - /** - * call 'dispose' directly on the parent class - */ + // Call 'dispose' directly on the parent class. View.prototype.dispose.apply( this, arguments ); }, + /** + * Calculates the amount of columns and sets it on the data-columns attribute + * of .media-frame-content. + * + * @summary Calculates the amount of columns. + * + * @returns {void} + */ setColumns: function() { var prev = this.columns, width = this.$el.width(); @@ -155,6 +235,16 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ } }, + /** + * Initializes jQuery sortable on the list if jQuery sortable exists and sortable has + * been passed to the options. + * + * @summary Initializes jQuery sortable on the list. + * + * @fires collection:reset + * + * @returns {void} + */ initSortable: function() { var collection = this.collection; @@ -166,8 +256,7 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ // If the `collection` has a `comparator`, disable sorting. disabled: !! collection.comparator, - // Change the position of the attachment as soon as the - // mouse pointer overlaps a thumbnail. + // Change the position of the attachment as soon as the mouse pointer overlaps a thumbnail. tolerance: 'pointer', // Record the initial `index` of the dragged model. @@ -175,8 +264,10 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ ui.item.data('sortableIndexStart', ui.item.index()); }, - // Update the model's index in the collection. - // Do so silently, as the view is already accurate. + /* + * Update the model's index in the collection. + * Do so silently, as the view is already accurate. + */ update: function( event, ui ) { var model = collection.at( ui.item.data('sortableIndexStart') ), comparator = collection.comparator; @@ -200,14 +291,15 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ // Fire the `reset` event to ensure other collections sync. collection.trigger( 'reset', collection ); - // If the collection is sorted by menu order, - // update the menu order. + // If the collection is sorted by menu order, update the menu order. collection.saveMenuOrder(); } }, this.options.sortable ) ); - // If the `orderby` property is changed on the `collection`, - // check to see if we have a `comparator`. If so, disable sorting. + /* + * If the `orderby` property is changed on the `collection`, + * check to see if we have a `comparator`. If so, disable sorting. + */ collection.props.on( 'change:orderby', function() { this.$el.sortable( 'option', 'disabled', !! collection.comparator ); }, this ); @@ -216,12 +308,16 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ this.refreshSortable(); }, + /** + * Disables jQuery sortable if collection has a comparator or collection.orderby equals menuOrder. + * + * @returns {void} + */ refreshSortable: function() { if ( ! this.options.sortable || ! $.fn.sortable ) { return; } - // If the `collection` has a `comparator`, disable sorting. var collection = this.collection, orderby = collection.props.get('orderby'), enabled = 'menuOrder' === orderby || ! collection.comparator; @@ -230,8 +326,11 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ }, /** + * Creates a new view for an attachment and adds it to _viewsByCid. + * * @param {wp.media.model.Attachment} attachment - * @returns {wp.media.View} + * + * @returns {wp.media.View} The created view. */ createAttachmentView: function( attachment ) { var view = new this.options.AttachmentView({ @@ -244,33 +343,51 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{ return this._viewsByCid[ attachment.cid ] = view; }, + /** + * Creates views for every attachment in collection if the collection is not empty, + * otherwise clears all views and loads more attachments. + * + * @summary Creates views for every attachment in collection. + * + * @returns {void} + */ prepare: function() { - // Create all of the Attachment views, and replace - // the list in a single DOM operation. if ( this.collection.length ) { this.views.set( this.collection.map( this.createAttachmentView, this ) ); - - // If there are no elements, clear the views and load some. } else { this.views.unset(); this.collection.more().done( this.scroll ); } }, + /** + * Triggers the scroll function to check if we should query for additional attachments right away. + * + * @returns {void} + */ ready: function() { - // Trigger the scroll event to check if we're within the - // threshold to query for additional attachments. this.scroll(); }, + /** + * Event handler for scroll events. + * Shows the spinner if we're close to the bottom. + * Loads more attachments from server if we're {refreshThreshold} times away from the bottom. + * + * @summary Event handler for scroll events. + * + * @returns {void} + */ scroll: function() { var view = this, el = this.options.scrollElement, scrollTop = el.scrollTop, toolbar; - // The scroll event occurs on the document, but the element - // that should be checked is the document body. + /* + * The scroll event occurs on the document, but the element + * that should be checked is the document body. + */ if ( el === document ) { el = document.body; scrollTop = $(document).scrollTop();