Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wpengine/wp-graphql-content-blocks
Plugin that extends WPGraphQL to support querying (Gutenberg) Blocks as data
https://github.com/wpengine/wp-graphql-content-blocks
graphql wordpress wordpress-plugin wp-plugin wpgraphql
Last synced: 6 days ago
JSON representation
Plugin that extends WPGraphQL to support querying (Gutenberg) Blocks as data
- Host: GitHub
- URL: https://github.com/wpengine/wp-graphql-content-blocks
- Owner: wpengine
- License: gpl-2.0
- Created: 2022-11-08T17:40:53.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-16T14:18:29.000Z (17 days ago)
- Last Synced: 2025-01-20T11:06:06.097Z (13 days ago)
- Topics: graphql, wordpress, wordpress-plugin, wp-plugin, wpgraphql
- Language: PHP
- Homepage: https://faustjs.org/docs/gutenberg/wp-graphql-content-blocks
- Size: 1.91 MB
- Stars: 115
- Watchers: 44
- Forks: 15
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# WPGraphQL Content Blocks
[](https://github.com/wpengine/wp-graphql-content-blocks/actions/workflows/test-plugin.yml)
[](https://github.com/wpengine/wp-graphql-content-blocks/releases/latest/download/wp-graphql-content-blocks.zip)
WordPress plugin that extends WPGraphQL to support querying (Gutenberg) Blocks as data.
## How to Install
This plugin is an extension of [`wp-graphql`](https://www.wpgraphql.com/), so make sure you have it installed first.
1. Download the [latest .zip version of the plugin](https://github.com/wpengine/wp-graphql-content-blocks/releases/latest/download/wp-graphql-content-blocks.zip)
2. Upload the plugin .zip to your WordPress site
3. Activate the plugin within WordPress plugins page.
There is no other configuration needed once you install the plugin.
## Getting started
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](https://www.wpgraphql.com/), 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:
```graphql
{
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
}
}
}
}
}
}
```
## How do I query block data?
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:
```graphql
{
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`.
```json
{
"__typename": "CoreParagraph",
"name": "core/paragraph",
"attributes": {
"content": "Hello world",
"className": null
}
}
```
## What about innerBlocks?
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:
```html
Example paragraph in Column
```
It will return the following blocks:
```json
[
{
"__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](https://www.wpgraphql.com/docs/menus#hierarchical-data).
### Note
> 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 new `clientId` each time.
### Contributor License Agreement
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.
1. [Submit your name and email](https://wpeng.in/cla/)
2. 📝 Sign the CLA emailed to you
3. 📥 Receive copy of signed CLA
❤️ Thank you for helping us fulfill our legal obligations in order to continue empowering builders through headless WordPress.