<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[11341] sites/trunk/wordpress.org/public_html/wp-content/plugins/handbook/inc/table-of-contents.php: Handbooks, ToC: Update the TOC generation to support Gutenberg usage.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { white-space: pre-line; overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="http://meta.trac.wordpress.org/changeset/11341">11341</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"http://meta.trac.wordpress.org/changeset/11341","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>dd32</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2021-11-25 01:11:00 +0000 (Thu, 25 Nov 2021)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Handbooks, ToC: Update the TOC generation to support Gutenberg usage.
In gutenberg, the headings automatically have IDs present, and can have `class` and `style` attributes which also didn't work with the plugin.
This change alters how markup is generated significantly by generating IDs once per `the_content` call, and makes use of named matching groups for readability.
This change means that:
- It works with Gutenberg header blocks including `id=..`
- Custom IDs can be specified for headings (In the Advanced panel in Gutenberg) to avoid changing the ID when changing the title
- Headings can be styled inside Gutenberg and it'll still be presented correctly in the ToC markup (both `style` and `class` attributes)
Fixes <a href="http://meta.trac.wordpress.org/ticket/5963">#5963</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#sitestrunkwordpressorgpublic_htmlwpcontentpluginshandbookinctableofcontentsphp">sites/trunk/wordpress.org/public_html/wp-content/plugins/handbook/inc/table-of-contents.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="sitestrunkwordpressorgpublic_htmlwpcontentpluginshandbookinctableofcontentsphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: sites/trunk/wordpress.org/public_html/wp-content/plugins/handbook/inc/table-of-contents.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- sites/trunk/wordpress.org/public_html/wp-content/plugins/handbook/inc/table-of-contents.php 2021-11-24 21:01:12 UTC (rev 11340)
+++ sites/trunk/wordpress.org/public_html/wp-content/plugins/handbook/inc/table-of-contents.php 2021-11-25 01:11:00 UTC (rev 11341)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -45,7 +45,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> ) );
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- function load_filters() {
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ public function load_filters() {
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( is_singular( $this->post_types ) && ! is_embed() ) {
</span><span class="cx" style="display: block; padding: 0 10px"> add_filter( 'the_content', array( $this, 'add_toc' ) );
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -102,62 +102,57 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return $content;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $toc = '';
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $toc = '';
+ $items = $this->get_tags( 'h(?P<level>[1-4])', $content );
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $items = $this->get_tags( 'h([1-4])', $content );
-
</del><span class="cx" style="display: block; padding: 0 10px"> if ( count( $items ) < 2 ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return $content;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Generate a list of the IDs in the document (generating them as needed).
</ins><span class="cx" style="display: block; padding: 0 10px"> $this->used_ids = $this->get_reserved_ids();
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- for ( $i = 1; $i <= 4; $i++ )
- $content = $this->add_ids_and_jumpto_links( "h$i", $content );
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ foreach ( $items as $i => $item ) {
+ $items[ $i ]['id'] = $this->get_id_for_item( $item );
+ }
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Replace each level of the headings.
+ $content = $this->add_ids_and_jumpto_links( $items, $content );
+
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( ! apply_filters( 'handbook_display_toc', true ) ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return $content;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- if ( $items ) {
- $contents_header = 'h' . $items[0][2]; // Duplicate the first <h#> tag in the document.
- $toc .= $this->styles;
- $toc .= '<div class="table-of-contents">';
- $toc .= "<$contents_header>" . esc_html( $this->args->header_text ) . "</$contents_header><ul class=\"items\">";
- $last_item = false;
- $used_ids = $this->get_reserved_ids();
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $contents_header = 'h' . $items[0]['level']; // Duplicate the first <h#> tag in the document for the TOC header
+ $toc .= $this->styles;
+ $toc .= '<div class="table-of-contents">';
+ $toc .= "<$contents_header>" . esc_html( $this->args->header_text ) . "</$contents_header><ul class=\"items\">";
+ $last_item = false;
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- foreach ( $items as $item ) {
- if ( $last_item ) {
- if ( $last_item < $item[2] )
- $toc .= "\n<ul>\n";
- elseif ( $last_item > $item[2] )
- $toc .= "\n</ul></li>\n";
- else
- $toc .= "</li>\n";
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ foreach ( $items as $item ) {
+ if ( $last_item ) {
+ if ( $last_item < $item['level'] ) {
+ $toc .= "\n<ul>\n";
+ } elseif ( $last_item > $item['level'] ) {
+ $toc .= "\n</ul></li>\n";
+ } else {
+ $toc .= "</li>\n";
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ }
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $last_item = $item[2];
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $last_item = $item['level'];
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $id = sanitize_title( $item[3] );
- // Append unique suffix if anchor ID isn't unique.
- $count = 2;
- $orig_id = $id;
- while ( in_array( $id, $used_ids ) && $count < 50 ) {
- $id = $orig_id . '-' . $count;
- $count++;
- }
- $used_ids[] = $id;
-
- $toc .= '<li><a href="#' . esc_attr( $id ) . '">' . $item[3] . '</a>';
- }
- $toc .= "</ul>\n</div>\n";
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $toc .= '<li><a href="#' . esc_attr( $item['id'] ) . '">' . $item['title'] . '</a>';
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $toc .= "</ul>\n</div>\n";
+
</ins><span class="cx" style="display: block; padding: 0 10px"> return $toc . $content;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- protected function add_ids_and_jumpto_links( $tag, $content ) {
- $items = $this->get_tags( $tag, $content );
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Add the HTML markup for the in-content header elements.
+ */
+ protected function add_ids_and_jumpto_links( $items, $content ) {
</ins><span class="cx" style="display: block; padding: 0 10px"> $first = true;
</span><span class="cx" style="display: block; padding: 0 10px"> $matches = array();
</span><span class="cx" style="display: block; padding: 0 10px"> $replacements = array();
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -164,26 +159,33 @@
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> foreach ( $items as $item ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $replacement = '';
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $matches[] = $item[0];
- $id = sanitize_title( $item[2] );
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $matches[] = $item[0];
+ $tag = 'h' . $item['level']; // 'h2'
+ $id = $item['id'];
+ $title = $item['title'];
+ $extra_attrs = $item['attrs']; // 'class="" style=""'
+ $class = 'toc-heading';
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // Append unique suffix if anchor ID isn't unique.
- $count = 2;
- $orig_id = $id;
- while ( in_array( $id, $this->used_ids ) && $count < 50 ) {
- $id = $orig_id . '-' . $count;
- $count++;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ if ( $extra_attrs ) {
+ // Strip all IDs from the heading attributes (including empty), we'll replace it with one below.
+ $extra_attrs = trim( preg_replace( '/id=(["\'])[^"\']*\\1/i', '', $extra_attrs ) );
+
+ // Extract any classes present, we're adding our own attribute.
+ if ( preg_match( '/class=(["\'])(?P<class>[^"\']+)\\1/i', $extra_attrs, $m ) ) {
+ $extra_attrs = str_replace( $m[0], '', $extra_attrs );
+ $class .= ' ' . $m['class'];
+ }
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $this->used_ids[] = $id;
-
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( ! $first ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $replacement .= '<p class="toc-jump"><a href="#top">' . __( 'Top ↑', 'wporg' ) . '</a></p>';
</span><span class="cx" style="display: block; padding: 0 10px"> } else {
</span><span class="cx" style="display: block; padding: 0 10px"> $first = false;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $a11y_text = sprintf( '<span class="screen-reader-text">%s</span>', $item[2] );
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ $a11y_text = sprintf( '<span class="screen-reader-text">%s</span>', $title );
</ins><span class="cx" style="display: block; padding: 0 10px"> $anchor = sprintf( '<a href="#%1$s" class="anchor"><span aria-hidden="true">#</span>%2$s</a>', $id, $a11y_text );
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $replacement .= sprintf( '<%1$s class="toc-heading" id="%2$s" tabindex="-1">%3$s %4$s</%1$s>', $tag, $id, $item[2], $anchor );
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $replacement .= sprintf( '<%1$s id="%2$s" class="%3$s" tabindex="-1" %4$s>%5$s %6$s</%1$s>', $tag, $id, $class, $extra_attrs, $title, $anchor );
</ins><span class="cx" style="display: block; padding: 0 10px"> $replacements[] = $replacement;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -200,10 +202,41 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return $content;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- private function get_tags( $tag, $content = '' ) {
- if ( empty( $content ) )
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Generate an ID for a given HTML element, use the tags `id` attribute if set.
+ */
+ protected function get_id_for_item( $item ) {
+ if ( ! empty( $item['id'] ) ) {
+ return $item['id'];
+ }
+
+ // Check to see if the item already had a non-empty ID, else generate one from the title.
+ if ( preg_match( '/id=(["\'])(?P<id>[^"\']+)\\1/', $item['attrs'], $m ) ) {
+ $id = $m['id'];
+ } else {
+ $id = sanitize_title( $item['title'] );
+ }
+
+ // Append unique suffix if anchor ID isn't unique in the document.
+ $count = 2;
+ $orig_id = $id;
+ while ( in_array( $id, $this->used_ids ) && $count < 50 ) {
+ $id = $orig_id . '-' . $count;
+ $count++;
+ }
+
+ $this->used_ids[] = $id;
+
+ return $id;
+ }
+
+ protected function get_tags( $tag, $content = '' ) {
+ if ( empty( $content ) ) {
</ins><span class="cx" style="display: block; padding: 0 10px"> $content = get_the_content();
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- preg_match_all( "/(<{$tag}>)(.*)(<\/{$tag}>)/", $content, $matches, PREG_SET_ORDER );
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ }
+
+ preg_match_all( "/(?P<tag><{$tag}(?P<attrs>[^>]*)>)(?P<title>.*)(<\/{$tag}>)/iJ", $content, $matches, PREG_SET_ORDER );
+
</ins><span class="cx" style="display: block; padding: 0 10px"> return $matches;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span></span></pre>
</div>
</div>
</body>
</html>