Making WordPress.org

Changeset 3626


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