WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
01/29/2020 12:43:23 AM (6 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/theme-editor.php

    r45932 r47122  
    118118$edit_error     = null;
    119119$posted_content = null;
     120
    120121if ( 'POST' === $_SERVER['REQUEST_METHOD'] ) {
    121122        $r = wp_edit_theme_plugin_file( wp_unslash( $_POST ) );
    … …  
    140141}
    141142
    142         $settings = array(
    143                 'codeEditor' => wp_enqueue_code_editor( compact( 'file' ) ),
    144         );
    145         wp_enqueue_script( 'wp-theme-plugin-editor' );
    146         wp_add_inline_script( 'wp-theme-plugin-editor', sprintf( 'jQuery( function( $ ) { wp.themePluginEditor.init( $( "#template" ), %s ); } )', wp_json_encode( $settings ) ) );
    147         wp_add_inline_script( 'wp-theme-plugin-editor', 'wp.themePluginEditor.themeOrPlugin = "theme";' );
    148 
    149         require_once( ABSPATH . 'wp-admin/admin-header.php' );
    150 
    151         update_recently_edited( $file );
    152 
    153         if ( ! is_file( $file ) ) {
    154                 $error = true;
     143$settings = array(
     144        'codeEditor' => wp_enqueue_code_editor( compact( 'file' ) ),
     145);
     146wp_enqueue_script( 'wp-theme-plugin-editor' );
     147wp_add_inline_script( 'wp-theme-plugin-editor', sprintf( 'jQuery( function( $ ) { wp.themePluginEditor.init( $( "#template" ), %s ); } )', wp_json_encode( $settings ) ) );
     148wp_add_inline_script( 'wp-theme-plugin-editor', 'wp.themePluginEditor.themeOrPlugin = "theme";' );
     149
     150require_once( ABSPATH . 'wp-admin/admin-header.php' );
     151
     152update_recently_edited( $file );
     153
     154if ( ! is_file( $file ) ) {
     155        $error = true;
     156}
     157
     158$content = '';
     159if ( ! empty( $posted_content ) ) {
     160        $content = $posted_content;
     161} elseif ( ! $error && filesize( $file ) > 0 ) {
     162        $f       = fopen( $file, 'r' );
     163        $content = fread( $f, filesize( $file ) );
     164
     165        if ( '.php' == substr( $file, strrpos( $file, '.' ) ) ) {
     166                $functions = wp_doc_link_parse( $content );
     167
     168                $docs_select  = '<select name="docs-list" id="docs-list">';
     169                $docs_select .= '<option value="">' . esc_attr__( 'Function Name&hellip;' ) . '</option>';
     170                foreach ( $functions as $function ) {
     171                        $docs_select .= '<option value="' . esc_attr( urlencode( $function ) ) . '">' . htmlspecialchars( $function ) . '()</option>';
     172                }
     173                $docs_select .= '</select>';
    155174        }
    156175
    157         $content = '';
    158         if ( ! empty( $posted_content ) ) {
    159                 $content = $posted_content;
    160         } elseif ( ! $error && filesize( $file ) > 0 ) {
    161                 $f       = fopen( $file, 'r' );
    162                 $content = fread( $f, filesize( $file ) );
    163 
    164                 if ( '.php' == substr( $file, strrpos( $file, '.' ) ) ) {
    165                         $functions = wp_doc_link_parse( $content );
    166 
    167                         $docs_select  = '<select name="docs-list" id="docs-list">';
    168                         $docs_select .= '<option value="">' . esc_attr__( 'Function Name&hellip;' ) . '</option>';
    169                         foreach ( $functions as $function ) {
    170                                 $docs_select .= '<option value="' . esc_attr( urlencode( $function ) ) . '">' . htmlspecialchars( $function ) . '()</option>';
    171                         }
    172                         $docs_select .= '</select>';
    173                 }
    174 
    175                 $content = esc_textarea( $content );
    176         }
    177 
    178         $file_description = get_file_description( $relative_file );
    179         $file_show        = array_search( $file, array_filter( $allowed_files ) );
    180         $description      = esc_html( $file_description );
    181         if ( $file_description != $file_show ) {
    182                 $description .= ' <span>(' . esc_html( $file_show ) . ')</span>';
    183         }
    184         ?>
     176        $content = esc_textarea( $content );
     177}
     178
     179$file_description = get_file_description( $relative_file );
     180$file_show        = array_search( $file, array_filter( $allowed_files ) );
     181$description      = esc_html( $file_description );
     182if ( $file_description != $file_show ) {
     183        $description .= ' <span>(' . esc_html( $file_show ) . ')</span>';
     184}
     185?>
    185186<div class="wrap">
    186187<h1><?php echo esc_html( $title ); ?></h1>
    … …  
    196197        </div>
    197198<?php endif; ?>
     199
    198200<?php if ( preg_match( '/\.css$/', $file ) ) : ?>
    199201        <div id="message" class="notice-info notice">
    … …  
    214216<div class="alignleft">
    215217<h2>
    216 <?php
    217 echo $theme->display( 'Name' );
    218 if ( $description ) {
    219         echo ': ' . $description;}
    220 ?>
     218        <?php
     219        echo $theme->display( 'Name' );
     220        if ( $description ) {
     221                echo ': ' . $description;}
     222        ?>
    221223</h2>
    222224</div>
    … …  
    225227                <strong><label for="theme"><?php _e( 'Select theme to edit:' ); ?> </label></strong>
    226228                <select name="theme" id="theme">
    227 <?php
    228 foreach ( wp_get_themes( array( 'errors' => null ) ) as $a_stylesheet => $a_theme ) {
    229         if ( $a_theme->errors() && 'theme_no_stylesheet' == $a_theme->errors()->get_error_code() ) {
    230                 continue;
    231         }
    232 
    233         $selected = $a_stylesheet == $stylesheet ? ' selected="selected"' : '';
    234         echo "\n\t" . '<option value="' . esc_attr( $a_stylesheet ) . '"' . $selected . '>' . $a_theme->display( 'Name' ) . '</option>';
    235 }
    236 ?>
     229                <?php
     230                foreach ( wp_get_themes( array( 'errors' => null ) ) as $a_stylesheet => $a_theme ) {
     231                        if ( $a_theme->errors() && 'theme_no_stylesheet' == $a_theme->errors()->get_error_code() ) {
     232                                continue;
     233                        }
     234
     235                        $selected = $a_stylesheet == $stylesheet ? ' selected="selected"' : '';
     236                        echo "\n\t" . '<option value="' . esc_attr( $a_stylesheet ) . '"' . $selected . '>' . $a_theme->display( 'Name' ) . '</option>';
     237                }
     238                ?>
    237239                </select>
    238240                <?php submit_button( __( 'Select' ), '', 'Submit', false ); ?>
    … …  
    241243<br class="clear" />
    242244</div>
     245
    243246<?php
    244247if ( $theme->errors() ) {
    … …  
    246249}
    247250?>
     251
    248252<div id="templateside">
    249253        <h2 id="theme-files-label"><?php _e( 'Theme Files' ); ?></h2>
    … …  
    286290                        <input type="hidden" name="theme" value="<?php echo esc_attr( $theme->get_stylesheet() ); ?>" />
    287291                </div>
    288         <?php if ( ! empty( $functions ) ) : ?>
    289                 <div id="documentation" class="hide-if-no-js">
    290                 <label for="docs-list"><?php _e( 'Documentation:' ); ?></label>
    291                 <?php echo $docs_select; ?>
    292                 <input disabled id="docs-lookup" type="button" class="button" value="<?php esc_attr_e( 'Look Up' ); ?>" onclick="if ( '' != jQuery('#docs-list').val() ) { window.open( 'https://api.wordpress.org/core/handbook/1.0/?function=' + escape( jQuery( '#docs-list' ).val() ) + '&amp;locale=<?php echo urlencode( get_user_locale() ); ?>&amp;version=<?php echo urlencode( get_bloginfo( 'version' ) ); ?>&amp;redirect=true'); }" />
    293                 </div>
    294         <?php endif; ?>
    295 
    296         <div>
    297                 <div class="editor-notices">
    298                         <?php if ( is_child_theme() && $theme->get_stylesheet() == get_template() ) : ?>
    299                                 <div class="notice notice-warning inline">
    300                                         <p>
    301                                                 <?php
    302                                                 if ( is_writeable( $file ) ) {
    303                                                         ?>
    304                                                 <strong><?php _e( 'Caution:' ); ?></strong><?php } ?>
    305                                                 <?php _e( 'This is a file in your current parent theme.' ); ?>
    306                                         </p>
    307                                 </div>
     292
     293                <?php if ( ! empty( $functions ) ) : ?>
     294                        <div id="documentation" class="hide-if-no-js">
     295                                <label for="docs-list"><?php _e( 'Documentation:' ); ?></label>
     296                                <?php echo $docs_select; ?>
     297                                <input disabled id="docs-lookup" type="button" class="button" value="<?php esc_attr_e( 'Look Up' ); ?>" onclick="if ( '' != jQuery('#docs-list').val() ) { window.open( 'https://api.wordpress.org/core/handbook/1.0/?function=' + escape( jQuery( '#docs-list' ).val() ) + '&amp;locale=<?php echo urlencode( get_user_locale() ); ?>&amp;version=<?php echo urlencode( get_bloginfo( 'version' ) ); ?>&amp;redirect=true'); }" />
     298                        </div>
     299                <?php endif; ?>
     300
     301                <div>
     302                        <div class="editor-notices">
     303                                <?php if ( is_child_theme() && $theme->get_stylesheet() == get_template() ) : ?>
     304                                        <div class="notice notice-warning inline">
     305                                                <p>
     306                                                        <?php if ( is_writeable( $file ) ) : ?>
     307                                                                <strong><?php _e( 'Caution:' ); ?></strong>
     308                                                        <?php endif; ?>
     309                                                        <?php _e( 'This is a file in your current parent theme.' ); ?>
     310                                                </p>
     311                                        </div>
     312                                <?php endif; ?>
     313                        </div>
     314                        <?php if ( is_writeable( $file ) ) : ?>
     315                                <p class="submit">
     316                                        <?php submit_button( __( 'Update File' ), 'primary', 'submit', false ); ?>
     317                                        <span class="spinner"></span>
     318                                </p>
     319                        <?php else : ?>
     320                                <p><em>
     321                                        <?php
     322                                        printf(
     323                                                /* translators: %s: Documentation URL. */
     324                                                __( 'You need to make this file writable before you can save your changes. See <a href="%s">Changing File Permissions</a> for more information.' ),
     325                                                __( 'https://wordpress.org/support/article/changing-file-permissions/' )
     326                                        );
     327                                        ?>
     328                                </em></p>
    308329                        <?php endif; ?>
    309330                </div>
    310         <?php if ( is_writeable( $file ) ) : ?>
    311                 <p class="submit">
    312                         <?php submit_button( __( 'Update File' ), 'primary', 'submit', false ); ?>
    313                         <span class="spinner"></span>
    314                 </p>
    315         <?php else : ?>
    316                 <p><em>
    317                         <?php
    318                         printf(
    319                                 /* translators: %s: Documentation URL. */
    320                                 __( 'You need to make this file writable before you can save your changes. See <a href="%s">Changing File Permissions</a> for more information.' ),
    321                                 __( 'https://wordpress.org/support/article/changing-file-permissions/' )
    322                         );
    323                         ?>
    324                 </em></p>
    325         <?php endif; ?>
    326         </div>
    327         <?php wp_print_file_editor_templates(); ?>
     331
     332                <?php wp_print_file_editor_templates(); ?>
    328333        </form>
    329334        <?php
    330 endif; // $error
     335endif; // End if $error.
    331336?>
    332337<br class="clear" />
    … …  
    335340$dismissed_pointers = explode( ',', (string) get_user_meta( get_current_user_id(), 'dismissed_wp_pointers', true ) );
    336341if ( ! in_array( 'theme_editor_notice', $dismissed_pointers, true ) ) :
    337         // Get a back URL
    338         $referer                    = wp_get_referer();
     342        // Get a back URL.
     343        $referer = wp_get_referer();
     344
    339345        $excluded_referer_basenames = array( 'theme-editor.php', 'wp-login.php' );
    340346
    … …  
    345351        }
    346352        ?>
    347 <div id="file-editor-warning" class="notification-dialog-wrap file-editor-warning hide-if-no-js hidden">
    348         <div class="notification-dialog-background"></div>
    349         <div class="notification-dialog">
    350                 <div class="file-editor-warning-content">
    351                         <div class="file-editor-warning-message">
    352                                 <h1><?php _e( 'Heads up!' ); ?></h1>
     353        <div id="file-editor-warning" class="notification-dialog-wrap file-editor-warning hide-if-no-js hidden">
     354                <div class="notification-dialog-background"></div>
     355                <div class="notification-dialog">
     356                        <div class="file-editor-warning-content">
     357                                <div class="file-editor-warning-message">
     358                                        <h1><?php _e( 'Heads up!' ); ?></h1>
     359                                        <p>
     360                                                <?php
     361                                                _e( 'You appear to be making direct edits to your theme in the WordPress dashboard. We recommend that you don&#8217;t! Editing your theme directly could break your site and your changes may be lost in future updates.' );
     362                                                ?>
     363                                        </p>
     364                                                <?php
     365                                                if ( ! $theme->parent() ) {
     366                                                        echo '<p>';
     367                                                        echo sprintf(
     368                                                                /* translators: %s: Link to documentation on child themes. */
     369                                                                __( 'If you need to tweak more than your theme&#8217;s CSS, you might want to try <a href="%s">making a child theme</a>.' ),
     370                                                                esc_url( __( 'https://developer.wordpress.org/themes/advanced-topics/child-themes/' ) )
     371                                                        );
     372                                                        echo '</p>';
     373                                                }
     374                                                ?>
     375                                        <p><?php _e( 'If you decide to go ahead with direct edits anyway, use a file manager to create a copy with a new name and hang on to the original. That way, you can re-enable a functional version if something goes wrong.' ); ?></p>
     376                                </div>
    353377                                <p>
    354                                         <?php
    355                                         _e( 'You appear to be making direct edits to your theme in the WordPress dashboard. We recommend that you don&#8217;t! Editing your theme directly could break your site and your changes may be lost in future updates.' );
    356                                         ?>
     378                                        <a class="button file-editor-warning-go-back" href="<?php echo esc_url( $return_url ); ?>"><?php _e( 'Go back' ); ?></a>
     379                                        <button type="button" class="file-editor-warning-dismiss button button-primary"><?php _e( 'I understand' ); ?></button>
    357380                                </p>
    358                                         <?php
    359                                         if ( ! $theme->parent() ) {
    360                                                 echo '<p>';
    361                                                 echo sprintf(
    362                                                         /* translators: %s: Link to documentation on child themes. */
    363                                                         __( 'If you need to tweak more than your theme&#8217;s CSS, you might want to try <a href="%s">making a child theme</a>.' ),
    364                                                         esc_url( __( 'https://developer.wordpress.org/themes/advanced-topics/child-themes/' ) )
    365                                                 );
    366                                                 echo '</p>';
    367                                         }
    368                                         ?>
    369                                 <p><?php _e( 'If you decide to go ahead with direct edits anyway, use a file manager to create a copy with a new name and hang on to the original. That way, you can re-enable a functional version if something goes wrong.' ); ?></p>
    370381                        </div>
    371                         <p>
    372                                 <a class="button file-editor-warning-go-back" href="<?php echo esc_url( $return_url ); ?>"><?php _e( 'Go back' ); ?></a>
    373                                 <button type="button" class="file-editor-warning-dismiss button button-primary"><?php _e( 'I understand' ); ?></button>
    374                         </p>
    375382                </div>
    376383        </div>
    377 </div>
    378384        <?php
    379 endif; // editor warning notice
     385endif; // Editor warning notice.
    380386
    381387include( ABSPATH . 'wp-admin/admin-footer.php' );
Note: See TracChangeset for help on using the changeset viewer.