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

Include an example of blocks.getSaveElement use #8470

Closed
wants to merge 2 commits into from
Closed

Include an example of blocks.getSaveElement use #8470

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f723579
Include an example of `blocks.getSaveElement` use
danielbachhuber Aug 3, 2018
f2f1c56
Provide a word of warning to the end user
danielbachhuber Aug 6, 2018
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
37 changes: 37 additions & 0 deletions docs/extensibility/extending-blocks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,43 @@ wp.hooks.addFilter(

A filter that applies to the result of a block's `save` function. This filter is used to replace or extend the element, for example using `wp.element.cloneElement` to modify the element's props or replace its children, or returning an entirely new element.

Notably, while you _can_ modify a block's `save` result from a theme or plugin, this behavior won't persist when the theme or plugin is deactivated.

_Example:_

Include a custom data attribute on the Image Block `<img>` tag when the block attribute is set.

```js
function addCustomDataAttribute( element, blockType, attributes ) {
if ( 'core/image' !== blockType.name ) {
return element;
}

if ( ! attributes.myCustomAttribute.length ) {
return element;
}
// Modifying nested JavaScript objects is pretty awful.
Copy link
Member

Choose a reason for hiding this comment

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

  • This should probably be using cloneElement to override props
  • Deep object assignment can be improved by using _.merge instead

Copy link
Member Author

Choose a reason for hiding this comment

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

Can you provide an example?

Copy link
Member

Choose a reason for hiding this comment

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

// Bad:
return _.assign( {}, element, { myprop: 'foo' } );

// Good:
return wp.element.cloneElement( element, { myprop: 'foo' } );

element = lodash.assign( {}, element, {
props: lodash.assign( {}, element.props, {
children: [
lodash.assign( {}, element.props.children[0], {
Copy link
Member

Choose a reason for hiding this comment

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

This will not assign data-custom-attribute when the image is assigned a URL. The deep override should be a signal of its fragility.

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't follow this either. Can you explain further?

Copy link
Member

Choose a reason for hiding this comment

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

The markup shape changes depending on whether the image block has a url attribute assigned.

Aside: It's maybe telling that this is an easy thing to overlook.

props: lodash.assign( {}, element.props.children[0].props, {
'data-custom-attribute': attributes.myCustomAttribute,
} )
} )
],
} )
} );
return element;
};

wp.hooks.addFilter(
'blocks.getSaveElement',
'my-plugin/add-custom-data-attribute',
addCustomDataAttribute
);
```

#### `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. It receives the current props of the `save` element, the block type and the block attributes as arguments.
Expand Down