Making WordPress.org


Ignore:
Timestamp:
07/06/2016 07:16:58 PM (7 years ago)
Author:
drewapicture
Message:

developer.wordpress.org: Restructure reference pages to leverage a table of contents for the majority of the page output.

  • Splits large sections of content-reference.php into individual template parts captured via output buffering.
  • Introduces four top-level sections for any given reference page: Description, More Information (if an explanation exists), Related, and User Contributed Notes
  • Improves overall responsive styling for smaller viewports

See #1802.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/content-reference.php

    r3563 r3626  
    1515<?php if ( is_single() ) : ?>
    1616
    17     <section class="description">
    18         <?php echo get_description(); ?>
    19     </section>
     17    <?php
     18    $content = get_reference_template_parts();
    2019
    21     <?php
    22     $return = get_return();
    23     if ( ! empty( $return ) ) :
    24         ?>
    25         <section class="return"><p><strong><?php _e( 'Return:', 'wporg' ); ?></strong> <?php echo $return; ?></p></section>
    26     <?php endif; ?>
     20    // If the Handbook TOC is available, use it.
     21    if ( class_exists( 'WPorg_Handbook_TOC' ) ) :
     22        $TOC = new \WPorg_Handbook_TOC( get_parsed_post_types(), array(
     23            'header_text' => __( 'Table of Contents', 'wporg' )
     24        ) );
    2725
    28     <?php
    29     $source_file = get_source_file();
    30     if ( ! empty( $source_file ) ) :
    31         ?>
    32         <section class="source">
    33             <p>
    34                 <strong><?php _e( 'Source file:', 'wporg' ); ?></strong>
    35                 <a href="<?php echo get_source_file_archive_link( $source_file ); ?>"><?php echo esc_html( $source_file ); ?></a>
    36             </p>
    37             <?php if ( post_type_has_source_code() ) { ?>
    38             <p>
    39                 <a href="#source-code"><?php _e( 'View source', 'wporg' ); ?></a>
    40             </p>
    41             <?php } else { ?>
    42             <p>
    43                 <a href="<?php echo get_source_file_link(); ?>"><?php _e( 'View on Trac', 'wporg' ); ?></a>
    44             </p>
    45             <?php } ?>
    46         </section>
    47     <?php endif; ?>
     26        add_filter( 'the_content', array( $TOC, 'add_toc' ) );
    4827
    49     <?php if ( $params = get_params() ) : ?>
    50     <hr/>
    51     <section class="parameters">
    52         <h2><?php _e( 'Parameters', 'wporg' ); ?></h2>
    53         <dl>
    54             <?php foreach ( $params as $param ) : ?>
    55             <?php if ( ! empty( $param['variable'] ) ) : ?>
    56             <dt><?php echo esc_html( $param['variable'] ); ?></dt>
    57             <?php endif; ?>
    58             <dd>
    59                 <p class="desc">
    60                     <?php if ( ! empty( $param['types'] ) ) : ?>
    61                     <span class="type"><?php printf( __( '(%s)', 'wporg' ), wp_kses_post( $param['types'] ) ); ?></span>
    62                     <?php endif; ?>
    63                     <?php if ( ! empty( $param['required'] ) && 'wp-parser-hook' !== get_post_type() ) : ?>
    64                     <span class="required"><?php printf( __( '(%s)', 'wporg' ), esc_html( $param['required'] ) ); ?></span>
    65                     <?php endif; ?>
    66                     <?php if ( ! empty( $param['content'] ) ) : ?>
    67                     <span class="description"><?php echo wp_kses_post( $param['content'] ); ?></span>
    68                     <?php endif; ?>
    69                 </p>
    70                 <?php if ( ! empty( $param['default'] ) ) : ?>
    71                 <p class="default"><?php _e( 'Default value:', 'wporg' );?> <?php echo htmlentities( $param['default'] ); ?></p>
    72                 <?php endif; ?>
    73             </dd>
    74             <?php endforeach; ?>
    75         </dl>
    76     </section>
    77     <?php endif; ?>
     28        $content = apply_filters( 'the_content', $content );
    7829
    79     <?php
    80     $explanation = get_explanation_field( 'post_content', get_the_ID() );
    81     if ( $explanation ) :
    82         ?>
    83         <hr/>
    84         <section class="explanation">
    85             <h2><?php _e( 'More Information', 'wporg' ); ?></h2>
     30        remove_filter( 'the_content', array( $TOC, 'add_toc' ) );
     31    endif;
     32    ?>
    8633
    87             <?php
    88             // Output the explanation. Passed through 'the_content' on retrieval, thus no escaping.
    89             echo $explanation;
    90             ?>
    91         </section>
    92     <?php endif; ?>
    93 
    94     <?php /*
    95     <?php if ( $arguments = get_arguments() ) : //todo: output arg data ?>
    96     <hr/>
    97     <section class="arguments">
    98         <h2><?php _e( 'Arguments', 'wporg' ); ?></h2>
    99     </section>
    100     <?php endif; ?>
    101     <hr/>
    102     <section class="learn-more">
    103         <h2><?php _e( 'Learn More', 'wporg' ); ?></h2>
    104     </section>
    105     */ ?>
    106 
    107     <?php if ( 'wp-parser-class' === get_post_type() ) :
    108         if ( $children = get_children( array( 'post_parent' => get_the_ID(), 'post_status' => 'publish' ) ) ) :
    109             usort( $children, __NAMESPACE__ . '\\compare_objects_by_name' );
    110     ?>
    111         <hr/>
    112         <section class="class-methods">
    113         <h2><?php _e( 'Methods', 'wporg' ); ?></h2>
    114         <ul>
    115             <?php foreach ( $children as $child ) : ?>
    116                 <li><a href="<?php echo get_permalink( $child->ID ); ?>">
    117                 <?php
    118                     $title = get_the_title( $child );
    119                     $pos = ( $i = strrpos( $title, ':' ) ) ? $i + 1 : 0;
    120                     echo substr( $title, $pos );
    121                 ?></a>
    122                 <?php if ( $excerpt = apply_filters( 'get_the_excerpt', $child->post_excerpt ) ) {
    123                     echo '&mdash; ' . sanitize_text_field( $excerpt );
    124                 } ?>
    125                 <?php if ( is_deprecated( $child->ID ) ) {
    126                     echo '&mdash; <span class="deprecated-method">' . __( 'deprecated', 'wporg' ) . '</span>';
    127                 } ?>
    128                 </li>
    129             <?php endforeach; ?>
    130         </ul>
    131         </section>
    132         <?php endif;
    133     endif; ?>
    134 
    135     <?php if ( show_usage_info() ) : ?>
    136         <hr id="usage" />
    137         <section class="usage">
    138             <article class="used-by">
    139                 <h2><?php _e( 'Used by', 'wporg' ); ?></h2>
    140                 <ul>
    141                     <?php
    142                         $used_by = get_used_by();
    143                         $used_by_to_show = 5;
    144                         while ( $used_by->have_posts() ) : $used_by->the_post();
    145                             ?>
    146                             <li>
    147                                 <span><?php echo esc_attr( get_source_file() ); ?>:</span>
    148                                 <a href="<?php the_permalink(); ?>"><?php the_title(); ?><?php if ( 'wp-parser-hook' !== get_post_type() ) : ?>()<?php endif; ?></a>
    149                             </li>
    150                         <?php endwhile; wp_reset_postdata(); ?>
    151                         <?php if ( $used_by->post_count > $used_by_to_show ) : ?>
    152                             <a href="#" class="show-more"><?php
    153                                 /* translators: %d: remaining 'used by' count */
    154                                 printf( _n( 'Show %d more used by', 'Show %d more used by', $used_by->post_count - $used_by_to_show, 'wporg' ),
    155                                     number_format_i18n( $used_by->post_count - $used_by_to_show )
    156                                 );
    157                             ?></a>
    158                             <a href="#" class="hide-more"><?php _e( 'Hide more used by', 'wporg' ); ?></a>
    159                         <?php endif; ?>
    160                 </ul>
    161             </article>
    162             <?php if ( post_type_has_uses_info() ) : ?>
    163                 <article class="uses">
    164                     <h2><?php _e( 'Uses', 'wporg' ); ?></h2>
    165                     <ul>
    166                         <?php
    167                         $uses = get_uses();
    168                         $uses_to_show = 5;
    169                         while ( $uses->have_posts() ) : $uses->the_post()
    170                             ?>
    171                             <li>
    172                                 <span><?php echo esc_attr( get_source_file() ); ?>:</span>
    173                                 <a href="<?php the_permalink(); ?>"><?php the_title(); ?><?php if ( 'wp-parser-hook' !== get_post_type() ) : ?>()<?php endif; ?></a>
    174                             </li>
    175                         <?php endwhile; wp_reset_postdata(); ?>
    176                         <?php if ( $uses->post_count > $uses_to_show ) : ?>
    177                             <a href="#" class="show-more"><?php
    178                                 /* translators: %d: remaining 'uses' count */
    179                                 printf( _n( 'Show %d more use', 'Show %d more uses', $uses->post_count - $uses_to_show, 'wporg' ),
    180                                     number_format_i18n( $uses->post_count - $uses_to_show )
    181                                 );
    182                             ?></a>
    183                             <a href="#" class="hide-more"><?php _e( 'Hide more uses', 'wporg' ); ?></a>
    184                         <?php endif; ?>
    185                     </ul>
    186                 </article>
    187             <?php endif; ?>
    188         </section>
    189     <?php endif; ?>
    190 
    191     <?php if ( post_type_has_source_code() ) : ?>
    192         <hr />
    193         <a id="source-code"></a>
    194         <section class="source-content">
    195             <h2><?php _e( 'Source', 'wporg' ); ?></h2>
    196             <div class="source-code-container">
    197                 <pre class="brush: php; toolbar: false; first-line: <?php echo esc_attr( get_post_meta( get_the_ID(), '_wp-parser_line_num', true ) ); ?>"><?php echo htmlentities( get_source_code() ); ?></pre>
    198             </div>
    199             <p class="source-code-links">
    200                 <span>
    201                     <a href="#" class="show-complete-source"><?php _e( 'Expand full source code', 'wporg' ); ?></a>
    202                     <a href="#" class="less-complete-source"><?php _e( 'Collapse full source code', 'wporg' ); ?></a>
    203                 </span>
    204                 <span><a href="<?php echo get_source_file_link(); ?>"><?php _e( 'View on Trac', 'wporg' ); ?></a></span>
    205             </p>
    206         </section>
    207     <?php endif; ?>
    208 
    209     <?php
    210     $changelog_data = get_changelog_data();
    211     if ( ! empty( $changelog_data ) ) :
    212         ?>
    213         <hr/>
    214         <section class="changelog">
    215             <h2><?php _e( 'Changelog', 'wporg' ); ?></h2>
    216             <ul>
    217                 <?php foreach ( $changelog_data as $version => $data ) : ?>
    218                     <li>
    219                         <strong><?php _e( 'Since:', 'wporg' ); ?></strong>
    220                         <?php printf(
    221                             /* translators: %s: WordPress version */
    222                             __( 'WordPress %s', 'wporg' ),
    223                             sprintf( '<a href="%1$s">%2$s</a>', esc_url( $data['since_url'] ), esc_html( $version ) )
    224                         ); ?>
    225                         <?php echo $data['description']; // escaped in get_changelog_data() ?>
    226                     </li>
    227                 <?php endforeach; ?>
    228             </ul>
    229         </section>
    230     <?php endif; ?>
    231 
    232     <?php if ( comments_open() || '0' != get_comments_number() ) : ?>
    233     <hr/>
    234     <section class="user-notes">
    235         <h2><?php _e( 'User Contributed Notes', 'wporg' ); ?></h2>
    236         <?php comments_template(); /* TODO: add '/user-notes.php' */ ?>
    237     </section>
    238     <?php endif; ?>
     34    <?php echo $content; ?>
    23935
    24036<?php endif; ?>
Note: See TracChangeset for help on using the changeset viewer.