Making WordPress.org

Changeset 10938


Ignore:
Timestamp:
04/29/2021 10:28:42 PM (9 months ago)
Author:
coffee2code
Message:

Handbooks, ToC: Prevent potential auto-generated ToC heading IDs from conflicting with those in theme markup.

Ensures ToC heading links are unique so that in such cases the links actually lead to the section heading and not some other part of the page.

This is very theme-specific and would need adjustments if the theme employs new potentially-conflicting markup IDs.

Props fahimmurshed, SergeyBiryukov, coffee2code.
Fixes #5064.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • sites/trunk/wordpress.org/public_html/wp-content/plugins/handbook/inc/table-of-contents.php

    r10920 r10938  
    4646
    4747    /**
     48     * Returns reserved markup IDs likely to conflict with ToC-generated heading IDs.
     49     *
     50     * This list isn't meant to be exhaustive, just IDs that are likely to conflict
     51     * with ToC-generated section heading IDs.
     52     *
     53     * If a reserved ID is encountered when a ToC section heading ID is being
     54     * generated, the generated ID is incremented to avoid a conflict.
     55     *
     56     * @return array
     57     */
     58    public function get_reserved_ids() {
     59        /**
     60         * Filters the array of reserved IDs considered when auto-generating IDs for
     61         * ToC sections.
     62         *
     63         * This is mostly for specifying markup IDs that may appear on the same page
     64         * as the ToC for which any ToC-generated IDs would conflict. In such
     65         * cases, the first instance of the ID on the page would be the target of
     66         * the ToC section permalink which is likely not the ToC section itself.
     67         *
     68         * By specifying these reserved IDs, any potential use of the IDs by the theme
     69         * can be accounted for by incrementing the auto-generated ID to avoid conflict.
     70         *
     71         * E.g. if the theme has `<div id="main">`, a ToC with a section titled "Main"
     72         * would have a permalink that links to the div and not the ToC section.
     73         *
     74         * @param array $ids Array of IDs.
     75         */
     76        return (array) apply_filters(
     77            'handbooks_reserved_ids',
     78            [
     79                'main', 'masthead', 'menu-header', 'page', 'primary', 'secondary', 'secondary-content', 'site-navigation',
     80                'wordpress-org', 'wp-toolbar', 'wpadminbar', 'wporg-footer', 'wporg-header'
     81            ]
     82        );
     83    }
     84
     85    /**
    4886     * Converts given content to dynamically add the ToC.
    4987     *
     
    79117            $toc .= "<$contents_header>" . esc_html( $this->args->header_text ) . "</$contents_header><ul class=\"items\">";
    80118            $last_item = false;
    81             $used_ids = [];
     119            $used_ids = $this->get_reserved_ids();
    82120
    83121            foreach ( $items as $item ) {
     
    116154        $matches = array();
    117155        $replacements = array();
    118         $used_ids = array();
     156        $used_ids = $this->get_reserved_ids();
    119157
    120158        foreach ( $items as $item ) {
Note: See TracChangeset for help on using the changeset viewer.