WordPress.org
Get WordPress

Make WordPress Core

Changeset 55729


Ignore:
Timestamp:
05/08/2023 07:57:47 PM (3 years ago)
Author:
SergeyBiryukov
Message:

Docs: Update code examples formatting in WP_HTML_Tag_Processor documentation.

Per the ​documentation standards, code samples should be created by indenting every line of the code by 4 spaces, with a blank line before and after. This matches the format used by the rest of core.

Follow-up to [55203], [55304], [55718], [55724].

Props juanmaguitar, coffee2code, azaozz, costdev, dmsnell, johnbillion, SergeyBiryukov.
Merges [55727] to the 6.2 branch.
Fixes #58028.

Location:
branches/6.2
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • branches/6.2

  • branches/6.2/src/wp-includes/class-wp-theme-json.php

    r55349 r55729  
    6767         * They are a unkeyed array of values such as:
    6868         *
    69          * ```php
    70          * array(
    71          *   array(
    72          *     'slug'      => 'unique-name-within-the-set',
    73          *     'name'      => 'Name for the UI',
    74          *     <value_key> => 'value'
    75          *   ),
    76          * )
    77          * ```
     69         *     array(
     70         *       array(
     71         *         'slug'      => 'unique-name-within-the-set',
     72         *         'name'      => 'Name for the UI',
     73         *         <value_key> => 'value'
     74         *       ),
     75         *     )
    7876         *
    7977         * This contains the necessary metadata to process them:
    … …  
    25322530         * For metadata values that can either be booleans or paths to booleans, gets the value.
    25332531         *
    2534          * ```php
    2535          * $data = array(
    2536          *   'color' => array(
    2537          *     'defaultPalette' => true
    2538          *   )
    2539          * );
    2540          *
    2541          * static::get_metadata_boolean( $data, false );
    2542          * // => false
    2543          *
    2544          * static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
    2545          * // => true
    2546          * ```
     2532         *     $data = array(
     2533         *       'color' => array(
     2534         *         'defaultPalette' => true
     2535         *       )
     2536         *     );
     2537         *
     2538         *     static::get_metadata_boolean( $data, false );
     2539         *     // => false
     2540         *
     2541         *     static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
     2542         *     // => true
    25472543         *
    25482544         * @since 6.0.0

  • branches/6.2/src/wp-includes/html-api/class-wp-html-tag-processor.php

    r55728 r55729  
    3939 *
    4040 * Example:
    41  * ```php
     41 *
    4242 *     $tags = new WP_HTML_Tag_Processor( $html );
    4343 *     if ( $tags->next_tag( 'option' ) ) {
    4444 *         $tags->set_attribute( 'selected', true );
    4545 *     }
    46  * ```
    4746 *
    4847 * ### Finding tags
    … …  
    5554 *
    5655 * If you want to _find whatever the next tag is_:
    57  * ```php
     56 *
    5857 *     $tags->next_tag();
    59  * ```
    6058 *
    6159 * | Goal                                                      | Query                                                                           |
    … …  
    8886 *
    8987 * Example:
    90  * ```php
     88 *
    9189 *     // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
    9290 *     $remaining_count = 5;
    … …  
    10098 *         }
    10199 *     }
    102  * ```
    103100 *
    104101 * `get_attribute()` will return `null` if the attribute wasn't present
    … …  
    117114 *
    118115 * Example:
    119  * ```php
     116 *
    120117 *     if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
    121118 *         $tags->set_attribute( 'title', 'This groups the contained content.' );
    122119 *         $tags->remove_attribute( 'data-test-id' );
    123120 *     }
    124  * ```
    125121 *
    126122 * If `set_attribute()` is called for an existing attribute it will
    … …  
    142138 *
    143139 * Example:
    144  * ```php
     140 *
    145141 *     // from `<span>Yippee!</span>`
    146142 *     //   to `<span class="is-active">Yippee!</span>`
    … …  
    166162 *     //   to `<input type="text" length="24">
    167163 *     $tags->remove_class( 'rugby' );
    168  * ```
    169164 *
    170165 * When class changes are enqueued but a direct change to `class` is made via
    … …  
    185180 * bookmark and update it frequently, such as within a loop.
    186181 *
    187  * ```php
    188182 *     $total_todos = 0;
    189183 *     while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
    … …  
    204198 *         }
    205199 *     }
    206  * ```
    207200 *
    208201 * ## Design and limitations
    … …  
    336329         *
    337330         * Example:
    338          * ```
    339          *   <div id="test">...
    340          *   01234
    341          *    - tag name starts at 1
    342          * ```
     331         *
     332         *     <div id="test">...
     333         *     01234
     334         *      - tag name starts at 1
    343335         *
    344336         * @since 6.2.0
    … …  
    351343         *
    352344         * Example:
    353          * ```
    354          *   <div id="test">...
    355          *   01234
    356          *    --- tag name length is 3
    357          * ```
     345         *
     346         *     <div id="test">...
     347         *     01234
     348         *      --- tag name length is 3
    358349         *
    359350         * @since 6.2.0
    … …  
    366357         *
    367358         * Example:
    368          * ```
    369          *   <div id="test">...
    370          *   0         1   |
    371          *   01234567890123456
    372          *    --- tag name ends at 14
    373          * ```
     359         *
     360         *     <div id="test">...
     361         *     0         1   |
     362         *     01234567890123456
     363         *      --- tag name ends at 14
    374364         *
    375365         * @since 6.2.0
    … …  
    389379         *
    390380         * Example:
    391          * ```php
    392          *     // supposing the parser is working through this content
    393          *     // and stops after recognizing the `id` attribute
     381         *
     382         *     // Supposing the parser is working through this content
     383         *     // and stops after recognizing the `id` attribute.
    394384         *     // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
    395          *     //                 ^ parsing will continue from this point
     385         *     //                 ^ parsing will continue from this point.
    396386         *     $this->attributes = array(
    397387         *         'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
    398388         *     );
    399389         *
    400          *     // when picking up parsing again, or when asking to find the
    401          *     // `class` attribute we will continue and add to this array
     390         *     // When picking up parsing again, or when asking to find the
     391         *     // `class` attribute we will continue and add to this array.
    402392         *     $this->attributes = array(
    403393         *         'id'    => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
    … …  
    407397         *     // Note that only the `class` attribute value is stored in the index.
    408398         *     // That's because it is the only value used by this class at the moment.
    409          * ```
    410399         *
    411400         * @since 6.2.0
    … …  
    426415         *
    427416         * Example:
    428          * ```php
     417         *
    429418         *     // Add the `wp-block-group` class, remove the `wp-group` class.
    430419         *     $classname_updates = array(
    431          *         // Indexed by a comparable class name
     420         *         // Indexed by a comparable class name.
    432421         *         'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
    433422         *         'wp-group'       => WP_HTML_Tag_Processor::REMOVE_CLASS
    434423         *     );
    435          * ```
    436424         *
    437425         * @since 6.2.0
    … …  
    480468         *
    481469         * Example:
    482          * ```php
     470         *
    483471         *     // Replace an attribute stored with a new value, indices
    484472         *     // sourced from the lazily-parsed HTML recognizer.
    … …  
    491479         *         WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
    492480         *     );
    493          * ```
    494481         *
    495482         * @since 6.2.0
    … …  
    609596         *
    610597         * Example:
    611          * ```
     598         *
    612599         *     <main><h2>Surprising fact you may not know!</h2></main>
    613600         *           ^  ^
    … …  
    617604         *                             ^  ^
    618605         *                              \-|-- it shifts with edits
    619          * ```
    620606         *
    621607         * Bookmarks provide the ability to seek to a previously-scanned
    … …  
    624610         *
    625611         * Example:
    626          * ```
     612         *
    627613         *     <ul><li>One</li><li>Two</li><li>Three</li></ul>
    628614         *                                 ^^^^
    … …  
    651637         *         }
    652638         *     }
    653          * ```
    654639         *
    655640         * Bookmarks intentionally hide the internal string offsets
    … …  
    728713         * @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state
    729714         *
    730          * @param string $tag_name – the lowercase tag name which will close the RCDATA region.
     715         * @param string $tag_name The lowercase tag name which will close the RCDATA region.
    731716         * @return bool Whether an end to the RCDATA region was found before the end of the document.
    732717         */
    … …  
    16161601                 *
    16171602                 * Example:
    1618                  * ```
     1603                 *
    16191604                 *     $p->set_attribute( 'data-TEST-id', 'update' );
    16201605                 *     'update' === $p->get_enqueued_attribute_value( 'data-test-id' );
    1621                  * ```
    16221606                 *
    16231607                 * Detect this difference based on the absence of the `=`, which _must_ exist in any
    … …  
    16501634         *
    16511635         * Example:
    1652          * ```php
     1636         *
    16531637         *     $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
    16541638         *     $p->next_tag( array( 'class_name' => 'test' ) ) === true;
    … …  
    16591643         *     $p->next_tag() === false;
    16601644         *     $p->get_attribute( 'class' ) === null;
    1661          * ```
    16621645         *
    16631646         * @since 6.2.0
    … …  
    17311714         *
    17321715         * Example:
    1733          * ```php
     1716         *
    17341717         *     $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
    17351718         *     $p->next_tag( array( 'class_name' => 'test' ) ) === true;
    … …  
    17381721         *     $p->next_tag() === false;
    17391722         *     $p->get_attribute_names_with_prefix( 'data-' ) === null;
    1740          * ```
    17411723         *
    17421724         * @since 6.2.0
    … …  
    17671749         *
    17681750         * Example:
    1769          * ```php
     1751         *
    17701752         *     $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' );
    17711753         *     $p->next_tag() === true;
    … …  
    17741756         *     $p->next_tag() === false;
    17751757         *     $p->get_tag() === null;
    1776          * ```
    17771758         *
    17781759         * @since 6.2.0
    … …  
    17941775         *
    17951776         * Example:
    1796          * ```php
     1777         *
    17971778         *     $p = new WP_HTML_Tag_Processor( '<div></div>' );
    17981779         *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
    … …  
    18011782         *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
    18021783         *     $p->is_tag_closer() === true;
    1803          * ```
    18041784         *
    18051785         * @since 6.2.0
    … …  
    19071887                         *
    19081888                         * Example – set attribute id to "new" in <div id="initial_id" />:
    1909                          *    <div id="initial_id"/>
    1910                          *         ^-------------^
    1911                          *         start         end
    1912                          *    replacement: `id="new"`
    19131889                         *
    1914                          *    Result: <div id="new"/>
     1890                         *     <div id="initial_id"/>
     1891                         *          ^-------------^
     1892                         *          start         end
     1893                         *     replacement: `id="new"`
     1894                         *
     1895                         *     Result: <div id="new"/>
    19151896                         */
    19161897                        $existing_attribute = $this->attributes[ $comparable_name ];
    … …  
    19251906                         *
    19261907                         * Example – add attribute id="new" to <div />:
    1927                          *    <div/>
    1928                          *        ^
    1929                          *        start and end
    1930                          *    replacement: ` id="new"`
    19311908                         *
    1932                          *    Result: <div id="new"/>
     1909                         *     <div/>
     1910                         *         ^
     1911                         *         start and end
     1912                         *     replacement: ` id="new"`
     1913                         *
     1914                         *     Result: <div id="new"/>
    19331915                         */
    19341916                        $this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
Note: See TracChangeset for help on using the changeset viewer.