WordPress plugin that extends WPGraphQL to support querying (Gutenberg) Blocks as data.
This plugin is an extension of wp-graphql
, so make sure you have it installed first.
There is no other configuration needed once you install the plugin.
Once the plugin is installed, head over to the GraphiQL IDE and you should be able to perform queries for the block data (This plugin is an extension of wp-graphql, so make sure you have it installed first.).
There is a new field added in the Post and Page models called editorBlocks
.
This represents a list of available blocks for that content type:
{
posts {
nodes {
# editorBlocks field represents array of Block data
editorBlocks(flat: false) {
# fields from the interface
renderedHtml
__typename
# expand the Paragraph block attributes
... on CoreParagraph {
attributes {
content
}
}
# expand a Custom block attributes
... on CreateBlockMyFirstBlock {
attributes {
title
}
}
}
}
}
}
To query specific block data you need to define that data in the editorBlocks
as the appropriate type.
For example, to use CoreParagraph
attributes you need to use the following query:
{
posts {
nodes {
editorBlocks(flat: false) {
__typename
name
... on CoreParagraph {
attributes {
content
className
}
}
}
}
}
}
If the resolved block has values for those fields, it will return them, otherwise it will return null
.
{
"__typename": "CoreParagraph",
"name": "core/paragraph",
"attributes": {
"content": "Hello world",
"className": null
}
}
In order to facilitate querying innerBlocks
fields more efficiently you want to use editorBlocks(flat: true)
instead of editorBlocks
.
By passing this argument, all the blocks available (both blocks and innerBlocks) will be returned all flattened in the same list.
For example, given the following HTML Content:
<columns>
<column>
<p>Example paragraph in Column</p>
<p></p
></column>
<column></column
></columns>
It will return the following blocks:
[
{
"__typename": "CoreColumns",
"name": "core/columns",
"id": "63dbec9abcf9d",
"parentClientId": null
},
{
"__typename": "CoreColumn",
"name": "core/column",
"id": "63dbec9abcfa6",
"parentClientId": "63dbec9abcf9d"
},
{
"__typename": "CoreParagraph",
"name": "core/paragraph",
"id": "63dbec9abcfa9",
"parentClientId": "63dbec9abcfa6",
"attributes": {
"content": "Example paragraph in Column 1",
"className": null
}
}
]
The CoreColumns
contains one or more CoreColumn
block, and each CoreColumn
contains a CoreParagraph
.
Given the flattened list of blocks though, how can you put it back? Well that's where you use the `` and parentId
fields to assign temporary unique ids for each block.
The clientId
field assigns a temporary unique id for a specific block and the parentClientId
will
be assigned only if the current block has a parent. If the current block does have a parent, it will get the parent's clientId
value.
So in order to put everything back in the Headless site, you want to use the flatListToHierarchical
function as mentioned in the WPGraphQL docs.
Currently the
clientId
field is only unique per request and is not persisted anywhere. If you perform another request each block will be assigned a newclientId
each time.
All external contributors to WP Engine products must have a signed Contributor License Agreement (CLA) in place before the contribution may be accepted into any WP Engine codebase.
❤️ Thank you for helping us fulfill our legal obligations in order to continue empowering builders through headless WordPress.