Skip to main content

Getting Started with Gutenberg Blocks Provider and Viewer

Quick Start​

note

Make sure you have completed the initial setup for Faust at Getting Started.

Install the blocks package:

npm i @faustwp/blocks

Create a new folder inside your application root that you will place all the blocks. For conventional reasons, we name it wp-blocks.

wp-blocks/index.js
export default {};

Open _app.js and import the blocks provider, passing the list of blocks in the config property:

import { WordPressBlocksProvider } from '@faustwp/blocks';
import blocks from '../wp-blocks';

<FaustProvider pageProps={pageProps}>
<WordPressBlocksProvider
config={{
blocks,
}}>
<Component {...pageProps} key={router.asPath} />
</WordPressBlocksProvider>
</FaustProvider>

Then, inside your templates you need to pass on the editorBlocks data in your WordPressBlocksViewer. The helper function flatListToHierarchical is referenced here:

wp-templates/single.js
import { WordPressBlocksViewer } from '@faustwp/blocks';
import components from '../wp-blocks';

const { editorBlocks } = props.data.post;
const blocks = flatListToHierarchical(editorBlocks);

return <WordPressBlocksViewer blocks={blocks}/>

Example editorBlocks GraphQL query fragment.

${components.CoreParagraph.fragments.entry}
editorBlocks(flat: false) {
__typename
renderedHtml
id: clientId
parentClientId
...${components.CoreParagraph.fragments.key}
}
note

Setting flat: false above returns separate nodes with their own arrays. By default, editorBlocks brings all the nodes back in one array instead.

A Simple Block Example​

This is a simple block called CoreParagraph. The block is a p tag that sets its content to attributes.content which is passed in from the props.

CoreParagraph.fragments does a WPGraphQL query for the content and cssClassName and sets it as the fragment CoreParagraphFragment.

import { gql } from '@apollo/client';
import React from 'react';

export default function CoreParagraph(props) {
const attributes = props.attributes;
return (
<p
className={attributes?.cssClassName}
dangerouslySetInnerHTML={{ __html: attributes.content }}></p>
);
}

CoreParagraph.fragments = {
entry: gql`
fragment CoreParagraphFragment on CoreParagraph {
attributes {
content
cssClassName
}
}
`,
key: `CoreParagraphFragment`,
};

CoreParagraph.displayName = 'CoreParagraph';
// This also works
// CoreParagraph.config.name = 'CoreParagraph'
note

We added a displayName property here to make sure that the __typename of the block matches this value. For production builds, it is required to use either a displayName="NameOfBlock" or a config.name="NameOfBlock" properties for the block to resolve and render properly.

Export the block in wp-blocks/index.js:

import CoreParagraph from './CoreParagraph';
export default {
CoreParagraph,
};

Further Learning​

More details on the WordPressBlocksProvider.

More details on the WordPressBlocksViewer.

Continue learning about the project structure, how to change styles, layout, etc. by referencing the Example Project Walkthrough Structure.