WordPress.org
Get WordPress

Making WordPress.org

Changeset 3626


Ignore:
Timestamp:
07/06/2016 07:16:58 PM (8 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.

Location:
sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer
Files:
10 added
4 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; ?>

  • sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php

    r3563 r3626  
    550550            $delimiter = false !== strpos( $signature, '$' ) ? '"' : "'";
    551551            $signature = $delimiter . $signature . $delimiter;
    552             $signature = '<span class="hook-func">' . $hook_type . '</span> ( ' . $signature;
     552            $signature = '<span class="hook-func">' . $hook_type . '</span>( ' . $signature;
    553553            if ( $hook_args ) {
    554554                $signature .= ', ';
    … …  
    580580        }
    581581
    582         $signature .= ' (';
     582        $signature .= '(';
    583583        if ( $args = implode( ', ', $args_strings ) ) {
    584584            $signature .= $args . '&nbsp;';
    … …  
    13211321        $post_field = get_post_field( $field, $explanation, $context );
    13221322
    1323         // If retrieving the explanation content for display, add the TOC if available.
    1324         if ( 'post_content' === $field && 'display' === $context ) {
    1325             if ( class_exists( 'WPorg_Handbook_TOC' ) ) :
    1326                 $TOC = new \WPorg_Handbook_TOC( get_parsed_post_types() );
    1327 
    1328                 add_filter( 'the_content', array( $TOC, 'add_toc' ) );
    1329                 $post_field = apply_filters( 'the_content', apply_filters( 'get_the_content', $post_field ) );
    1330                 remove_filter( 'the_content', array( $TOC, 'add_toc' ) );
    1331             else :
    1332                 $post_field = apply_filters( 'the_content', apply_filters( 'get_the_content', $post_field ) );
    1333             endif;
    1334         }
    1335 
    1336         return $post_field;
     1323        return apply_filters( 'the_content', apply_filters( 'get_the_content', $post_field ) );
    13371324    }
    13381325
    … …  
    14401427        echo $form;
    14411428    }
     1429
     1430    /**
     1431     * Retrieves all content for reference template parts.
     1432     *
     1433     * @return string Template part markup retrieved via output buffering.
     1434     */
     1435    function get_reference_template_parts() {
     1436        // Order dictates order of display.
     1437        $templates = array(
     1438            'description',
     1439            'params',
     1440            'return',
     1441            'source',
     1442            'changelog',
     1443            'explanation',
     1444            'related',
     1445            'methods',
     1446            'notes'
     1447        );
     1448
     1449        ob_start();
     1450
     1451        foreach ( $templates as $part ) {
     1452            get_template_part( 'reference/template', $part );
     1453        }
     1454
     1455        return ob_get_clean();
     1456    }
    14421457}
    1443 

  • sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/scss/main.scss

    r3564 r3626  
    10571057            width: 300px;
    10581058        }
     1059        .toc-jump {
     1060            display: inline-block;
     1061            float: right;
     1062        }
    10591063    }
    10601064
    … …  
    10881092    ----------------------------------------------- */
    10891093    .usage {
    1090         article {
    1091             float: left;
    1092             width: 50%;
    1093         }
    1094 
    1095         .used-by {
    1096             padding-right: 30px;
    1097         }
    1098 
    1099         .uses {
    1100             padding-left: 30px;
    1101         }
    1102 
    11031094        ul {
    11041095            line-height: 1.7; /* Slightly increase the line height for more readability */
    … …  
    14291420        li {
    14301421            padding-bottom: 6px !important;
     1422            font-weight: 600;
    14311423
    14321424            ul li,
    14331425            ul li ul li {
    14341426                padding-bottom: 0 !important;
     1427                font-weight: normal;
    14351428            }
    14361429
    … …  
    16141607                text-indent: -45px;
    16151608            }
    1616 
    1617             .table-of-contents {
    1618                 width: 200px;
    1619             }
    16201609        }
    16211610
    … …  
    16231612            width: 99%;
    16241613        }
    1625 
    1626         .usage {
    1627             article {
     1614    }
     1615}
     1616
     1617@media (max-width: 32em) {
     1618    .devhub-wrap {
     1619        .wp-parser-class, .wp-parser-function, .wp-parser-hook, .wp-parser-method {
     1620            .table-of-contents {
    16281621                width: 100%;
    1629             }
    1630 
    1631             .uses {
    1632                 padding-left: 0;
    1633                 margin-top: 30px;
     1622                margin-bottom: 10px;
     1623            }
     1624
     1625            section {
     1626                overflow: inherit;
     1627            }
     1628
     1629            hr {
     1630                clear: both;
    16341631            }
    16351632        }
    … …  
    16491646                font-size: 16px;
    16501647            }
    1651             .table-of-contents {
    1652                 width: 100%;
    1653                 margin-bottom: 10px;
    1654             }
    16551648        }
    16561649

  • sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/stylesheets/main.css

    r3564 r3626  
    12661266  width: 300px;
    12671267}
     1268.devhub-wrap .wp-parser-class .toc-jump, .devhub-wrap .wp-parser-function .toc-jump, .devhub-wrap .wp-parser-hook .toc-jump, .devhub-wrap .wp-parser-method .toc-jump {
     1269  display: inline-block;
     1270  float: right;
     1271}
    12681272.devhub-wrap .callout:before {
    12691273  top: 0.2em;
    … …  
    12801284.devhub-wrap .single .wp-parser-class, .devhub-wrap .single .wp-parser-function, .devhub-wrap .single .wp-parser-hook, .devhub-wrap .single .wp-parser-method {
    12811285  border-bottom-style: none;
    1282 }
    1283 .devhub-wrap .usage article {
    1284   float: left;
    1285   width: 50%;
    1286 }
    1287 .devhub-wrap .usage .used-by {
    1288   padding-right: 30px;
    1289 }
    1290 .devhub-wrap .usage .uses {
    1291   padding-left: 30px;
    12921286}
    12931287.devhub-wrap .usage ul {
    … …  
    15281522.devhub-wrap ul.items li {
    15291523  padding-bottom: 6px !important;
     1524  font-weight: 600;
    15301525}
    15311526.devhub-wrap ul.items li ul li,
    15321527.devhub-wrap ul.items li ul li ul li {
    15331528  padding-bottom: 0 !important;
     1529  font-weight: normal;
    15341530}
    15351531.devhub-wrap ul.items li a {
    … …  
    16731669    text-indent: -45px;
    16741670  }
    1675   .devhub-wrap .wp-parser-class .table-of-contents, .devhub-wrap .wp-parser-function .table-of-contents, .devhub-wrap .wp-parser-hook .table-of-contents, .devhub-wrap .wp-parser-method .table-of-contents {
    1676     width: 200px;
    1677   }
    16781671  .devhub-wrap .two-columns .box {
    16791672    width: 99%;
    16801673  }
    1681   .devhub-wrap .usage article {
     1674}
     1675@media (max-width: 32em) {
     1676  .devhub-wrap .wp-parser-class .table-of-contents, .devhub-wrap .wp-parser-function .table-of-contents, .devhub-wrap .wp-parser-hook .table-of-contents, .devhub-wrap .wp-parser-method .table-of-contents {
    16821677    width: 100%;
    1683   }
    1684   .devhub-wrap .usage .uses {
    1685     padding-left: 0;
    1686     margin-top: 30px;
     1678    margin-bottom: 10px;
     1679  }
     1680  .devhub-wrap .wp-parser-class section, .devhub-wrap .wp-parser-function section, .devhub-wrap .wp-parser-hook section, .devhub-wrap .wp-parser-method section {
     1681    overflow: inherit;
     1682  }
     1683  .devhub-wrap .wp-parser-class hr, .devhub-wrap .wp-parser-function hr, .devhub-wrap .wp-parser-hook hr, .devhub-wrap .wp-parser-method hr {
     1684    clear: both;
    16871685  }
    16881686}
    … …  
    16981696    font-size: 16px;
    16991697  }
    1700   .devhub-wrap .wp-parser-class .table-of-contents, .devhub-wrap .wp-parser-function .table-of-contents, .devhub-wrap .wp-parser-hook .table-of-contents, .devhub-wrap .wp-parser-method .table-of-contents {
    1701     width: 100%;
    1702     margin-bottom: 10px;
    1703   }
    17041698  .devhub-wrap.single-wp-parser-function .comment-list li, .devhub-wrap.single-wp-parser-method .comment-list li, .devhub-wrap.single-wp-parser-hook .comment-list li {
    17051699    padding-left: 0;
Note: See TracChangeset for help on using the changeset viewer.