Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/trunk' into update/node-to-18-x
Browse files Browse the repository at this point in the history
  • Loading branch information
desrosj committed Dec 20, 2023
2 parents 5d485aa + 4173b30 commit 2bfa462
Show file tree
Hide file tree
Showing 52 changed files with 1,407 additions and 1,424 deletions.
337 changes: 337 additions & 0 deletions changelog.txt

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions docs/getting-started/fundamentals/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,5 @@ In this section, you will learn:
1. [**Registration of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block) - How a block is registered in both the server and the client.
1. [**Block wrapper**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper) - How to set proper attributes to the block's markup wrapper.
1. [**The block in the Editor**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-in-the-editor) - The block as a React component loaded in the Block Editor and its possibilities.
1. [**Markup representation of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block) - How blocks are represented in the DB or in templates.
1. [**Javascript in the Block Editor**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/javascript-in-the-block-editor) - How to work with Javascript for the Block Editor.
8 changes: 4 additions & 4 deletions docs/getting-started/fundamentals/block-wrapper.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Each block's markup is wrapped by a container HTML tag that needs to have the pr
Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`.

<div class="callout callout-info">
The use of <code>supports</code> generates a set of properties that need to be manually added to the wrapping element of the block so they're properly stored as part of the block data
The use of <code>supports</code> generates a set of properties that need to be manually added to the wrapping element of the block so they're properly stored as part of the block data.
</div>

A block can have three sets of markup defined, each one of them with a specific target and purpose:
Expand All @@ -16,7 +16,7 @@ A block can have three sets of markup defined, each one of them with a specific
- The one used to **dynamically render the markup of the block** returned to the front end on request, defined through the `render_callback` on [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) or the [`render`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render) PHP file in `block.json`
- If defined, this server-side generated markup will be returned to the front end, ignoring the markup stored in DB.

For the [`edit` React component and the `save` function](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/), the block wrapper element should be a native DOM element (like `<div>`) or a React component that forwards any additional props to native DOM elements. Using a <Fragment> or <ServerSideRender> component, for instance, would be invalid.
For the [`edit` React component and the `save` function](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/), the block wrapper element should be a native DOM element (like `<div>`) or a React component that forwards any additional props to native DOM elements. Using a `<Fragment>` or `<ServerSideRender>` component, for instance, would be invalid.


## The Edit component's markup
Expand Down Expand Up @@ -60,7 +60,7 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b
>Hello World - Block Editor</p>
```

Any additional classes and attributes for the `Edit` component of the block should be passed as an argument of `useBlockProps` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/edit.js)). When you add `support` for any feature, they get added to the object returned by the `useBlockProps` hook.
Any additional classes and attributes for the `Edit` component of the block should be passed as an argument of `useBlockProps` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/edit.js)). When you add `supports` for any feature, they get added to the object returned by the `useBlockProps` hook.


## The Save component's markup
Expand Down Expand Up @@ -89,7 +89,7 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b

Any additional classes and attributes for the `save` function of the block should be passed as an argument of `useBlockProps.save()` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/save.js)).

When you add `support` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook.
When you add `supports` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook.

```html
<p class="
Expand Down
44 changes: 44 additions & 0 deletions docs/getting-started/fundamentals/markup-representation-block.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Markup representation of a block

When stored, in the database (DB) or in templates as HTML files, blocks are represented using a [specific HTML grammar](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/#data-and-attributes), which is technically valid HTML based on HTML comments that act as explicit block delimiters

These are some of the rules for the markup used to represent a block:
- All core block comments start with a prefix and the block name: `wp:blockname`
- For custom blocks, `blockname` is `namespace/blockname`
- The comment can be a single line, self-closing, or wrapper for HTML content.
- Custom block settings and attributes are stored as a JSON object inside the block comment.

_Example: Markup representation of an `image` core block_

```
<!-- wp:image -->
<figure class="wp-block-image"><img src="source.jpg" alt="" /></figure>
<!-- /wp:image -->
```

The [markup representation of a block is parsed for the Block Editor](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/) and the block's output for the front end:
- In the editor, WordPress parses this block markup, captures its data and loads its `edit` version
- In the front end, WordPress parses this block markup, captures its data and generates its final HTML markup

Whenever a block is saved, the `save` function, defined when the [block is registered in the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), is called to return the markup that will be saved into the database within the block delimiter's comment. If `save` is `null` (common case for blocks with dynamic rendering), only a single line block delimiter's comment is stored, along with any attributes

The Post Editor checks that the markup created by the `save` function is identical to the block's markup saved to the database:
- If there are any differences, the Post Editor trigger a **block validation error**.
- Block validation errors usually happen when a block’s `save` function is updated to change the markup produced by the block.
- A block developer can mitigate these issues by adding a [**block deprecation**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) to register the change in the block.

The markup of a **block with dynamic rendering** is expected to change so the markup of these blocks is not saved to the database. What is saved in the DB as representation of the block, for blocks with dynamic rendering, is a single line of HTML consisting on just the block delimiter's comment (including block attributes values). That HTML is not subject to the Post Editor’s validation.

_Example: Markup representation of a block with dynamic rendering (`save` = `null`) and attributes_


```html
<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->
```

## Additional Resources

- [Data Flow and Data Format](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/)
- [Static vs. dynamic blocks: What’s the difference?](https://developer.wordpress.org/news/2023/02/27/static-vs-dynamic-blocks-whats-the-difference/)
- [Block deprecation – a tutorial](https://developer.wordpress.org/news/2023/03/10/block-deprecation-a-tutorial/)
- [Introduction to Templates > Block markup](https://developer.wordpress.org/themes/templates/introduction-to-templates/#block-markup) | Theme Handbook
6 changes: 6 additions & 0 deletions docs/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,12 @@
"markdown_source": "../docs/getting-started/fundamentals/block-in-the-editor.md",
"parent": "fundamentals"
},
{
"title": "Markup representation of a block",
"slug": "markup-representation-block",
"markdown_source": "../docs/getting-started/fundamentals/markup-representation-block.md",
"parent": "fundamentals"
},
{
"title": "Working with Javascript for the Block Editor",
"slug": "javascript-in-the-block-editor",
Expand Down
4 changes: 2 additions & 2 deletions docs/reference-guides/filters/block-filters.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ wp.hooks.addFilter(
);
```

#### `blocks.getSaveContent.extraProps`
### `blocks.getSaveContent.extraProps`

A filter that applies to all blocks returning a WP Element in the `save` function. This filter is used to add extra props to the root element of the `save` function. For example: to add a className, an id, or any valid prop for this element.

Expand Down Expand Up @@ -229,7 +229,7 @@ const withMyPluginControls = createHigherOrderComponent( ( BlockEdit ) => {
}, 'withMyPluginControls' );
```

#### `editor.BlockListBlock`
### `editor.BlockListBlock`

Used to modify the block's wrapper component containing the block's `edit` component and all toolbars. It receives the original `BlockListBlock` component and returns a new wrapped component.

Expand Down
3 changes: 3 additions & 0 deletions docs/toc.json
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@
{
"docs/getting-started/fundamentals/block-in-the-editor.md": []
},
{
"docs/getting-started/fundamentals/markup-representation-block.md": []
},
{
"docs/getting-started/fundamentals/javascript-in-the-block-editor.md": []
}
Expand Down
2 changes: 1 addition & 1 deletion gutenberg.php
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
* Description: Printing since 1440. This is the development plugin for the block editor, site editor, and other future WordPress core functionality.
* Requires at least: 6.3
* Requires PHP: 7.0
* Version: 17.3.0-rc.1
* Version: 17.3.0
* Author: Gutenberg Team
* Text Domain: gutenberg
*
Expand Down
3 changes: 0 additions & 3 deletions lib/class-wp-theme-json-resolver-gutenberg.php
Original file line number Diff line number Diff line change
Expand Up @@ -322,9 +322,6 @@ public static function get_theme_data( $deprecated = array(), $options = array()
}
$theme_support_data['settings']['color']['defaultGradients'] = $default_gradients;

// Classic themes without a theme.json don't support global duotone.
$theme_support_data['settings']['color']['defaultDuotone'] = false;

// Allow themes to enable all border settings via theme_support.
if ( current_theme_supports( 'border' ) ) {
$theme_support_data['settings']['border']['color'] = true;
Expand Down
36 changes: 0 additions & 36 deletions lib/compat/wordpress-6.4/block-patterns.php

This file was deleted.

46 changes: 46 additions & 0 deletions lib/compat/wordpress-6.5/block-patterns.php
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,49 @@ function gutenberg_register_media_pattern_categories() {
);
}
add_action( 'init', 'gutenberg_register_media_pattern_categories' );

/**
* Adds a new taxonomy for organizing user created patterns.
*
* @see https://github.com/WordPress/gutenberg/pull/53163
*
* @return void
*/
function gutenberg_register_taxonomy_patterns() {
$args = array(
'public' => false,
'publicly_queryable' => false,
'hierarchical' => false,
'labels' => array(
'name' => _x( 'Pattern Categories', 'taxonomy general name' ),
'singular_name' => _x( 'Pattern Category', 'taxonomy singular name' ),
'add_new_item' => __( 'Add New Category' ),
'add_or_remove_items' => __( 'Add or remove pattern categories' ),
'back_to_items' => __( '&larr; Go to pattern categories' ),
'choose_from_most_used' => __( 'Choose from the most used pattern categories' ),
'edit_item' => __( 'Edit Pattern Category' ),
'item_link' => __( 'Pattern Category Link' ),
'item_link_description' => __( 'A link to a pattern category.' ),
'items_list' => __( 'Pattern Categories list' ),
'items_list_navigation' => __( 'Pattern Categories list navigation' ),
'new_item_name' => __( 'New Pattern Category Name' ),
'no_terms' => __( 'No pattern categories' ),
'not_found' => __( 'No pattern categories found.' ),
'popular_items' => __( 'Popular Pattern Categories' ),
'search_items' => __( 'Search Pattern Categories' ),
'separate_items_with_commas' => __( 'Separate pattern categories with commas' ),
'update_item' => __( 'Update Pattern Category' ),
'view_item' => __( 'View Pattern Category' ),
),
'query_var' => false,
'rewrite' => false,
'show_ui' => true,
'_builtin' => true,
'show_in_nav_menus' => false,
'show_in_rest' => true,
'show_admin_column' => true,
'show_tagcloud' => false,
);
register_taxonomy( 'wp_pattern_category', array( 'wp_block' ), $args );
}
add_action( 'init', 'gutenberg_register_taxonomy_patterns' );
Loading

0 comments on commit 2bfa462

Please sign in to comment.