WordPress.org

WordPress build repository browser

Changeset 40765


Ignore:
Timestamp:
06/15/17 15:37:53 (2 months ago)
Author:
peterwilsoncc
Message:

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

Props jipmoors, jjcomack, diedeexterkate.
Fixes #41072.

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

Location:
trunk
Files:
2 edited

Legend:

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

    r37811 r40765  
    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 ); 
  • trunk/wp-includes/version.php

    r40764 r40765  
    55 * @global string $wp_version 
    66 */ 
    7 $wp_version = '4.9-alpha-40914'; 
     7$wp_version = '4.9-alpha-40915'; 
    88 
    99/** 
Note: See TracChangeset for help on using the changeset viewer.