Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Quartz/wp-graphql-content-blocks
Structured content blocks for WPGraphQL
https://github.com/Quartz/wp-graphql-content-blocks
Last synced: 3 months ago
JSON representation
Structured content blocks for WPGraphQL
- Host: GitHub
- URL: https://github.com/Quartz/wp-graphql-content-blocks
- Owner: Quartz
- Created: 2018-04-23T22:31:22.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2021-12-15T11:34:55.000Z (about 3 years ago)
- Last Synced: 2024-08-02T05:15:15.412Z (6 months ago)
- Language: PHP
- Homepage:
- Size: 94.7 KB
- Stars: 76
- Watchers: 6
- Forks: 16
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-wordpress-gatsby - WPGraphQL Content Blocks - This FREE plugin from the folks at QZ.com exposes a way to query HTML content from WordPress Posts and Pages as “Blocks” (not related to Gutenberg) to bring more structure to your queried content. (Plugins / WordPress)
README
# WPGraphQL Content Blocks (Structured Content)
This [WPGraphQL](https://github.com/wp-graphql/wp-graphql) plugin returns a WordPress post’s content as a shallow tree of blocks and allows for some limited validation and cleanup. This is helpful for rendering post content within component-based front-end ecosystems like React.
## What this plugin does
This plugin adds a GraphQL field called `blocks` to `Post` in WPGraphQL (and any other post types configured to appear in WPGraphQL).
The `blocks` field contains a list of the root-level blocks that comprise the post's content. Each block is a distinct HTML element, embeddable URL, shortcode, or Gutenberg block (beta!).
For example, if a post’s `content` field in GraphQL contained:
```html
Hello world
- Here is a list
```
Then the `blocks` field would contain:
```json
[
{
"type": "P",
"innerHtml": "Hello world"
},
{
"type": "UL",
"innerHTML": "
}
]
```
When consuming this field, you can now easily iterate over the blocks and map them to components in your component library. No more `dangerouslySetInnerHTML`ing your entire `post_content`!
## GraphQL fields and types
An exhaustive GraphQL of a post’s `blocks` field would look like this:
```graphql
blocks {
type
tagName
innerHtml
attributes {
name
value
}
connections {
... on Post {
...PostParts
}
... on MediaItem {
...MediaItemParts
}
}
}
```
This will return a list of `BlockTypes`, defined in `src/types/Blocktype.php`. Let’s break down each of these fields:
### `type`
Type: `BlockNameEnumType` (defined in `src/types/enums/BlockNameEnumType.php`)
The name of the block. For HTML blocks, this is the uppercase version of the HTML tag name, e.g. `P`, `UL`, `BLOCKQUOTE`, `TABLE` etc. Shortcode and embed types are name-spaced with `SHORTCODE_` and `EMBED_` respectively., e.g. `SHORTCODE_CAPTION`, `EMBED_INSTAGRAM`, etc.
HTML block types are hardcoded, as are Gutenberg block types (for now). Embed types are determined by the handlers that have been registered in `global $wp_embed->handlers` and shortcodes are determined by the handlers registered with `global $shortcode_tags`. A complete list of permissible block names can seen by browsing the WPGraphQL schema.
You can filter the type definitions with `graphql_blocks_definitions`.
### tagName
Type: `String`
The suggested HTML tag name for the block. For HTML blocks, this is simply a lowercased version of the type field. For embeds and shortcodes, it will likely be `null`. This field is most useful for Gutenberg blocks, as a hint from the server for which tag to use when wrapping the `innerHtml` (see below).
### `innerHtml`
Type: `String`
The stringified inner content of the block. Can be passed into a React component using `dangerouslySetInnerHTML`, for example.
Note that the value of `innerHtml` is the stringified version of all the block’s descendants *after* they have been parsed. This means that any invalid tags, attributes, etc. will have been stripped out.
### `attributes`
Type: List of `BlockAttributeType`s
Each item in the list is a name/value pair describing an attribute of the block. For HTML blocks, these are taken from the HTML attributes, e.g.
```json
{
"name": "id",
"value": "section1"
}
```
Note that this field will only contain valid attributes for the given Block, as defined in `BlockDefinitions`. Invalid attributes are stripped out during the parsing process (see [How Parsing Works](#how-parsing-works)).
### `connections` (beta)
Type: List of `MenuItemObjectUnion`s
The `connections` field returns an array of objects that are connected to the block. For example, if you wanted to upload an image and associate it with a block, that image could be queried as a GraphQL connection here. The `connections` field will **always be empty by default**. Presumably there is some way to derive these connections from the block's attributes, but we have no way of knowing what that correspondence is. If you'd like to use this field, it's up to you to filter `graphql_blocks_output` and populate the `connections` array as you see fit.
## Blocks
### What is a block?
A block is an atomic piece of content that comprises an article body. We define a block as being an HTML tag (like a paragraph, list, table, etc), a Gutenberg block, a text node (the textual content of a non-empty HTML element or shortcode), a [shortcode](https://codex.wordpress.org/shortcode) (like a caption, gallery, or video), or an [embed](https://codex.wordpress.org/Embeds) (an embeddable URL on its own line in the post content).
### HTML Blocks
An HTML block is an HTML element (typically a [block-level](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements) element) represented by its tag name. If an HTML tag’s name is not included in `BlockNameEnumType`, it will be stripped from the tree. Additionally, at runtime it must meet the requirements specified in the block definitions in order to be considered valid.
An example HTML block in a GraphQL response looks like this:
```json
{
"type": "P",
"innerHtml": "This isn’t the first time Facebook has unveiled new privacy settings in response to user concerns. It debuted a redesign that promised to give users more control over their data back in 2010. “People think that we don’t care about privacy, but that’s not true,” Zuckerberg said at the time. Yet some observers, including Quartz reporter Mike Murphy, remain skeptical.",
"attributes": []
}
```
### Gutenberg blocks (beta)
Gutenberg blocks map very well to blocks, but do not have a server-side registration system. Like HTML blocks, we are forced to hardcode a list of core Gutenberg blocks. This list can be extended with `graphql_blocks_definitions` to add your own custom Gutenberg blocks.
Another issue with Gutenberg is that the markup of a (non-dynamic) block is defined only in JavaScript and then rendered directly into `post_content`. While we are most interested in the `attributes` of a block, the `innerHtml` is also important since the rendered tag name could be important information to, say, a React component tasked with its implementation.
For this reason, we descend into the `innerHtml` of a Gutenberg block to extract the `tagName` of the surrounding tag, then discard it, leaving just the true "inner" HTML of the block.
```json
{
"type": "CORE_HEADING",
"tagName": "h2",
"attributes": [],
"innerHtml": "My Heading"
}
```
In the example above, this allows the `innerHtml` to be `My Heading` instead of `
My Heading
`. This is a much better situation for the components that implement this data.Gutenberg blocks present a number of challenges and the spec is still evolving. Take care when using this plugin with Gutenberg blocks since there will likely be breaking changes ahead.
### Shortcode and Embed Blocks
A shortcode block is a WordPress shortcode. *Shortcode/embed blocks are returned untransformed*: the parsing of shortcodes is the responsibility of the front-end consuming the GraphQL endpoint. Only the name of the shortcode, its attributes and any nested content of the shortcode are returned in the GraphQL response.
Shortcode block type names are prefixed with the `SHORTCODE_` namespace by default.
```json
{
"type": "SHORTCODE_PULLQUOTE",
"innerHtml": "Here is some HTML within a shortcode",
"attributes": []
}
```
An embed is a distinct block-type that represents WordPress’ [URL-to-markup embedding functionality](https://codex.wordpress.org/Embeds). If WordPress recognizes a URL as an embed, this plugin will output it as an embed block.
Embed block type names are prefixed with the `EMBED_` namespace by default.
```json
{
"type": "EMBED_TWITTER",
"innerHtml": "",
"attributes": [
{
"name": "url",
"value": "https://twitter.com/mcwm/status/978975850455556097"
}
]
}
```
Because neither shortcode or embed blocks are parsed, the markup for embedding the URL is not provided by the plugin.
### Block definitions
We can specify validation requirements for individual blocks. This allows us to enforce certain rules about blocks that determine where they end up in the tree, what attributes they may have, and whether or not they should end up in the GraphQL response at all.
Block definitions (and the default definition from which all blocks extend) for blocks can be found in `src/types/shared/BlockDefinitions`. If you are interested in filtering the block definitions (via `graphql_blocks_definitions`) to override behavior or add your own block definitions, you should look over that file.
Our default block definition suits us well for most block HTML elements; we always want them to exist at the root and we will hoist them to the root if we find them nested deeper in the post content HTML. We therefore don’t provide any overrides for most block elements:
```php
'blockquote' => [],
'figure' => [],
'h1' => [],
'h2' => [],
'h3' => [],
'h4' => [],
'h5' => [],
'h6' => [],
'hr' => [],
// etc
```
We permit `
` tags to live at the root, but we do not enforce it (i.e. we don’t want to hoist a `
` tag out of a parent element) so we use this definition.
```php
'p' => [
'root_only' => false,
],
```
We don’t want inline HTML elements like `` to exist by themselves at the root, and we don’t want to permit the `target` attribute, so we use the following definition:
```php
'a' => [
'attributes' => array(
'deny' => array( 'target' ),
),
'root_only' => false,
'allow_root' => false,
],
```
Then we would expect a query for the blocks that comprise the post to return the following.
Query:
```graphql
{
post(id: "cG9zdDoxMjM5NzIx") {
blocks {
type
innerHtml
}
}
}
```
Response:
```json
{
"data": {
"post": {
"blocks": [
{
"type": "P",
"innerHtml": "Now this is a story all about how
My life got flipped turned upside down
And I’d like to take a minute, just sit right there
I’ll tell you how I became the prince of a town called Bel-Air"
},
{
"type": "EMBED_YOUTUBE",
"innerHtml": ""
},
{
"type": "P",
"innerHtml": "In West Philadelphia, born and raised
On the playground is where I spent most of my days
Chillin’ out, maxin’, relaxin’ all cool
And all shootin’ some b-ball outside of the school
When a couple of guys who were up to no good
Started makin’ trouble in my neighborhood
I got in one little fight and my mom got scared
And said “You’re movin’ with your auntie and uncle in Bel-Air"
},
{
"type": "SHORTCODE_PULLQUOTE",
"innerHtml": "You’re movin’ with your auntie and uncle in Bel-Air"
},
{
"type": "P",
"innerHtml": "I begged and pleaded with her day after day
But she packed my suitcase and sent me on my way
She gave me a kiss and then she gave me my ticket
I put my Walkman on and said “I might as well kick it”
First class, yo, this is bad
Drinkin’ orange juice out of a champagne glass
Is this what the people of Bel-Air livin’ like?
Hmmm, this might be all right
But wait, I hear they’re prissy, bourgeois, and all that
Is this the type of place that they just sent this cool cat?
I don’t think so, I’ll see when I get there
I hope they’re prepared for the Prince of Bel-Air"
},
{
"type": "IMG",
"innerHtml": ""
}
]
}
}
}
```
We can also see the attributes for the shortcode and embed blocks by requesting the `attributes` field.
Query:
```graphql
{
post(id: "cG9zdDoxMjM5NzIx") {
blocks {
type
attributes {
name
value
}
}
}
}
```
Response:
```json
{
"data": {
"post": {
"blocks": [
{
"type": "P",
"attributes": []
},
{
"type": "EMBED_YOUTUBE",
"attributes": [
{
"name": "url",
"value": "https://www.youtube.com/watch?v=AVbQo3IOC_A"
}
]
},
{
"type": "P",
"attributes": []
},
{
"type": "SHORTCODE_PULLQUOTE",
"attributes": []
},
{
"type": "P",
"attributes": []
},
{
"type": "IMG",
"attributes": [
{
"name": "src",
"value": "https://example.com/fresh-prince.jpeg"
},
{
"name": "alt",
"value": "The Fresh Prince of Bel Air"
}
]
}
]
}
}
}
```