Make WordPress Core

Changeset 40915


Ignore:
Timestamp:
06/15/2017 03:36:20 PM (7 years ago)
Author:
peterwilsoncc
Message:

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

Props jipmoors, jjcomack, diedeexterkate.
Fixes #41072.

File:
1 edited

Legend:

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

    r37859 r40915  
    11/* global ajaxurl, attachMediaBoxL10n, _wpMediaGridSettings, showNotice */
    22
     3/**
     4 * @summary Creates a dialog containing posts that can have a particular media attached to it.
     5 *
     6 * @since 2.7.0
     7 *
     8 * @global
     9 * @namespace
     10 *
     11 * @requires jQuery
     12 */
    313var findPosts;
     14
    415( function( $ ){
    516    findPosts = {
     17        /**
     18         * @summary Opens a dialog to attach media to a post.
     19         *
     20         * Adds an overlay prior to retrieving a list of posts to attach the media to.
     21         *
     22         * @since 2.7.0
     23         *
     24         * @memberOf findPosts
     25         *
     26         * @param {string} af_name The name of the affected element.
     27         * @param {string} af_val The value of the affected post element.
     28         *
     29         * @returns {boolean} Always returns false.
     30         */
    631        open: function( af_name, af_val ) {
    732            var overlay = $( '.ui-find-overlay' );
     
    1540
    1641            if ( af_name && af_val ) {
     42                // #affected is a hidden input field in the dialog that keeps track of which media should be attached.
    1743                $( '#affected' ).attr( 'name', af_name ).val( af_val );
    1844            }
     
    2046            $( '#find-posts' ).show();
    2147
     48            // Close the dialog when the escape key is pressed.
    2249            $('#find-posts-input').focus().keyup( function( event ){
    2350                if ( event.which == 27 ) {
    2451                    findPosts.close();
    25                 } // close on Escape
    26             });
    27 
    28             // Pull some results up by default
     52                }
     53            });
     54
     55            // Retrieves a list of applicable posts for media attachment and shows them.
    2956            findPosts.send();
    3057
     
    3259        },
    3360
     61        /**
     62         * @summary Clears the found posts lists before hiding the attach media dialog.
     63         *
     64         * @since 2.7.0
     65         *
     66         * @memberOf findPosts
     67         *
     68         * @returns {void}
     69         */
    3470        close: function() {
    3571            $('#find-posts-response').empty();
     
    3874        },
    3975
     76        /**
     77         * @summary Binds a click event listener to the overlay which closes the attach media dialog.
     78         *
     79         * @since 3.5.0
     80         *
     81         * @memberOf findPosts
     82         *
     83         * @returns {void}
     84         */
    4085        overlay: function() {
    4186            $( '.ui-find-overlay' ).on( 'click', function () {
     
    4489        },
    4590
     91        /**
     92         * @summary Retrieves and displays posts based on the search term.
     93         *
     94         * Sends a post request to the admin_ajax.php, requesting posts based on the search term provided by the user.
     95         * Defaults to all posts if no search term is provided.
     96         *
     97         * @since 2.7.0
     98         *
     99         * @memberOf findPosts
     100         *
     101         * @returns {void}
     102         */
    46103        send: function() {
    47104            var post = {
     
    54111            spinner.addClass( 'is-active' );
    55112
     113            /**
     114             * Send a POST request to admin_ajax.php, hide the spinner and replace the list of posts with the response data.
     115             * If an error occurs, display it.
     116             */
    56117            $.ajax( ajaxurl, {
    57118                type: 'POST',
     
    72133    };
    73134
     135    /**
     136     * @summary Initializes the file once the DOM is fully loaded and attaches events to the various form elements.
     137     *
     138     * @returns {void}
     139     */
    74140    $( document ).ready( function() {
    75141        var settings, $mediaGridWrap = $( '#wp-media-grid' );
    76142
    77         // Open up a manage media frame into the grid.
     143        // Opens a manage media frame into the grid.
    78144        if ( $mediaGridWrap.length && window.wp && window.wp.media ) {
    79145            settings = _wpMediaGridSettings;
     
    86152        }
    87153
     154        // Prevents form submission if no post has been selected.
    88155        $( '#find-posts-submit' ).click( function( event ) {
    89156            if ( ! $( '#find-posts-response input[type="radio"]:checked' ).length )
    90157                event.preventDefault();
    91158        });
     159
     160        // Submits the search query when hitting the enter key in the search input.
    92161        $( '#find-posts .find-box-search :input' ).keypress( function( event ) {
    93162            if ( 13 == event.which ) {
     
    96165            }
    97166        });
     167
     168        // Binds the click event to the search button.
    98169        $( '#find-posts-search' ).click( findPosts.send );
     170
     171        // Binds the close dialog click event.
    99172        $( '#find-posts-close' ).click( findPosts.close );
     173
     174        // Binds the bulk action events to the submit buttons.
    100175        $( '#doaction, #doaction2' ).click( function( event ) {
     176
     177            /*
     178             * Retrieves all select elements for bulk actions that have a name starting with `action`
     179             * and handle its action based on its value.
     180             */
    101181            $( 'select[name^="action"]' ).each( function() {
    102182                var optionValue = $( this ).val();
     
    113193        });
    114194
    115         // Enable whole row to be clicked
     195        /**
     196         * @summary Enables clicking on the entire table row.
     197         *
     198         * @returns {void}
     199         */
    116200        $( '.find-box-inside' ).on( 'click', 'tr', function() {
    117201            $( this ).find( '.found-radio input' ).prop( 'checked', true );
Note: See TracChangeset for help on using the changeset viewer.