WordPress.org
Get WordPress

Make WordPress Core

Changeset 55729 for branches/6.2


Ignore:
Timestamp:
05/08/2023 07:57:47 PM (16 months 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.