- Timestamp:
- 05/08/2023 05:30:41 PM (18 months ago)
- Location:
- trunk/src/wp-includes
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/wp-includes/class-wp-theme-json.php
r55712 r55727 67 67 * They are a unkeyed array of values such as: 68 68 * 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 * ) 78 76 * 79 77 * This contains the necessary metadata to process them: … … 2533 2531 * For metadata values that can either be booleans or paths to booleans, gets the value. 2534 2532 * 2535 * ```php 2536 * $data = array( 2537 * 'color' => array( 2538 * 'defaultPalette' => true 2539 * ) 2540 * ); 2541 * 2542 * static::get_metadata_boolean( $data, false ); 2543 * // => false 2544 * 2545 * static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) ); 2546 * // => true 2547 * ``` 2533 * $data = array( 2534 * 'color' => array( 2535 * 'defaultPalette' => true 2536 * ) 2537 * ); 2538 * 2539 * static::get_metadata_boolean( $data, false ); 2540 * // => false 2541 * 2542 * static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) ); 2543 * // => true 2548 2544 * 2549 2545 * @since 6.0.0 -
trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php
r55725 r55727 39 39 * 40 40 * Example: 41 * ```php 42 * $tags = new WP_HTML_Tag_Processor( $html ); 43 * if ( $tags->next_tag( 'option' ) ) { 44 * $tags->set_attribute( 'selected', true ); 45 * } 46 * ``` 41 * 42 * $tags = new WP_HTML_Tag_Processor( $html ); 43 * if ( $tags->next_tag( 'option' ) ) { 44 * $tags->set_attribute( 'selected', true ); 45 * } 47 46 * 48 47 * ### Finding tags … … 55 54 * 56 55 * If you want to _find whatever the next tag is_: 57 * ```php 58 * $tags->next_tag(); 59 * ``` 56 * 57 * $tags->next_tag(); 60 58 * 61 59 * | Goal | Query | … … 88 86 * 89 87 * Example: 90 * ```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--; 88 * 89 * // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style. 90 * $remaining_count = 5; 91 * while ( $remaining_count > 0 && $tags->next_tag() ) { 92 * if ( 93 * ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) && 94 * 'jazzy' === $tags->get_attribute( 'data-style' ) 95 * ) { 96 * $tags->add_class( 'theme-style-everest-jazz' ); 97 * $remaining_count--; 98 * } 100 99 * } 101 * }102 * ```103 100 * 104 101 * `get_attribute()` will return `null` if the attribute wasn't present … … 117 114 * 118 115 * Example: 119 * ```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 * } 124 * ``` 116 * 117 * if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) { 118 * $tags->set_attribute( 'title', 'This groups the contained content.' ); 119 * $tags->remove_attribute( 'data-test-id' ); 120 * } 125 121 * 126 122 * If `set_attribute()` is called for an existing attribute it will … … 142 138 * 143 139 * Example: 144 * ```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' ); 168 * ``` 140 * 141 * // from `<span>Yippee!</span>` 142 * // to `<span class="is-active">Yippee!</span>` 143 * $tags->add_class( 'is-active' ); 144 * 145 * // from `<span class="excited">Yippee!</span>` 146 * // to `<span class="excited is-active">Yippee!</span>` 147 * $tags->add_class( 'is-active' ); 148 * 149 * // from `<span class="is-active heavy-accent">Yippee!</span>` 150 * // to `<span class="is-active heavy-accent">Yippee!</span>` 151 * $tags->add_class( 'is-active' ); 152 * 153 * // from `<input type="text" class="is-active rugby not-disabled" length="24">` 154 * // to `<input type="text" class="is-active not-disabled" length="24"> 155 * $tags->remove_class( 'rugby' ); 156 * 157 * // from `<input type="text" class="rugby" length="24">` 158 * // to `<input type="text" length="24"> 159 * $tags->remove_class( 'rugby' ); 160 * 161 * // from `<input type="text" length="24">` 162 * // to `<input type="text" length="24"> 163 * $tags->remove_class( 'rugby' ); 169 164 * 170 165 * When class changes are enqueued but a direct change to `class` is made via … … 185 180 * bookmark and update it frequently, such as within a loop. 186 181 * 187 * ```php188 * $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++;182 * $total_todos = 0; 183 * while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) { 184 * $p->set_bookmark( 'list-start' ); 185 * while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) { 186 * if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) { 187 * $p->set_bookmark( 'list-end' ); 188 * $p->seek( 'list-start' ); 189 * $p->set_attribute( 'data-contained-todos', (string) $total_todos ); 190 * $total_todos = 0; 191 * $p->seek( 'list-end' ); 192 * break; 193 * } 194 * 195 * if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) { 196 * $total_todos++; 197 * } 203 198 * } 204 199 * } 205 * }206 * ```207 200 * 208 201 * ## Design and limitations … … 336 329 * 337 330 * 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 343 335 * 344 336 * @since 6.2.0 … … 351 343 * 352 344 * 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 358 349 * 359 350 * @since 6.2.0 … … 366 357 * 367 358 * 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 374 364 * 375 365 * @since 6.2.0 … … 389 379 * 390 380 * Example: 391 * ```php 392 * // supposing the parser is working through this content 393 * // and stops after recognizing the `id` attribute 394 * // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8"> 395 * // ^ parsing will continue from this point 396 * $this->attributes = array( 397 * 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ) 398 * ); 399 * 400 * // when picking up parsing again, or when asking to find the 401 * // `class` attribute we will continue and add to this array 402 * $this->attributes = array( 403 * 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ), 404 * 'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 ) 405 * ); 406 * 407 * // Note that only the `class` attribute value is stored in the index. 408 * // That's because it is the only value used by this class at the moment. 409 * ``` 381 * 382 * // Supposing the parser is working through this content 383 * // and stops after recognizing the `id` attribute. 384 * // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8"> 385 * // ^ parsing will continue from this point. 386 * $this->attributes = array( 387 * 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ) 388 * ); 389 * 390 * // When picking up parsing again, or when asking to find the 391 * // `class` attribute we will continue and add to this array. 392 * $this->attributes = array( 393 * 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ), 394 * 'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 ) 395 * ); 396 * 397 * // Note that only the `class` attribute value is stored in the index. 398 * // That's because it is the only value used by this class at the moment. 410 399 * 411 400 * @since 6.2.0 … … 426 415 * 427 416 * Example: 428 * ```php 429 * // Add the `wp-block-group` class, remove the `wp-group` class. 430 * $classname_updates = array( 431 * // Indexed by a comparable class name 432 * 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS, 433 * 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS 434 * ); 435 * ``` 417 * 418 * // Add the `wp-block-group` class, remove the `wp-group` class. 419 * $classname_updates = array( 420 * // Indexed by a comparable class name. 421 * 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS, 422 * 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS 423 * ); 436 424 * 437 425 * @since 6.2.0 … … 480 468 * 481 469 * Example: 482 * ```php 483 * // Replace an attribute stored with a new value, indices 484 * // sourced from the lazily-parsed HTML recognizer. 485 * $start = $attributes['src']->start; 486 * $end = $attributes['src']->end; 487 * $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value ); 488 * 489 * // Correspondingly, something like this will appear in this array. 490 * $lexical_updates = array( 491 * WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' ) 492 * ); 493 * ``` 470 * 471 * // Replace an attribute stored with a new value, indices 472 * // sourced from the lazily-parsed HTML recognizer. 473 * $start = $attributes['src']->start; 474 * $end = $attributes['src']->end; 475 * $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value ); 476 * 477 * // Correspondingly, something like this will appear in this array. 478 * $lexical_updates = array( 479 * WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' ) 480 * ); 494 481 * 495 482 * @since 6.2.0 … … 609 596 * 610 597 * Example: 611 * ```598 * 612 599 * <main><h2>Surprising fact you may not know!</h2></main> 613 600 * ^ ^ … … 617 604 * ^ ^ 618 605 * \-|-- it shifts with edits 619 * ```620 606 * 621 607 * Bookmarks provide the ability to seek to a previously-scanned … … 624 610 * 625 611 * Example: 626 * ```612 * 627 613 * <ul><li>One</li><li>Two</li><li>Three</li></ul> 628 614 * ^^^^ … … 651 637 * } 652 638 * } 653 * ```654 639 * 655 640 * Bookmarks intentionally hide the internal string offsets … … 728 713 * @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state 729 714 * 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. 731 716 * @return bool Whether an end to the RCDATA region was found before the end of the document. 732 717 */ … … 1625 1610 * 1626 1611 * Example: 1627 * ```1612 * 1628 1613 * $p->set_attribute( 'data-TEST-id', 'update' ); 1629 1614 * 'update' === $p->get_enqueued_attribute_value( 'data-test-id' ); 1630 * ```1631 1615 * 1632 1616 * Detect this difference based on the absence of the `=`, which _must_ exist in any … … 1659 1643 * 1660 1644 * Example: 1661 * ```php 1662 * $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' ); 1663 * $p->next_tag( array( 'class_name' => 'test' ) ) === true; 1664 * $p->get_attribute( 'data-test-id' ) === '14'; 1665 * $p->get_attribute( 'enabled' ) === true; 1666 * $p->get_attribute( 'aria-label' ) === null; 1667 * 1668 * $p->next_tag() === false; 1669 * $p->get_attribute( 'class' ) === null; 1670 * ``` 1645 * 1646 * $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' ); 1647 * $p->next_tag( array( 'class_name' => 'test' ) ) === true; 1648 * $p->get_attribute( 'data-test-id' ) === '14'; 1649 * $p->get_attribute( 'enabled' ) === true; 1650 * $p->get_attribute( 'aria-label' ) === null; 1651 * 1652 * $p->next_tag() === false; 1653 * $p->get_attribute( 'class' ) === null; 1671 1654 * 1672 1655 * @since 6.2.0 … … 1740 1723 * 1741 1724 * Example: 1742 * ```php 1743 * $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' ); 1744 * $p->next_tag( array( 'class_name' => 'test' ) ) === true; 1745 * $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' ); 1746 * 1747 * $p->next_tag() === false; 1748 * $p->get_attribute_names_with_prefix( 'data-' ) === null; 1749 * ``` 1725 * 1726 * $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' ); 1727 * $p->next_tag( array( 'class_name' => 'test' ) ) === true; 1728 * $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' ); 1729 * 1730 * $p->next_tag() === false; 1731 * $p->get_attribute_names_with_prefix( 'data-' ) === null; 1750 1732 * 1751 1733 * @since 6.2.0 … … 1776 1758 * 1777 1759 * Example: 1778 * ```php 1779 * $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' ); 1780 * $p->next_tag() === true; 1781 * $p->get_tag() === 'DIV'; 1782 * 1783 * $p->next_tag() === false; 1784 * $p->get_tag() === null; 1785 * ``` 1760 * 1761 * $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' ); 1762 * $p->next_tag() === true; 1763 * $p->get_tag() === 'DIV'; 1764 * 1765 * $p->next_tag() === false; 1766 * $p->get_tag() === null; 1786 1767 * 1787 1768 * @since 6.2.0 … … 1828 1809 * 1829 1810 * Example: 1830 * ```php 1831 * $p = new WP_HTML_Tag_Processor( '<div></div>' ); 1832 * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); 1833 * $p->is_tag_closer() === false; 1834 * 1835 * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); 1836 * $p->is_tag_closer() === true; 1837 * ``` 1811 * 1812 * $p = new WP_HTML_Tag_Processor( '<div></div>' ); 1813 * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); 1814 * $p->is_tag_closer() === false; 1815 * 1816 * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); 1817 * $p->is_tag_closer() === true; 1838 1818 * 1839 1819 * @since 6.2.0 … … 1941 1921 * 1942 1922 * Example – set attribute id to "new" in <div id="initial_id" />: 1943 * <div id="initial_id"/>1944 * ^-------------^1945 * start end1946 * replacement: `id="new"`1947 1923 * 1948 * Result: <div id="new"/> 1924 * <div id="initial_id"/> 1925 * ^-------------^ 1926 * start end 1927 * replacement: `id="new"` 1928 * 1929 * Result: <div id="new"/> 1949 1930 */ 1950 1931 $existing_attribute = $this->attributes[ $comparable_name ]; … … 1959 1940 * 1960 1941 * Example – add attribute id="new" to <div />: 1961 * <div/>1962 * ^1963 * start and end1964 * replacement: ` id="new"`1965 1942 * 1966 * Result: <div id="new"/> 1943 * <div/> 1944 * ^ 1945 * start and end 1946 * replacement: ` id="new"` 1947 * 1948 * Result: <div id="new"/> 1967 1949 */ 1968 1950 $this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
Note: See TracChangeset
for help on using the changeset viewer.