Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
136 lines (101 sloc) 4.06 KB
title description
WPGraphQL Content Blocks
Access Post Content as Blocks using GraphQL

About

This WPGraphQL 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:

<p>Hello world</p>
<ul>
	<li>Here is a list</li>
</ul>

Then the blocks field would contain:

[
	{
		"type": "P",
		"innerHtml": "Hello world"
	},
	{
		"type": "UL",
		"innerHTML": "<li>Here is a list</li>"
	}
]

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:

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 BlockAttributeTypes

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.

{
	"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).

connections (beta)

Type: List of MenuItemObjectUnions

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

You can’t perform that action at this time.