Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add pre- and post- content filter #60

Merged
merged 9 commits into from
Apr 9, 2024
+320 −134
Merged

Add pre- and post- content filter #60

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ca15c02
Add vip_block_data_api__before_parse_post_content filter
alecgeatches Mar 27, 2024
aada721
Add post-parse vip_block_data_api__after_parse_blocks filter too
alecgeatches Mar 27, 2024
b238b2c
Add documentation for new filters
alecgeatches Apr 8, 2024
8b06ef1
Add test for before_parse filter
alecgeatches Apr 8, 2024
988a1ed
Fix GraphQL tests by removing no-longer-default "cite" attribute
alecgeatches Apr 8, 2024
fc73fc5
Convert some array() usage to []
alecgeatches Apr 8, 2024
8d970c6
Add after_parse_blocks filter test
alecgeatches Apr 8, 2024
f753421
Add before_parse filter example
alecgeatches Apr 8, 2024
c547220
Fix mistake in warning text
alecgeatches Apr 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1218,6 +1218,64 @@ Direct block HTML can be accessed through `$block['innerHTML']`. This may be use

For another example of how this filter can be used to extend block data, we have implemented a default image block filter in [`src/parser/block-additions/core-image.php`][repo-core-image-block-addition]. This filter is automatically called on `core/image` blocks to add `width` and `height` to image attributes.

---

### `vip_block_data_api__before_parse_post_content`

Modify raw post content before it's parsed by the Block Data API.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like you do with the other filter, I might mention that this is the very first thing called so that you are getting exactly what is in the WP database.

I also like the example in the other one, so we could add one here. The example helps people understand why they might use it.

We should also add a warning that manipulating the content directly can cause block parsing errors, and they should be careful with this filter. Here's the language I would use:

Block Markup is sensitive to changes, even changes in whitespace. We've added this filter to make the plugin flexible, but any changes to the post_content should be done with extreme care. Strongly consider adding tests to any filter.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great notes, especially the warning. Will add!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@smithjw1 Added an before_parse example along with a warning as you described above. Thank you!


```php
/**
* Filters content before parsing blocks in a post.
*
* @param string $post_content The content of the post being parsed.
* @param int $post_id Post ID associated with the content.
*/
$post_content = apply_filters( 'vip_block_data_api__before_parse_post_content', $post_content, $post_id );
```

---

### `vip_block_data_api__after_parse_blocks`

Modify the Block Data API REST endpoint response.

```php
/**
* Filters the API result before returning parsed blocks in a post.
*
* @param string $result The successful API result, contains 'blocks' key with an array
* of block data, and optionally 'warnings' and 'debug' keys.
* @param int $post_id Post ID associated with the content.
*/
$result = apply_filters( 'vip_block_data_api__after_parse_blocks', $result, $post_id );
```

This filter is called directly before returning a result in the REST API. Use this filter to add additional metadata or debug information to the API output.

```php
add_action( 'vip_block_data_api__after_parse_blocks', 'add_block_data_debug_info', 10, 2 );

function add_block_data_debug_info( $result, $post_id ) {
$result['debug']['my-value'] = 123;

return $result;
}
```

This would add `debug.my-value` to all Block Data API REST results:

```bash
> curl https://my.site/wp-json/vip-block-data-api/v1/posts/1/blocks

{
"debug": {
"my-value": 123
},
"blocks": [ /* ... */ ]
}
```

## Analytics

**Please note that, this is for VIP sites only. Analytics are disabled if this plugin is not being run on VIP sites.**
Expand Down
17 changes: 17 additions & 0 deletions src/parser/content-parser.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,14 @@ public function parse( $post_content, $post_id = null, $filter_options = [] ) {
$parsing_error = false;

try {
/**
* Filters content before parsing blocks in a post.
*
* @param string $post_content The content of the post being parsed.
* @param int $post_id Post ID associated with the content.
*/
$post_content = apply_filters( 'vip_block_data_api__before_parse_post_content', $post_content, $post_id );

$blocks = parse_blocks( $post_content );
$blocks = array_values( array_filter( $blocks, function ( $block ) {
$is_whitespace_block = ( null === $block['blockName'] && empty( trim( $block['innerHTML'] ) ) );
Expand Down Expand Up @@ -168,6 +176,15 @@ public function parse( $post_content, $post_id = null, $filter_options = [] ) {
'details' => $parsing_error->__toString(),
] );
} else {
/**
* Filters the API result before returning parsed blocks in a post.
*
* @param string $result The successful API result, contains 'blocks'
* key with an array of block data, and optionally 'warnings' and 'debug' keys.
* @param int $post_id Post ID associated with the content.
*/
$result = apply_filters( 'vip_block_data_api__after_parse_blocks', $result, $post_id );

return $result;
}
}
Expand Down
124 changes: 50 additions & 74 deletions tests/graphql/test-graphql-api.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,12 @@ public function test_get_blocks_data() {
<!-- wp:paragraph -->
<p>Welcome to WordPress. This is your first post. Edit or delete it, then start writing!</p>
<!-- /wp:paragraph -->

<!-- wp:quote -->
<blockquote class="wp-block-quote"><!-- wp:paragraph -->
<p>This is a heading inside a quote</p>
<!-- /wp:paragraph -->

<!-- wp:quote -->
<blockquote class="wp-block-quote"><!-- wp:heading -->
<h2 class="wp-block-heading">This is a heading</h2>
Expand All @@ -49,68 +49,60 @@ public function test_get_blocks_data() {
[
'name' => 'core/paragraph',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'Welcome to WordPress. This is your first post. Edit or delete it, then start writing!',
),
array(
],
[
'name' => 'dropCap',
'value' => '',
),
],
],
'id' => '1',
],
[
'name' => 'core/quote',
'attributes' => [
array(
[
'name' => 'value',
'value' => '',
),
array(
'name' => 'citation',
'value' => '',
),
],
],
'innerBlocks' => [
[
'name' => 'core/paragraph',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'This is a heading inside a quote',
),
array(
],
[
'name' => 'dropCap',
'value' => '',
),
],
],
'id' => '3',
],
[
'name' => 'core/quote',
'attributes' => [
array(
[
'name' => 'value',
'value' => '',
),
array(
'name' => 'citation',
'value' => '',
),
],
],
'innerBlocks' => [
[
'name' => 'core/heading',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'This is a heading',
),
array(
],
[
'name' => 'level',
'value' => '2',
),
],
],
'id' => '5',
],
Expand All @@ -137,68 +129,60 @@ public function test_flatten_inner_blocks() {
[
'name' => 'core/paragraph',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'Welcome to WordPress. This is your first post. Edit or delete it, then start writing!',
),
array(
],
[
'name' => 'dropCap',
'value' => '',
),
],
],
'id' => '2',
],
[
'name' => 'core/quote',
'attributes' => [
array(
[
'name' => 'value',
'value' => '',
),
array(
'name' => 'citation',
'value' => '',
),
],
],
'innerBlocks' => [
[
'name' => 'core/paragraph',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'This is a heading inside a quote',
),
array(
],
[
'name' => 'dropCap',
'value' => '',
),
],
],
'id' => '4',
],
[
'name' => 'core/quote',
'attributes' => [
array(
[
'name' => 'value',
'value' => '',
),
array(
'name' => 'citation',
'value' => '',
),
],
],
'innerBlocks' => [
[
'name' => 'core/heading',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'This is a heading',
),
array(
],
[
'name' => 'level',
'value' => '2',
),
],
],
'id' => '6',
],
Expand All @@ -214,74 +198,66 @@ public function test_flatten_inner_blocks() {
[
'name' => 'core/paragraph',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'Welcome to WordPress. This is your first post. Edit or delete it, then start writing!',
),
array(
],
[
'name' => 'dropCap',
'value' => '',
),
],
],
'parentId' => '1',
'id' => '2',
],
[
'name' => 'core/quote',
'attributes' => [
array(
[
'name' => 'value',
'value' => '',
),
array(
'name' => 'citation',
'value' => '',
),
],
],
'id' => '3',
'parentId' => '1',
],
[
'name' => 'core/paragraph',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'This is a heading inside a quote',
),
array(
],
[
'name' => 'dropCap',
'value' => '',
),
],
],
'id' => '4',
'parentId' => '3',
],
[
'name' => 'core/quote',
'attributes' => [
array(
[
'name' => 'value',
'value' => '',
),
array(
'name' => 'citation',
'value' => '',
),
],
],
'id' => '5',
'parentId' => '3',
],
[
'name' => 'core/heading',
'attributes' => [
array(
[
'name' => 'content',
'value' => 'This is a heading',
),
array(
],
[
'name' => 'level',
'value' => '2',
),
],
],
'id' => '6',
'parentId' => '5',
Expand Down
Loading
Loading