WordPress.org
Get WordPress

Make WordPress Core

Ticket #25375: 25375.3.diff

File 25375.3.diff, 18.0 KB (added by kpdesign, 12 years ago)

Second pass, all @since tags completed. Minor alignment changes, fix couple typos.

  • src/wp-admin/includes/media.php

     
    2121                'library' => __('Media Library')
    2222        );
    2323
    24         return apply_filters('media_upload_tabs', $_default_tabs);
     24        /**
     25         * Filter the available tabs in the legacy (pre-3.5) media popup.
     26         *
     27         * @since 2.5.0
     28         *
     29         * @param array $_default_tabs An array of media tabs in the form of key/value pairs.
     30         */
     31        return apply_filters( 'media_upload_tabs', $_default_tabs );
    2532}
    2633
    2734/**
    … …  
    7380                elseif ( isset($_GET['tab']) && array_key_exists($_GET['tab'], $tabs) )
    7481                        $current = $_GET['tab'];
    7582                else
    76                         $current = apply_filters('media_upload_default_tab', $default);
     83                        /**
     84                         * Filter the default tab in the legacy (pre-3.5) media popup.
     85                         *
     86                         * @since 2.5.0
     87                         */
     88                        $current = apply_filters( 'media_upload_default_tab', $default );
    7789
    7890                foreach ( $tabs as $callback => $text ) {
    7991                        $class = '';
    … …  
    113125        if ( $url )
    114126                $html = '<a href="' . esc_attr($url) . "\"$rel>$html</a>";
    115127
     128        /**
     129         * Filter the image HTML markup to send to the editor.
     130         *
     131         * @since 2.5.0
     132         *
     133         * @param string $html     The image HTML markup to send.
     134         * @param int     $id        The attachment id.
     135         * @param string $caption The image caption.
     136         * @param string $title     The image title.
     137         * @param string $align    The image alignment.
     138         * @param string $url       The image source URL.
     139         * @param string $size     The image size.
     140         * @param string $alt       The image alternative, or alt, text.
     141         */
    116142        $html = apply_filters( 'image_send_to_editor', $html, $id, $caption, $title, $align, $url, $size, $alt );
    117143
    118144        return $html;
    … …  
    135161 */
    136162function image_add_caption( $html, $id, $caption, $title, $align, $url, $size, $alt = '' ) {
    137163
     164        /**
     165         * Filter whether to disable captions.
     166         *
     167         * Prevents image captions from being appended to image HTML when inserted into the editor.
     168         *
     169         * @since 2.7.0
     170         *
     171         * @param bool Whether to disable appending captions. Returning true to the filter will disable captions.
     172         *                   Default empty string.
     173         */
    138174        if ( empty($caption) || apply_filters( 'disable_captions', '' ) )
    139175                return $html;
    140176
    … …  
    156192
    157193        $shcode = '[caption id="' . $id . '" align="align' . $align     . '" width="' . $width . '"]' . $html . ' ' . $caption . '[/caption]';
    158194
     195        /**
     196         * Filter the image HTML markup including the caption shortcode.
     197         *
     198         * @since 2.6.0
     199         *
     200         * @param string $shcode The image HTML markup with caption shortcode.
     201         * @param string $html     The image HTML markup.
     202         */
    159203        return apply_filters( 'image_add_caption_shortcode', $shcode, $html );
    160204}
    161205add_filter( 'image_send_to_editor', 'image_add_caption', 20, 8 );
    … …  
    397441//]]>
    398442</script>
    399443<?php
    400 do_action('admin_enqueue_scripts', 'media-upload-popup');
    401 do_action('admin_print_styles-media-upload-popup');
    402 do_action('admin_print_styles');
    403 do_action('admin_print_scripts-media-upload-popup');
    404 do_action('admin_print_scripts');
    405 do_action('admin_head-media-upload-popup');
    406 do_action('admin_head');
     444        /**
     445         * Enqueue scripts for the admin.
     446         *
     447         * @since 2.8.0
     448         * @since 3.5.0
     449         *
     450         * @param Unknown
     451         */
     452        do_action( 'admin_enqueue_scripts', 'media-upload-popup' );
    407453
     454        /**
     455         * Prints styles enqueued for the legacy media upload popup.
     456         *
     457         * @since 2.9.0
     458         * @since 3.5.0
     459         */
     460        do_action( 'admin_print_styles-media-upload-popup' );
     461
     462        /**
     463         * Prints styles enqueued for the admin.
     464         *
     465         * @since 2.6.0
     466         */
     467        do_action( 'admin_print_styles' );
     468
     469        /**
     470         * Prints scripts enqueued for the legacy media upload popup.
     471         *
     472         * @since 2.9.0
     473         * @since 3.5.0
     474         */
     475        do_action( 'admin_print_scripts-media-upload-popup' );
     476
     477        /**
     478         * Prints scripts enqueued for the admin.
     479         *
     480         * @since 2.1.0
     481         */
     482        do_action( 'admin_print_scripts' );
     483
     484        /**
     485         * Prints scripts enqueued for the admin header for the legacy media upload popup.
     486         *
     487         * @since 2.9.0
     488         * @since 3.5.0
     489         */
     490        do_action( 'admin_head-media-upload-popup' );
     491
     492        /**
     493         * Fires in the admin header.
     494         *
     495         * @since 1.2.1
     496         */
     497        do_action( 'admin_head' );
     498
    408499if ( is_string($content_func) )
    409         do_action( "admin_head_{$content_func}" );
     500        /**
     501         * Fires in the admin header for specific media upload type forms.
     502         *
     503         * Part of the legacy (pre-3.5) media upload popup.
     504         *
     505         * The dynamic portion of the hook, $content_func, refers
     506         * to the media upload type form callback.
     507         *
     508         * @since 2.5.0
     509         */
     510do_action( "admin_head_{$content_func}" );
    410511?>
    411512</head>
    412513<body<?php if ( isset($GLOBALS['body_id']) ) echo ' id="' . $GLOBALS['body_id'] . '"'; ?> class="wp-core-ui no-js">
    … …  
    418519        $args = array_slice($args, 1);
    419520        call_user_func_array($content_func, $args);
    420521
     522        /**
     523         * Prints scripts enqueued for the admin footer.
     524         *
     525         * @since 2.8.0
     526         */
    421527        do_action('admin_print_footer_scripts');
    422528?>
    423529<script type="text/javascript">if(typeof wpOnload=='function')wpOnload();</script>
    … …  
    446552
    447553        echo '<a href="#" id="insert-media-button" class="button insert-media add_media" data-editor="' . esc_attr( $editor_id ) . '" title="' . esc_attr__( 'Add Media' ) . '">' . $img . __( 'Add Media' ) . '</a>';
    448554
    449         // Don't use this filter. Want to add a button? Use the media_buttons action.
     555        /**
     556         * Filter legacy media buttons (deprecated).
     557         *
     558         * Don't use this filter. Want to add a button? Use the 'media_buttons' action.
     559         *
     560         * @since 2.5.0
     561         * @deprecated 3.5.0
     562         *
     563         * @param string Media buttons context.
     564         */
    450565        $legacy_filter = apply_filters('media_buttons_context', ''); // deprecated
    451566
    452567        if ( $legacy_filter ) {
    … …  
    472587        if ( ! empty( $tab ) )
    473588                $upload_iframe_src = add_query_arg('tab', $tab, $upload_iframe_src);
    474589
     590        /**
     591         * Filter the upload iframe source URL by media type.
     592         *
     593         * The dynamic portion of the hook name, $type, refers to the type of media uploaded.
     594         *
     595         * @since 3.0.0
     596         *
     597         * @param string $upload_iframe_src The upload iframe source URL by type.
     598         */
    475599        $upload_iframe_src = apply_filters($type . '_upload_iframe_src', $upload_iframe_src);
    476600
    477601        return add_query_arg('TB_iframe', true, $upload_iframe_src);
    … …  
    514638                                $post['post_parent'] = $attachment['post_parent'];
    515639                }
    516640
     641                /**
     642                 * Filter attachment fields to be saved.
     643                 *
     644                 * @since 2.5.0
     645                 *
     646                 * @param WP_Post $post           The WP_Post object.
     647                 * @param array      $attachment An array of attachment metadata.
     648                 */
    517649                $post = apply_filters('attachment_fields_to_save', $post, $attachment);
    518650
    519651                if ( isset($attachment['image_alt']) ) {
    … …  
    561693                        $html = "<a href='{$attachment['url']}'$rel>$html</a>";
    562694                }
    563695
     696                /**
     697                 * Filter the media HTML markup sent to the editor.
     698                 *
     699                 * @since 2.5.0
     700                 *
     701                 * @param string $html           The media's HTML markup sent to the editor.
     702                 * @param int     $send_id       The first key from the $_POST['send'] data.
     703                 * @param array  $attachment The attachment metadata.
     704                 */
    564705                $html = apply_filters('media_send_to_editor', $html, $send_id, $attachment);
    565706                return media_send_to_editor($html);
    566707        }
    … …  
    608749                                && ( 'audio' == $ext_type || 'video' == $ext_type ) )
    609750                                        $type = $ext_type;
    610751
     752                        /**
     753                         * Filter the media URL sent to the editor by type.
     754                         *
     755                         * The dynamic portion of the hook name, $type, refers to the type of media being sent.
     756                         *
     757                         * @since 3.3.0
     758                         *
     759                         * @param string $html  The HTML markup sent to the editor.
     760                         * @param string $src   The media source URL.
     761                         * @param string $title  The media title.
     762                         */
    611763                        $html = apply_filters( $type . '_send_to_editor_url', $html, esc_url_raw( $src ), $title );
    612764                } else {
    613765                        $align = '';
    … …  
    779931function image_size_input_fields( $post, $check = '' ) {
    780932
    781933                // get a list of the actual pixel dimensions of each possible intermediate version of this image
    782                 $size_names = apply_filters( 'image_size_names_choose', array('thumbnail' => __('Thumbnail'), 'medium' => __('Medium'), 'large' => __('Large'), 'full' => __('Full Size')) );
     934                $size_names = array(
     935                        'thumbnail' => __( 'Thumbnail' ),
     936                        'medium'    => __( 'Medium' ),
     937                        'large'     => __( 'Large' ),
     938                        'full'      => __( 'Full Size' )
     939                );
    783940
     941                /**
     942                 * Filter the names of the default image sizes.
     943                 *
     944                 * @since 3.3.0
     945                 *
     946                 * @param array $size_names An array of image sizes and their names.
     947                 */
     948                $size_names = apply_filters( 'image_size_names_choose', $size_names );
     949
    784950                if ( empty($check) )
    785951                        $check = get_user_setting('imgsize', 'medium');
    786952
    … …  
    10611227                unset( $form_fields['image_alt'] );
    10621228        }
    10631229
     1230        /**
     1231         * Filter the attachment fields to edit.
     1232         *
     1233         * @since 2.5.0
     1234         *
     1235         * @param array      $form_fields An array of attachment form fields.
     1236         * @param WP_Post $post          The WP_Post attachment object.
     1237         */
    10641238        $form_fields = apply_filters('attachment_fields_to_edit', $form_fields, $post);
    10651239
    10661240        return $form_fields;
    … …  
    11261300
    11271301        $default_args = array( 'errors' => null, 'send' => $current_post_id ? post_type_supports( get_post_type( $current_post_id ), 'editor' ) : true, 'delete' => true, 'toggle' => true, 'show_title' => true );
    11281302        $args = wp_parse_args( $args, $default_args );
     1303
     1304        /**
     1305         * Filter the arguments used to get an image for the edit image form.
     1306         *
     1307         * @since 3.1.0
     1308         *
     1309         * @param array $args An array of arguments. @see get_media_item()
     1310         */
    11291311        $args = apply_filters( 'get_media_item_args', $args );
    11301312        extract( $args, EXTR_SKIP );
    11311313
    … …  
    11801362        $meta = wp_get_attachment_metadata( $post->ID );
    11811363        if ( isset( $meta['width'], $meta['height'] ) )
    11821364                $media_dims .= "<span id='media-dims-$post->ID'>{$meta['width']}&nbsp;&times;&nbsp;{$meta['height']}</span> ";
     1365
     1366        /**
     1367         * Filter the media metadata.
     1368         *
     1369         * @since 2.5.0
     1370         *
     1371         * @param string     $media_dims The HTML markup containing the media dimensions.
     1372         * @param WP_Post $post          The WP_Post attachment object.
     1373         */
    11831374        $media_dims = apply_filters( 'media_meta', $media_dims, $post );
    11841375
    11851376        $image_edit_button = '';
    … …  
    13431534        $user_can_edit = current_user_can( 'edit_post', $attachment_id );
    13441535
    13451536        $args = wp_parse_args( $args, $default_args );
     1537
     1538        //duplicate_hook
    13461539        $args = apply_filters( 'get_media_item_args', $args );
    13471540
    13481541        $form_fields = array();
    … …  
    13761569        // The recursive merge is easily traversed with array casting: foreach( (array) $things as $thing )
    13771570        $form_fields = array_merge_recursive($form_fields, (array) $args['errors'] );
    13781571
     1572        //duplicate_hook
    13791573        $form_fields = apply_filters( 'attachment_fields_to_edit', $form_fields, $post );
    13801574
    13811575        unset( $form_fields['image-size'], $form_fields['align'], $form_fields['image_alt'],
    … …  
    13821576                $form_fields['post_title'], $form_fields['post_excerpt'], $form_fields['post_content'],
    13831577                $form_fields['url'], $form_fields['menu_order'], $form_fields['image_url'] );
    13841578
     1579        //duplicate_hook
    13851580        $media_meta = apply_filters( 'media_meta', '', $post );
    13861581
    13871582        $defaults = array(
    … …  
    15451740        return;
    15461741}
    15471742
    1548 do_action('pre-upload-ui');
     1743/**
     1744 * Fires just before the legacy (pre-3.5) upload interface is loaded.
     1745 *
     1746 * @since 2.6.0
     1747 */
     1748do_action( 'pre-upload-ui' );
    15491749
    15501750$post_params = array(
    15511751                "post_id" => $post_id,
    … …  
    15551755                "short" => "1",
    15561756);
    15571757
    1558 $post_params = apply_filters( 'upload_post_params', $post_params ); // hook change! old name: 'swfupload_post_params'
     1758/**
     1759 * Filter the media upload post parameters.
     1760 *
     1761 * Previously 'swfupload_post_params'.
     1762 *
     1763 * @since 3.3.0
     1764 * @since 3.5.0
     1765 *
     1766 * @param array $post_params An array of media upload parameters used by Plupload.
     1767 */
     1768$post_params = apply_filters( 'upload_post_params', $post_params );
    15591769
    15601770$plupload_init = array(
    15611771        'runtimes' => 'html5,silverlight,flash,html4',
    … …  
    15791789if ( wp_is_mobile() )
    15801790        $plupload_init['multi_selection'] = false;
    15811791
     1792/**
     1793 * Filter the default Plupload settings.
     1794 *
     1795 * @since 3.3.0
     1796 *
     1797 * @param array $plupload_init An array of default settings used by Plupload.
     1798 */
    15821799$plupload_init = apply_filters( 'plupload_init', $plupload_init );
    15831800
    15841801?>
    … …  
    15981815</script>
    15991816
    16001817<div id="plupload-upload-ui" class="hide-if-no-js">
    1601 <?php do_action('pre-plupload-upload-ui'); // hook change, old name: 'pre-flash-upload-ui' ?>
     1818<?php
     1819/**
     1820 * Fires before the upload interface loads.
     1821 *
     1822 * Previously named 'pre-flash-upload-ui'.
     1823 *
     1824 * @since 3.3.0
     1825 * @since 3.5.0
     1826 */
     1827do_action('pre-plupload-upload-ui'); // hook change, old name: 'pre-flash-upload-ui' ?>
    16021828<div id="drag-drop-area">
    16031829        <div class="drag-drop-inside">
    16041830        <p class="drag-drop-info"><?php _e('Drop files here'); ?></p>
    … …  
    16061832        <p class="drag-drop-buttons"><input id="plupload-browse-button" type="button" value="<?php esc_attr_e('Select Files'); ?>" class="button" /></p>
    16071833        </div>
    16081834</div>
    1609 <?php do_action('post-plupload-upload-ui'); // hook change, old name: 'post-flash-upload-ui' ?>
     1835<?php
     1836/**
     1837 * Fires after the upload interface loads.
     1838 *
     1839 * Previously named 'post-flash-upload-ui'.
     1840 *
     1841 * @since 3.3.0
     1842 * @since 3.5.0
     1843 */
     1844do_action( 'post-plupload-upload-ui' ); ?>
    16101845</div>
    16111846
    16121847<div id="html-upload-ui" class="hide-if-js">
    1613 <?php do_action('pre-html-upload-ui'); ?>
     1848        <?php
     1849        /**
     1850         * Fires before the upload button in the media upload interface.
     1851         *
     1852         * @since 2.6.0
     1853         */
     1854        do_action( 'pre-html-upload-ui' );
     1855        ?>
    16141856        <p id="async-upload-wrap">
    16151857                <label class="screen-reader-text" for="async-upload"><?php _e('Upload'); ?></label>
    16161858                <input type="file" name="async-upload" id="async-upload" />
    … …  
    16181860                <a href="#" onclick="try{top.tb_remove();}catch(e){}; return false;"><?php _e('Cancel'); ?></a>
    16191861        </p>
    16201862        <div class="clear"></div>
    1621 <?php do_action('post-html-upload-ui'); ?>
     1863<?php
     1864/**
     1865 * Fires after the upload button in the media upload interface.
     1866 *
     1867 * @since 2.6.0
     1868 */
     1869do_action( 'post-html-upload-ui' );
     1870?>
    16221871</div>
    16231872
    16241873<span class="max-upload-size"><?php printf( __( 'Maximum upload file size: %d%s.' ), esc_html($upload_size_unit), esc_html($sizes[$u]) ); ?></span>
    … …  
    16271876        <span class="big-file-warning"><?php _e('Your browser has some limitations uploading large files with the multi-file uploader. Please use the browser uploader for files over 100MB.'); ?></span>
    16281877<?php }
    16291878
    1630         do_action('post-upload-ui');
     1879        /**
     1880         * Fires on the post upload UI screen.
     1881         *
     1882         * Legacy (pre-3.5) media workflow hook.
     1883         *
     1884         * @since 2.6.0
     1885         * @since 3.5.0
     1886         */
     1887        do_action( 'post-upload-ui' );
    16311888}
    16321889
    16331890/**
    … …  
    16461903        $post_id = isset( $_REQUEST['post_id'] )? intval( $_REQUEST['post_id'] ) : 0;
    16471904
    16481905        $form_action_url = admin_url("media-upload.php?type=$type&tab=type&post_id=$post_id");
     1906
     1907        /**
     1908         * Filter the media upload form action URL.
     1909         *
     1910         * @since 2.6.0
     1911         *
     1912         * @param string $form_action_url The media upload form action URL.
     1913         * @param string $type                The type of media. Default 'file'.
     1914         */
    16491915        $form_action_url = apply_filters('media_upload_form_url', $form_action_url, $type);
    16501916        $form_class = 'media-upload-form type-form validate';
    16511917
    … …  
    17111977        $post_id = isset( $_REQUEST['post_id'] ) ? intval( $_REQUEST['post_id'] ) : 0;
    17121978
    17131979        $form_action_url = admin_url("media-upload.php?type=$type&tab=type&post_id=$post_id");
     1980        //duplicate_hook
    17141981        $form_action_url = apply_filters('media_upload_form_url', $form_action_url, $type);
    17151982        $form_class = 'media-upload-form type-form validate';
    17161983
    … …  
    17412008                if ( f.alt.value )
    17422009                        alt = f.alt.value.replace(/'/g, '&#039;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
    17432010
    1744 <?php if ( ! apply_filters( 'disable_captions', '' ) ) { ?>
     2011<?php
     2012        //duplicate_hook
     2013        if ( ! apply_filters( 'disable_captions', '' ) ) {
     2014                ?>
    17452015                if ( f.caption.value ) {
    17462016                        caption = f.caption.value.replace(/\r\n|\r/g, '\n');
    17472017                        caption = caption.replace(/<[a-zA-Z0-9]+( [^<>]+)?>/g, function(a){
    … …  
    18182088
    18192089<div id="media-items">
    18202090<div class="media-item media-blank">
    1821 <?php echo apply_filters( 'type_url_form_media', wp_media_insert_url_form( $type ) ); ?>
     2091<?php
     2092$form_html = wp_media_insert_url_form( $type );
     2093/**
     2094 * Filter the insert from URL form HTML.
     2095 *
     2096 * @since 3.3.0
     2097 *
     2098 * @param string $form_html The insert from URL form HTML.
     2099 */
     2100echo apply_filters( 'type_url_form_media', $form_html );
     2101?>
    18222102</div>
    18232103</div>
    18242104</form>
    … …  
    18402120
    18412121        $post_id = intval($_REQUEST['post_id']);
    18422122        $form_action_url = admin_url("media-upload.php?type=$type&tab=gallery&post_id=$post_id");
     2123        //duplicate_hook
    18432124        $form_action_url = apply_filters('media_upload_form_url', $form_action_url, $type);
    18442125        $form_class = 'media-upload-form validate';
    18452126
    … …  
    19862267        $post_id = isset( $_REQUEST['post_id'] ) ? intval( $_REQUEST['post_id'] ) : 0;
    19872268
    19882269        $form_action_url = admin_url("media-upload.php?type=$type&tab=library&post_id=$post_id");
     2270        //duplicate_hook
    19892271        $form_action_url = apply_filters('media_upload_form_url', $form_action_url, $type);
    19902272        $form_class = 'media-upload-form validate';
    19912273
    … …  
    20492331
    20502332        $type_links[] = "<li><a href='" . esc_url(add_query_arg(array('post_mime_type'=>$mime_type, 'paged'=>false))) . "'$class>" . sprintf( translate_nooped_plural( $label[2], $num_posts[$mime_type] ), "<span id='$mime_type-counter'>" . number_format_i18n( $num_posts[$mime_type] ) . '</span>') . '</a>';
    20512333}
     2334/**
     2335 * Filter the media upload mime type list items.
     2336 *
     2337 * @since 3.1.0
     2338 *
     2339 * @param array $type_links An array of list items containing mime type link HTML.
     2340 */
    20522341echo implode(' | </li>', apply_filters( 'media_upload_mime_type_links', $type_links ) ) . '</li>';
    20532342unset($type_links);
    20542343?>
    … …  
    21482437 * @return string the form html
    21492438 */
    21502439function wp_media_insert_url_form( $default_view = 'image' ) {
     2440        //duplicate_hook
    21512441        if ( !apply_filters( 'disable_captions', '' ) ) {
    21522442                $caption = '
    21532443                <tr class="image-only">
    … …  
    24302720        $meta = wp_get_attachment_metadata( $post->ID );
    24312721        if ( isset( $meta['width'], $meta['height'] ) )
    24322722                $media_dims .= "<span id='media-dims-$post->ID'>{$meta['width']}&nbsp;&times;&nbsp;{$meta['height']}</span> ";
     2723        //duplicate_hook
    24332724        $media_dims = apply_filters( 'media_meta', $media_dims, $post );
    24342725
    24352726        $att_url = wp_get_attachment_url( $post->ID );