You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/explanation/blocks-faq/index.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ export const metadata = {
7
7
8
8
If the block does not have any attributes or has only a few of them declared in the `block.json` for that block (you can view the `block.json` file for the block at https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/), you can still try to extend the block API by declaring additional attributes for that block.
9
9
10
-
Follow the [filters reference guide](reference/plugin-filters) to create a block that uses the `additional_block_attributes` property. The attributes will then be available to query from that block.
10
+
Follow the [filters reference guide](/docs/reference/use-blocks-theme/) to create a block that uses the `additional_block_attributes` property. The attributes will then be available to query from that block.
11
11
12
12
```php
13
13
class CoreCode extends WPGraphQL\ContentBlocks\Blocks\Block
Copy file name to clipboardExpand all lines: docs/explanation/deploy-your-app/index.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,11 +14,11 @@ Faust.js uses the `package.json` [engines field](https://docs.npmjs.com/cli/v9/c
14
14
15
15
## Building Your App
16
16
17
-
Since Faust.js is built on top of Next.js, it shares the same build process. For details on how Next.js generates optimized production builds, refer to the [Next.js Build API](<(https://nextjs.org/docs/pages/building-your-application/deploying#nextjs-build-api)>) documentation. Additionally, you can explore the Headless Platform framework guide for Next.js apps [here](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/).
17
+
Since Faust.js is built on top of Next.js, it shares the same build process. For details on how Next.js generates optimized production builds, refer to the [Next.js Build API](https://nextjs.org/docs/pages/building-your-application/deploying#nextjs-build-api) documentation. Additionally, you can explore the Headless Platform [framework guide](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/) for Next.js apps.
18
18
19
19
## Deploying to WP Engine's Headless Platform
20
20
21
-
The Headless Platform is the most effortless way to deploy a Faust.js app. Connect your GitHub repo and Atlas will automatically build and deploy your Faust.js project on each push. Some of the benefits you get out of the box are:
21
+
The Headless Platform is the most effortless way to deploy a Faust.js app. Connect your GitHub repo and Headless Platform will automatically build and deploy your Faust.js project on each push. Some of the benefits you get out of the box are:
22
22
23
23
- Automatic installation of required WordPress plugins (Faust, WPGraphQL, etc.)
24
24
- Automatic setup of Faust.js environment variables
@@ -29,7 +29,7 @@ The Headless Platform is the most effortless way to deploy a Faust.js app. Conne
29
29
30
30
Deploy your Faust.js app and try for the [Headless Platform](https://wpengine.com/headless-wordpress/#form) for free!
31
31
32
-
For further reference, please check out the Headless Platform framework guide docs on Deploying Next.js [here](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/).
32
+
For further reference, please check out the Headless Platform [framework guide](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/) docs on Deploying Next.js.
33
33
34
34
> [!NOTE]
35
35
> If deploying from the WP Engine portal using your own repository (without beginning with a blueprint), you will need to set your environment variables manually. Learn how by taking a look at our [platform docs](https://developers.wpengine.com/docs/atlas/getting-started/deploy-from-existing-repo/#set-environment-variables-optional).
Copy file name to clipboardExpand all lines: docs/explanation/react-components-to-blocks/index.mdx
+80-88Lines changed: 80 additions & 88 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,137 +6,129 @@ export const metadata = {
6
6
7
7
The `@faustwp/block-editor-utils` package provides helper functions for converting React components into blocks. This means you can use the same components in both places—your Next.js app and the WordPress Block Editor.
8
8
9
-
In this how-to guide, we will walk through the steps required to create a new block named `my-first-block` using this workflow.
9
+
## Prerequisites
10
10
11
-
## 0. Prerequisites
11
+
In order to use this feature, you need to clone down the working boilerplate example [here](https://github.com/wpengine/faustjs/tree/canary/examples/next/block-support) and follow its instructions in the `README.md` file on what plugins you need, packages you need to install and the command that needs to be run to sync the blocks to WordPress.
12
12
13
-
Make sure you have followed the [Basic Setup](/docs/how-to/basic-setup/) steps to get Faust.js set up.
13
+
> [!WARNING]
14
+
> This feature does not work with the latest version of React. It only works with React 18.
15
+
> Also, please avoid using this feature in production. It is not fully maintained.
14
16
15
-
## 1. Install the Dev Dependencies
17
+
## Creating and Registering a Block Component
16
18
17
-
First, from your root folder, install the required dev dependencies:
19
+
In the `pages/wp-blocks/block-b/Component.js` file, you will see the following code:
Now we're ready to explore the process of using this package's helpers to convert a React component to blocks.
24
-
25
-
## 2. Create and Register a Block Component
26
-
27
-
For the purposes of this guide we are using the a simple React component. Add a folder called `my-first-block` to the `wp-blocks` folder, then add the following into a jsx file called `MyFirstBlock.jsx`:
This React component consists of a `div` element with three attributes that controls the content and the style of the box. Let's describe them briefly:
69
+
This defines a React component that renders two `<div>` elements with inline styles and specific CSS class names, inserting `HTML` content from the `attributes` prop using `dangerouslySetInnerHTML`.
52
70
53
-
-**message**: is a text message that gets displayed.
54
-
-**bg_color**: controls the background color.
55
-
-**text_color**: controls the text color.
71
+
It also specifies a GraphQL fragment to fetch the necessary data for the component, particularly the message attribute, ensuring the data structure is aligned with the expected GraphQL type. Additionally, the component includes a configuration object that defines its name and editor fields, which is used to integrate and manage the block within a WordPress block editor environment.
56
72
57
-
The `MyFirstBlock.config` object here with a `name` value inside is used to specify the name of the block.
73
+
Within your `block-b/index.js` file, we see the following code:
58
74
59
-
We would like to use this React component in WordPress using the Block Editor. Traditionally, this step would require us (the developers) to register a block within WordPress, provide a `block.json` and write code for the [Edit and Save](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/) functions for the editor. Once those steps are done, then the block would be usable in the Block Editor list.
60
-
61
-
That is a lot of know-how and development effort for simply trying to use the React component in the editor side. What if we just provided the React component and let the framework handle all the block registration and creating the editor form fields for changing the content?
62
-
63
-
This is what the `@faustwp/block-editor-utils` package tries to do. It provides a `registerFaustBlock` helper function, that handles all the necessary configuration, registration and generation of Editor Form fields and [Inspector controls](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar/) for you. A developer can provide the React component and are able to review this within the WordPress Block Editor and use it in both places.
64
-
65
-
Within your `wp-blocks/my-first-block` folder replace the `index.js` contents with the following code:
The `registerFaustBlock`helper takes the following arguments:
91
+
This file imports the necessary styling, component logic, and metadata to register a React block with the WordPress block editor using the Faust.js framework. It leverages the `registerFaustBlock`utility from the `@faustwp/block-editor-utils` package, passing the component and its configuration metadata to properly initialize the block.
83
92
84
-
-**component**: the actual React component to convert into a Block Editor block. (**Required**).
85
-
-**metadata**: a metadata object that contains several fields:
86
-
-**blockJson**: the `block.json` object that describes the component attributes. (**Required**).
87
-
-**edit**: provides a custom Edit function that describes the structure of your block in the context of the editor. (**Optional**).
88
-
-**save**: provides a custom Save function that defines the way in which the different attributes should be combined into the final markup. (**Optional**).
93
+
As a result, the block is seamlessly integrated into the editor, with its visual and functional properties defined by the imported SCSS and JSON metadata.
89
94
90
-
Now let's take a look at the `block.json`. Since we declared three configurable attributes for our component, we need to declare them as attributes here.
95
+
Now let's take a look at the `block.json` file in the `block-b` folder. Since we declared three configurable attributes for our component, we need to declare them as attributes here.
91
96
92
97
Here is the final `block.json` with the assigned attributes object:
Add the following `blockset` script to your `package.json` file, then run it on the command line:
125
-
126
-
```json title="package.json"
127
-
"scripts": {
128
-
...
129
-
"blockset": "faust blockset"
130
-
},
131
-
```
132
-
133
-
```sh
134
-
npm run blockset
135
-
```
136
-
137
-
The cli tool will compile the blocks within the `wp-blocks` folder and upload them to your WordPress site in a special location that Faust uses to detect and register the blocks.
138
-
139
-
## 4. Try out the Component in the Block Editor
131
+
## Try out the Component in the Block Editor
140
132
141
133
Open the WordPress Block Editor and try out the new block. This is what it will look like at first glance in Edit mode:
142
134
@@ -146,22 +138,22 @@ You can interact with the form fields, and then click outside the block contents
146
138
147
139
148
140
149
-
## 5. Configure the Form Controls
141
+
## Configure the Form Controls
150
142
151
-
So far we've been able to render the React component in the Block Editor, change some of the attributes, and reflect the changes in the page.
143
+
So far we've been able to render the React component in the Block Editor.
152
144
153
145
However, a few of the attributes that control the color are using [text field](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/) controls, which may prove problematic since they allow invalid values. What if we wanted to use a proper color picker component?
154
146
155
147
Since the `block.json`[attribute types](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#type-validation) do not allow `color` as a value, we will have to provide a different configuration to allow that option.
156
148
157
149
When registering the React component using `registerFaustBlock`, it allows extra configuration to be used in case you want to declare which kinds of controls to use on each attribute.
158
150
159
-
In your `MyFirstBlock.jsx` file, add the following `editorFields` to your `MyFirstBlock.config` object:
151
+
In your `Component.js` file, add the following `editorFields` to your `Component.config` object:
160
152
161
-
```js title="MyFirstBlock.jsx"
153
+
```js title="block-b/Component.js"
162
154
...
163
-
MyFirstBlock.config= {
164
-
name:"MyFirstBlock",
155
+
Component.config= {
156
+
name:"CreateBlockBlockB",
165
157
editorFields: {// [!code ++]
166
158
bg_color: {// [!code ++]
167
159
location:"inspector",// [!code ++]
@@ -181,7 +173,7 @@ Once you update the component, you can refresh the page and create a new block.
181
173
182
174
183
175
184
-
## 6. Form Control Reference List
176
+
## Form Control Reference List
185
177
186
178
So far we've seen examples of two controls: The `ColorPicker` handled by the `control: "color"` and the `TextControl`, which is set as default for every `type: "string"` in the `block.json` attributes list. You can experiment with adding more, however.
> If you're not using a `src` folder in your project, you can omit "src/" from the file path above. And the same applies for other file paths mentioned throughout this doc.
84
+
82
85
### F. Update `_app.js` file
83
86
84
-
Once the API router is set up, head to `pages/_app.js` and add this code to the file:
87
+
Once the API router is set up, head to `src/pages/_app.js`. Add the `import` statements, wrap your app in the `FaustProvider`, and pass `key={router.asPath}` to `Component`, as shown below.
In order for Faust.js to run the GraphQL queries it needs to determine the correct template to use, it needs to have a list of all the types available in the GraphQL schema. We'll generate this list of types now.
107
110
111
+
In your WordPress admin sidebar, go to `GraphQL` > `Settings`. Check the `Enable Public Introspection` box if it's not checked already and save your changes. Enabling introspection is required for the `npm run generate` command below to work.
112
+
108
113
Add the following generate script to your Next.js project's `package.json` file, in the scripts block:
109
114
110
115
```json title="package.json"
@@ -124,7 +129,7 @@ Run `npm run generate` on the command line. Confirm that a possibleTypes.json ha
124
129
125
130
### B. Add a template
126
131
127
-
Create a new `wp-templates` folder in the root of your project. This is where your template files will be stored. We'll start by adding a template for rendering single blog posts.
132
+
Create a new `src/wp-templates` folder (or add the `/wp-templates` folder in the root project folder if you don't use a `/src` folder). This is where your template files will be stored. We'll start by adding a template for rendering single blog posts.
128
133
129
134
Inside the `wp-templates` folder, create a `single.js` file that contains the following code.
130
135
@@ -167,10 +172,10 @@ In the `SingleTemplate` component, we receive the props, destructure the `title`
167
172
Finally, we have to make Faust.js aware that this template exists. To do that, create an `index.js` file inside the `wp-templates` folder with this code inside:
168
173
169
174
```js title="wp-templates/index.js"
170
-
importsinglefrom"./single";
175
+
importSingleTemplatefrom"./single";
171
176
172
177
consttemplates= {
173
-
single,
178
+
single: SingleTemplate,
174
179
};
175
180
176
181
exportdefaulttemplates;
@@ -180,7 +185,7 @@ export default templates;
180
185
181
186
Create a `[...wordpressNode].js` file inside your `pages` folder. Add the following code to it.
@@ -201,7 +206,7 @@ export async function getStaticPaths() {
201
206
202
207
This catch-all route tells Next.js to use the templates to render pages.
203
208
204
-
Note that it is still possible to override this with hardcoded pages. For example, if you have a page in your WordPress site with a URI of `/about`, Faust.js will render that page using the relevant template in your project's `wp-templates` folder. However, if you add a `pages/about.js` file to your project, Next.js will render the `/about` path in your app using that file instead.
209
+
Note that it is still possible to override this with hardcoded pages. For example, if you have a page in your WordPress site with a URI of `/about`, Faust.js will render that page using the relevant template in your project's `wp-templates` folder. However, if you add a `src/pages/about.js` file to your project, Next.js will render the `/about` path in your app using that file instead.
0 commit comments