From d35679b81d8d068e56219ea0e0df3aa9a2fd3f53 Mon Sep 17 00:00:00 2001 From: Fran Agulto Date: Thu, 2 Jan 2025 12:27:29 -0600 Subject: [PATCH 1/2] added docs page for plugin creation --- .../docs/how-to/create-a-plugin/index.mdx | 75 +++++++++++++++++++ src/pages/docs/nav.json | 4 + 2 files changed, 79 insertions(+) create mode 100644 src/pages/docs/how-to/create-a-plugin/index.mdx diff --git a/src/pages/docs/how-to/create-a-plugin/index.mdx b/src/pages/docs/how-to/create-a-plugin/index.mdx new file mode 100644 index 00000000..e8ebe17c --- /dev/null +++ b/src/pages/docs/how-to/create-a-plugin/index.mdx @@ -0,0 +1,75 @@ +export const metadata = { + title: "Create A Plugin", +}; + +Faust plugins are a structured way to extend or alter the framework’s behavior, very much like WordPress plugins do in a traditional WordPress environment. Instead of `PHP`, however, Faust’s plugins are written in JavaScript/TypeScript, leveraging actions and filters to deliver similar flexibility in a headless architecture. + +## Steps + +### 1\. Basic setup + +If you haven't already, follow the [Basic Setup](/docs/how-to/basic-setup/) steps to get Faust.js set up. + +### 2\. Create A Plugins Folder and file + +In its very basic form, a Faust Plugin is a JavaScript class with an `apply` method. This apply method has a parameter called `hooks`, which is passed from `@wordpress/hooks`. Create a folder in the root of your Faust project called `plugin`. In the folder, create a file called `SamplePlugin.js`. In this file, add this code block: + +```js title="plugins/SamplePlugin.js" +import { FaustHooks } from "@faustwp/core"; + +export class MyPlugin { + /** + * @param {FaustHooks} hooks + */ + apply(hooks) { + // Plugin logic goes here + } +} +``` + +The `hooks` parameter is an object which contains the functions `addFilter` and `addAction`, amongst others. You can then use these functions to call the respective actions and filters to tap into Faust like so: + +```js {10-16} title="plugins/SamplePlugin.js " +import { FaustHooks } from "@faustwp/core"; + +export class MyPlugin { + /** + * @param {FaustHooks} hooks + */ + apply(hooks) { + const { addAction, addFilter } = hooks; + + addFilter( + "possibleTemplatesList", + "my-namespace", + (possibleTemplates, context) => { + // Filter logic goes here. + }, + ); + } +} +``` + +> **NOTE:** +> `experimentalPlugins` is being deprecated and replaced with `plugins` in the `faust.config.js` file. +> Please update your configuration accordingly. + +### 3\. Add The Plugin to the Faust Config + +You can then implement the plugin by adding it to the plugins property in the App’s `faust.config.js` file: + +```js title="faust.config.js" +import { setConfig } from "@faustwp/core"; +import templates from "./wp-templates"; +import possibleTypes from "./possibleTypes.json"; +import { MyPlugin } from "./plugins/MyPlugin.js"; + +/** + * @type {import('@faustwp/core').FaustConfig} + */ +export default setConfig({ + templates, + plugins: [new MyPlugin()], + possibleTypes, +}); +``` diff --git a/src/pages/docs/nav.json b/src/pages/docs/nav.json index bd2f0435..9ee5aa9a 100644 --- a/src/pages/docs/nav.json +++ b/src/pages/docs/nav.json @@ -27,6 +27,10 @@ { "title": "Post Previews", "route": "/docs/how-to/post-previews/" + }, + { + "title": "Create A Plugin", + "route": "/docs/how-to/create-a-plugin/" } ] }, From 5ab91726775b72e4cd188c5680a00a38a1c243a5 Mon Sep 17 00:00:00 2001 From: Alex Moon Date: Thu, 2 Jan 2025 11:07:28 -0800 Subject: [PATCH 2/2] fix: note formatting and misc cleanup --- src/pages/docs/how-to/create-a-plugin/index.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/pages/docs/how-to/create-a-plugin/index.mdx b/src/pages/docs/how-to/create-a-plugin/index.mdx index e8ebe17c..4b275e24 100644 --- a/src/pages/docs/how-to/create-a-plugin/index.mdx +++ b/src/pages/docs/how-to/create-a-plugin/index.mdx @@ -2,15 +2,15 @@ export const metadata = { title: "Create A Plugin", }; -Faust plugins are a structured way to extend or alter the framework’s behavior, very much like WordPress plugins do in a traditional WordPress environment. Instead of `PHP`, however, Faust’s plugins are written in JavaScript/TypeScript, leveraging actions and filters to deliver similar flexibility in a headless architecture. +Faust plugins are a structured way to extend or alter the framework's behavior, very much like WordPress plugins do in a traditional WordPress environment. Instead of `PHP`, however, Faust's plugins are written in JavaScript/TypeScript, leveraging actions and filters to deliver similar flexibility in a headless architecture. ## Steps -### 1\. Basic setup +### 1. Basic setup If you haven't already, follow the [Basic Setup](/docs/how-to/basic-setup/) steps to get Faust.js set up. -### 2\. Create A Plugins Folder and file +### 2. Create A Plugins Folder and file In its very basic form, a Faust Plugin is a JavaScript class with an `apply` method. This apply method has a parameter called `hooks`, which is passed from `@wordpress/hooks`. Create a folder in the root of your Faust project called `plugin`. In the folder, create a file called `SamplePlugin.js`. In this file, add this code block: @@ -50,13 +50,13 @@ export class MyPlugin { } ``` -> **NOTE:** -> `experimentalPlugins` is being deprecated and replaced with `plugins` in the `faust.config.js` file. +> [!important] Please Note +> `experimentalPlugins` is being deprecated and replaced with `plugins` in the `faust.config.js` file. > Please update your configuration accordingly. -### 3\. Add The Plugin to the Faust Config +### 3. Add The Plugin to the Faust Config -You can then implement the plugin by adding it to the plugins property in the App’s `faust.config.js` file: +You can then implement the plugin by adding it to the plugins property in the App's `faust.config.js` file: ```js title="faust.config.js" import { setConfig } from "@faustwp/core";