Make WordPress Core

Changeset 55718


Ignore:
Timestamp:
05/03/2023 11:53:19 PM (12 months ago)
Author:
johnbillion
Message:

Docs: Improve formatting of markup in the docs for WP_HTML_Tag_Processor.

Code blocks wrapped inside backtacks don't need to be indented.

See #57840

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php

    r55706 r55718  
    4040 * Example:
    4141 * ```php
    42  *     $tags = new WP_HTML_Tag_Processor( $html );
    43  *     if ( $tags->next_tag( 'option' ) ) {
    44  *         $tags->set_attribute( 'selected', true );
    45  *     }
     42 * $tags = new WP_HTML_Tag_Processor( $html );
     43 * if ( $tags->next_tag( 'option' ) ) {
     44 *     $tags->set_attribute( 'selected', true );
     45 * }
    4646 * ```
    4747 *
     
    5656 * If you want to _find whatever the next tag is_:
    5757 * ```php
    58  *     $tags->next_tag();
     58 * $tags->next_tag();
    5959 * ```
    6060 *
     
    8989 * Example:
    9090 * ```php
    91  *     // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
    92  *     $remaining_count = 5;
    93  *     while ( $remaining_count > 0 && $tags->next_tag() ) {
    94  *         if (
    95  *              ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) &&
    96  *              'jazzy' === $tags->get_attribute( 'data-style' )
    97  *         ) {
    98  *             $tags->add_class( 'theme-style-everest-jazz' );
    99  *             $remaining_count--;
    100  *         }
     91 * // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
     92 * $remaining_count = 5;
     93 * while ( $remaining_count > 0 && $tags->next_tag() ) {
     94 *     if (
     95 *          ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) &&
     96 *          'jazzy' === $tags->get_attribute( 'data-style' )
     97 *     ) {
     98 *         $tags->add_class( 'theme-style-everest-jazz' );
     99 *         $remaining_count--;
    101100 *     }
     101 * }
    102102 * ```
    103103 *
     
    118118 * Example:
    119119 * ```php
    120  *     if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
    121  *         $tags->set_attribute( 'title', 'This groups the contained content.' );
    122  *         $tags->remove_attribute( 'data-test-id' );
    123  *     }
     120 * if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
     121 *     $tags->set_attribute( 'title', 'This groups the contained content.' );
     122 *     $tags->remove_attribute( 'data-test-id' );
     123 * }
    124124 * ```
    125125 *
     
    143143 * Example:
    144144 * ```php
    145  *     // from `<span>Yippee!</span>`
    146  *     //   to `<span class="is-active">Yippee!</span>`
    147  *     $tags->add_class( 'is-active' );
    148  *
    149  *     // from `<span class="excited">Yippee!</span>`
    150  *     //   to `<span class="excited is-active">Yippee!</span>`
    151  *     $tags->add_class( 'is-active' );
    152  *
    153  *     // from `<span class="is-active heavy-accent">Yippee!</span>`
    154  *     //   to `<span class="is-active heavy-accent">Yippee!</span>`
    155  *     $tags->add_class( 'is-active' );
    156  *
    157  *     // from `<input type="text" class="is-active rugby not-disabled" length="24">`
    158  *     //   to `<input type="text" class="is-active not-disabled" length="24">
    159  *     $tags->remove_class( 'rugby' );
    160  *
    161  *     // from `<input type="text" class="rugby" length="24">`
    162  *     //   to `<input type="text" length="24">
    163  *     $tags->remove_class( 'rugby' );
    164  *
    165  *     // from `<input type="text" length="24">`
    166  *     //   to `<input type="text" length="24">
    167  *     $tags->remove_class( 'rugby' );
     145 * // from `<span>Yippee!</span>`
     146 * //   to `<span class="is-active">Yippee!</span>`
     147 * $tags->add_class( 'is-active' );
     148 *
     149 * // from `<span class="excited">Yippee!</span>`
     150 * //   to `<span class="excited is-active">Yippee!</span>`
     151 * $tags->add_class( 'is-active' );
     152 *
     153 * // from `<span class="is-active heavy-accent">Yippee!</span>`
     154 * //   to `<span class="is-active heavy-accent">Yippee!</span>`
     155 * $tags->add_class( 'is-active' );
     156 *
     157 * // from `<input type="text" class="is-active rugby not-disabled" length="24">`
     158 * //   to `<input type="text" class="is-active not-disabled" length="24">
     159 * $tags->remove_class( 'rugby' );
     160 *
     161 * // from `<input type="text" class="rugby" length="24">`
     162 * //   to `<input type="text" length="24">
     163 * $tags->remove_class( 'rugby' );
     164 *
     165 * // from `<input type="text" length="24">`
     166 * //   to `<input type="text" length="24">
     167 * $tags->remove_class( 'rugby' );
    168168 * ```
    169169 *
     
    186186 *
    187187 * ```php
    188  *     $total_todos = 0;
    189  *     while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
    190  *         $p->set_bookmark( 'list-start' );
    191  *         while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
    192  *             if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) {
    193  *                 $p->set_bookmark( 'list-end' );
    194  *                 $p->seek( 'list-start' );
    195  *                 $p->set_attribute( 'data-contained-todos', (string) $total_todos );
    196  *                 $total_todos = 0;
    197  *                 $p->seek( 'list-end' );
    198  *                 break;
    199  *             }
    200  *
    201  *             if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) {
    202  *                 $total_todos++;
    203  *             }
     188 * $total_todos = 0;
     189 * while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
     190 *     $p->set_bookmark( 'list-start' );
     191 *     while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
     192 *         if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) {
     193 *             $p->set_bookmark( 'list-end' );
     194 *             $p->seek( 'list-start' );
     195 *             $p->set_attribute( 'data-contained-todos', (string) $total_todos );
     196 *             $total_todos = 0;
     197 *             $p->seek( 'list-end' );
     198 *             break;
     199 *         }
     200 *
     201 *         if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) {
     202 *             $total_todos++;
    204203 *         }
    205204 *     }
     205 * }
    206206 * ```
    207207 *
     
    230230 * HTML5 specifies that certain invalid content be transformed into different forms
    231231 * for display, such as removing null bytes from an input document and replacing
    232  * invalid characters with the Unicode replacement character U+FFFD �. Where errors
     232 * invalid characters with the Unicode replacement character `U+FFFD`. Where errors
    233233 * or transformations exist within the HTML5 specification, the Tag Processor leaves
    234234 * those invalid inputs untouched, passing them through to the final browser to handle.
     
    388388     * Example:
    389389     * ```php
    390      *     // supposing the parser is working through this content
    391      *     // and stops after recognizing the `id` attribute
    392      *     // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
    393      *     //                 ^ parsing will continue from this point
    394      *     $this->attributes = array(
    395      *         'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
    396      *     );
    397      *
    398      *     // when picking up parsing again, or when asking to find the
    399      *     // `class` attribute we will continue and add to this array
    400      *     $this->attributes = array(
    401      *         'id'    => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
    402      *         'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 )
    403      *     );
    404      *
    405      *     // Note that only the `class` attribute value is stored in the index.
    406      *     // That's because it is the only value used by this class at the moment.
     390     * // supposing the parser is working through this content
     391     * // and stops after recognizing the `id` attribute
     392     * // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
     393     * //                 ^ parsing will continue from this point
     394     * $this->attributes = array(
     395     *     'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
     396     * );
     397     *
     398     * // when picking up parsing again, or when asking to find the
     399     * // `class` attribute we will continue and add to this array
     400     * $this->attributes = array(
     401     *     'id'    => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
     402     *     'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 )
     403     * );
     404     *
     405     * // Note that only the `class` attribute value is stored in the index.
     406     * // That's because it is the only value used by this class at the moment.
    407407     * ```
    408408     *
     
    425425     * Example:
    426426     * ```php
    427      *     // Add the `wp-block-group` class, remove the `wp-group` class.
    428      *     $classname_updates = array(
    429      *         // Indexed by a comparable class name
    430      *         'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
    431      *         'wp-group'       => WP_HTML_Tag_Processor::REMOVE_CLASS
    432      *     );
     427     * // Add the `wp-block-group` class, remove the `wp-group` class.
     428     * $classname_updates = array(
     429     *     // Indexed by a comparable class name
     430     *     'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
     431     *     'wp-group'       => WP_HTML_Tag_Processor::REMOVE_CLASS
     432     * );
    433433     * ```
    434434     *
     
    479479     * Example:
    480480     * ```php
    481      *     // Replace an attribute stored with a new value, indices
    482      *     // sourced from the lazily-parsed HTML recognizer.
    483      *     $start = $attributes['src']->start;
    484      *     $end   = $attributes['src']->end;
    485      *     $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value );
    486      *
    487      *     // Correspondingly, something like this will appear in this array.
    488      *     $lexical_updates = array(
    489      *         WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
    490      *     );
     481     * // Replace an attribute stored with a new value, indices
     482     * // sourced from the lazily-parsed HTML recognizer.
     483     * $start = $attributes['src']->start;
     484     * $end   = $attributes['src']->end;
     485     * $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value );
     486     *
     487     * // Correspondingly, something like this will appear in this array.
     488     * $lexical_updates = array(
     489     *     WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
     490     * );
    491491     * ```
    492492     *
     
    16621662     * Example:
    16631663     * ```php
    1664      *     $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
    1665      *     $p->next_tag( array( 'class_name' => 'test' ) ) === true;
    1666      *     $p->get_attribute( 'data-test-id' ) === '14';
    1667      *     $p->get_attribute( 'enabled' ) === true;
    1668      *     $p->get_attribute( 'aria-label' ) === null;
    1669      *
    1670      *     $p->next_tag() === false;
    1671      *     $p->get_attribute( 'class' ) === null;
     1664     * $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
     1665     * $p->next_tag( array( 'class_name' => 'test' ) ) === true;
     1666     * $p->get_attribute( 'data-test-id' ) === '14';
     1667     * $p->get_attribute( 'enabled' ) === true;
     1668     * $p->get_attribute( 'aria-label' ) === null;
     1669     *
     1670     * $p->next_tag() === false;
     1671     * $p->get_attribute( 'class' ) === null;
    16721672     * ```
    16731673     *
     
    17451745     * Example:
    17461746     * ```php
    1747      *     $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
    1748      *     $p->next_tag( array( 'class_name' => 'test' ) ) === true;
    1749      *     $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
    1750      *
    1751      *     $p->next_tag() === false;
    1752      *     $p->get_attribute_names_with_prefix( 'data-' ) === null;
     1747     * $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
     1748     * $p->next_tag( array( 'class_name' => 'test' ) ) === true;
     1749     * $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
     1750     *
     1751     * $p->next_tag() === false;
     1752     * $p->get_attribute_names_with_prefix( 'data-' ) === null;
    17531753     * ```
    17541754     *
     
    17791779     * Example:
    17801780     * ```php
    1781      *     $p = new WP_HTML_Tag_Processor( '<DIV CLASS="test">Test</DIV>' );
    1782      *     $p->next_tag() === true;
    1783      *     $p->get_tag() === 'DIV';
    1784      *
    1785      *     $p->next_tag() === false;
    1786      *     $p->get_tag() === null;
     1781     * $p = new WP_HTML_Tag_Processor( '<DIV CLASS="test">Test</DIV>' );
     1782     * $p->next_tag() === true;
     1783     * $p->get_tag() === 'DIV';
     1784     *
     1785     * $p->next_tag() === false;
     1786     * $p->get_tag() === null;
    17871787     * ```
    17881788     *
     
    18311831     * Example:
    18321832     * ```php
    1833      *     $p = new WP_HTML_Tag_Processor( '<div></div>' );
    1834      *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
    1835      *     $p->is_tag_closer() === false;
    1836      *
    1837      *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
    1838      *     $p->is_tag_closer() === true;
     1833     * $p = new WP_HTML_Tag_Processor( '<div></div>' );
     1834     * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
     1835     * $p->is_tag_closer() === false;
     1836     *
     1837     * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
     1838     * $p->is_tag_closer() === true;
    18391839     * ```
    18401840     *
Note: See TracChangeset for help on using the changeset viewer.