Docs: Add `wp-admin/js/media.js` documentation.

Props jipmoors, jjcomack, diedeexterkate.
Fixes #41072.

Built from https://develop.svn.wordpress.org/trunk@40915


git-svn-id: http://core.svn.wordpress.org/trunk@40765 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Peter Wilson 2017-06-15 15:37:53 +00:00
parent 952975fd0d
commit 395ff7aebe
2 changed files with 89 additions and 5 deletions

View File

@ -1,8 +1,33 @@
/* global ajaxurl, attachMediaBoxL10n, _wpMediaGridSettings, showNotice */
/**
* @summary Creates a dialog containing posts that can have a particular media attached to it.
*
* @since 2.7.0
*
* @global
* @namespace
*
* @requires jQuery
*/
var findPosts;
( function( $ ){
findPosts = {
/**
* @summary Opens a dialog to attach media to a post.
*
* Adds an overlay prior to retrieving a list of posts to attach the media to.
*
* @since 2.7.0
*
* @memberOf findPosts
*
* @param {string} af_name The name of the affected element.
* @param {string} af_val The value of the affected post element.
*
* @returns {boolean} Always returns false.
*/
open: function( af_name, af_val ) {
var overlay = $( '.ui-find-overlay' );
@ -14,35 +39,67 @@ var findPosts;
overlay.show();
if ( af_name && af_val ) {
// #affected is a hidden input field in the dialog that keeps track of which media should be attached.
$( '#affected' ).attr( 'name', af_name ).val( af_val );
}
$( '#find-posts' ).show();
// Close the dialog when the escape key is pressed.
$('#find-posts-input').focus().keyup( function( event ){
if ( event.which == 27 ) {
findPosts.close();
} // close on Escape
}
});
// Pull some results up by default
// Retrieves a list of applicable posts for media attachment and shows them.
findPosts.send();
return false;
},
/**
* @summary Clears the found posts lists before hiding the attach media dialog.
*
* @since 2.7.0
*
* @memberOf findPosts
*
* @returns {void}
*/
close: function() {
$('#find-posts-response').empty();
$('#find-posts').hide();
$( '.ui-find-overlay' ).hide();
},
/**
* @summary Binds a click event listener to the overlay which closes the attach media dialog.
*
* @since 3.5.0
*
* @memberOf findPosts
*
* @returns {void}
*/
overlay: function() {
$( '.ui-find-overlay' ).on( 'click', function () {
findPosts.close();
});
},
/**
* @summary Retrieves and displays posts based on the search term.
*
* Sends a post request to the admin_ajax.php, requesting posts based on the search term provided by the user.
* Defaults to all posts if no search term is provided.
*
* @since 2.7.0
*
* @memberOf findPosts
*
* @returns {void}
*/
send: function() {
var post = {
ps: $( '#find-posts-input' ).val(),
@ -53,6 +110,10 @@ var findPosts;
spinner.addClass( 'is-active' );
/**
* Send a POST request to admin_ajax.php, hide the spinner and replace the list of posts with the response data.
* If an error occurs, display it.
*/
$.ajax( ajaxurl, {
type: 'POST',
data: post,
@ -71,10 +132,15 @@ var findPosts;
}
};
/**
* @summary Initializes the file once the DOM is fully loaded and attaches events to the various form elements.
*
* @returns {void}
*/
$( document ).ready( function() {
var settings, $mediaGridWrap = $( '#wp-media-grid' );
// Open up a manage media frame into the grid.
// Opens a manage media frame into the grid.
if ( $mediaGridWrap.length && window.wp && window.wp.media ) {
settings = _wpMediaGridSettings;
@ -85,19 +151,33 @@ var findPosts;
}).open();
}
// Prevents form submission if no post has been selected.
$( '#find-posts-submit' ).click( function( event ) {
if ( ! $( '#find-posts-response input[type="radio"]:checked' ).length )
event.preventDefault();
});
// Submits the search query when hitting the enter key in the search input.
$( '#find-posts .find-box-search :input' ).keypress( function( event ) {
if ( 13 == event.which ) {
findPosts.send();
return false;
}
});
// Binds the click event to the search button.
$( '#find-posts-search' ).click( findPosts.send );
// Binds the close dialog click event.
$( '#find-posts-close' ).click( findPosts.close );
// Binds the bulk action events to the submit buttons.
$( '#doaction, #doaction2' ).click( function( event ) {
/*
* Retrieves all select elements for bulk actions that have a name starting with `action`
* and handle its action based on its value.
*/
$( 'select[name^="action"]' ).each( function() {
var optionValue = $( this ).val();
@ -112,7 +192,11 @@ var findPosts;
});
});
// Enable whole row to be clicked
/**
* @summary Enables clicking on the entire table row.
*
* @returns {void}
*/
$( '.find-box-inside' ).on( 'click', 'tr', function() {
$( this ).find( '.found-radio input' ).prop( 'checked', true );
});

View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '4.9-alpha-40914';
$wp_version = '4.9-alpha-40915';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.