Skip to content

Commit 5087990

Browse files
ahuseynahuseyn
authored
Merge branch 'main' into prepare-docs-for-website
2 parents 99a8a3a + 3bda7d7 commit 5087990

File tree

16 files changed

+230
-69
lines changed

16 files changed

+230
-69
lines changed

plugins/hwp-previews/ACTIONS_AND_FILTERS.md renamed to docs/plugins/hwp-previews/explanation/actions-and-filters/index.md

Lines changed: 3 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,10 @@
1-
# Actions & Filters
2-
3-
## Table of Contents
4-
5-
- [PHP Actions](#php-actions)
6-
- [PHP Filters](#php-filters)
7-
- [Examples](#examples)
8-
- [Actions](#actions)
9-
- [Filters](#filters)
10-
- [Contributing](#contributing)
11-
1+
---
2+
title: "Actions and Filters"
3+
description: "Learn about the available PHP actions and filters in HWP Previews plugin for customizing plugin behavior, settings, and integrations."
124
---
135

146
This document lists the available PHP actions and filters provided by the HWP Previews plugin, along with explanations and usage examples. These hooks allow you to customize plugin behavior, settings, and integration with other plugins or your theme.
157

16-
---
178

189
## PHP Actions
1910

@@ -25,7 +16,6 @@ This document lists the available PHP actions and filters provided by the HWP Pr
2516
| `hwp_previews_settings_init` | Fired after the settings page is initialized. |
2617
| `hwp_previews_settings_form_manager_init` | Fired after the settings form manager is initialized. |
2718

28-
---
2919

3020
## PHP Filters
3121

@@ -39,7 +29,6 @@ This document lists the available PHP actions and filters provided by the HWP Pr
3929
| `hwp_previews_filter_available_post_types` | Filter the available post types for previews (affects settings UI and preview logic). |
4030
| `hwp_previews_filter_available_post_statuses` | Filter the available post statuses for previews. |
4131

42-
---
4332

4433
## Examples
4534

‎docs/plugins/hwp-previews/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,18 @@ To implement previews from scratch, refer to your framework's documentation:
119119

120120
HWP Previews automatically integrates with [Faust.js](https://faustjs.org/) when both plugins are active. See the [Integrate with Faust.js](how-to/integrate-with-faust/index.md) guide for details.
121121

122+
## Uninstallation
123+
124+
By default, HWP Previews preserves all settings when the plugin is deactivated to prevent accidental data loss.
125+
126+
If you would like to remove all plugin settings and data, you must set the PHP constant before you uninstall the plugin:
127+
128+
```php
129+
define( 'HWP_PREVIEWS_UNINSTALL_PLUGIN', true );
130+
```
131+
132+
You can add this constant to your `wp-config.php` file if you want to enable automatic cleanup during uninstallation.
133+
122134
## Contributing
123135

124136
If you feel like something is missing or you want to add documentation, we encourage you to contribute! Please check out our [Contributing Guide](https://github.com/wpengine/hwptoolkit/blob/main/CONTRIBUTING.md) for more details.

‎plugins/composer-packages.json‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,58 @@
11
{
22
"packages": {
33
"wpengine/hwp-previews": {
4+
"0.0.14": {
5+
"name": "wpengine/hwp-previews",
6+
"version": "0.0.14",
7+
"type": "wordpress-plugin",
8+
"description": "A WordPress plugin for headless previews.",
9+
"homepage": "https://github.com/wpengine/hwptoolkit",
10+
"license": "GPL-2.0",
11+
"authors": [
12+
{
13+
"name": "WP Engine Headless OSS Development Team",
14+
"email": "[email protected]",
15+
"homepage": "https://wpengine.com/"
16+
}
17+
],
18+
"support": {
19+
"issues": "https://github.com/wpengine/hwptoolkit/issues",
20+
"email": "[email protected]"
21+
},
22+
"dist": {
23+
"url": "https://github.com/wpengine/hwptoolkit/releases/download/%40wpengine%2Fhwp-previews-wordpress-plugin-0.0.14/hwp-previews.zip",
24+
"type": "zip"
25+
},
26+
"require": {
27+
"composer/installers": "~1.0 || ~2.0"
28+
}
29+
},
30+
"0.0.13": {
31+
"name": "wpengine/hwp-previews",
32+
"version": "0.0.13",
33+
"type": "wordpress-plugin",
34+
"description": "A WordPress plugin for headless previews.",
35+
"homepage": "https://github.com/wpengine/hwptoolkit",
36+
"license": "GPL-2.0",
37+
"authors": [
38+
{
39+
"name": "WP Engine Headless OSS Development Team",
40+
"email": "[email protected]",
41+
"homepage": "https://wpengine.com/"
42+
}
43+
],
44+
"support": {
45+
"issues": "https://github.com/wpengine/hwptoolkit/issues",
46+
"email": "[email protected]"
47+
},
48+
"dist": {
49+
"url": "https://github.com/wpengine/hwptoolkit/releases/download/%40wpengine%2Fhwp-previews-wordpress-plugin-0.0.13/hwp-previews.zip",
50+
"type": "zip"
51+
},
52+
"require": {
53+
"composer/installers": "~1.0 || ~2.0"
54+
}
55+
},
456
"0.0.12": {
557
"name": "wpengine/hwp-previews",
658
"version": "0.0.12",

‎plugins/hwp-previews/CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
# HWP Previews
22

3+
## 0.0.14
4+
5+
### Patch Changes
6+
7+
- [#525](https://github.com/wpengine/hwptoolkit/pull/525) [`a120c89`](https://github.com/wpengine/hwptoolkit/commit/a120c899d6f8fe2b11ec122e142da24d7859dbda) Thanks [@ahuseyn](https://github.com/ahuseyn)! - Add optional data cleanup on uninstall via HWP_PREVIEWS_UNINSTALL_PLUGIN constant
8+
9+
## 0.0.13
10+
11+
### Patch Changes
12+
13+
- [#519](https://github.com/wpengine/hwptoolkit/pull/519) [`0dff8ff`](https://github.com/wpengine/hwptoolkit/commit/0dff8fff953767fd33c2a864909955b28a620b75) Thanks [@ahuseyn](https://github.com/ahuseyn)! - Changed documentation links on wp-admin
14+
315
## 0.0.12
416

517
### Patch Changes

‎plugins/hwp-previews/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
- [Using With Faust.js](#using-with-faustjs)
3636
- [Extending the Functionality](#extending-the-functionality)
3737
- [Testing](#testing)
38+
- [Uninstallation](#uninstallation)
3839

3940
## Overview
4041

@@ -171,6 +172,18 @@ See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehe
171172

172173
See [Testing.md](TESTING.md) for details on how to test the plugin.
173174

175+
## Uninstallation
176+
177+
By default, HWP Previews preserves all settings when the plugin is deactivated to prevent accidental data loss.
178+
179+
If you would like to remove all plugin settings and data, you must set the PHP constant before you uninstall the plugin:
180+
181+
```php
182+
define( 'HWP_PREVIEWS_UNINSTALL_PLUGIN', true );
183+
```
184+
185+
You can add this constant to your `wp-config.php` file if you want to enable automatic cleanup during uninstallation.
186+
174187
## Screenshots
175188

176189
<details>

‎plugins/hwp-previews/composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"type": "wordpress-plugin",
44
"description": "A WordPress plugin for headless previews.",
55
"license": "GPL-2.0",
6-
"version": "0.0.12",
6+
"version": "0.0.14",
77
"authors": [
88
{
99
"name": "WP Engine Headless OSS Development Team",

‎plugins/hwp-previews/examples/hwp-preview-rest/.wp-env.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"phpVersion": "7.4",
33
"plugins": [
44
"https://github.com/Tmeister/wp-api-jwt-auth/archive/refs/tags/1.3.8.zip",
5-
"../../../plugins/hwp-previews"
5+
"https://github.com/wpengine/hwptoolkit/releases/download/%40wpengine%2Fhwp-previews-wordpress-plugin-0.0.12/hwp-previews.zip"
66
],
77
"config": {
88
"WP_DEBUG": true,

‎plugins/hwp-previews/examples/hwp-preview-rest/README.md‎

Lines changed: 28 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,26 @@
1-
# Example: Headless WordPress Previews with Nextjs App Router and REST API
1+
---
2+
title: "Headless WordPress Previews with Next.js App Router and REST API"
3+
description: "This demonstrates the usage of HWP Previews with Next.js App Router and REST API. It uses JWT authentication to fetch posts in draft status and implements a login modal for front-end authentication, showcasing an alternative approach to the Draft Mode implementation."
4+
---
5+
6+
# Example: Headless WordPress Previews with Next.js App Router and REST API
27

38
> [!NOTE]
4-
> Check out [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) if you need the previews implementation with Nextjs pages router, Draft Mode or WordPress Application Passwords.
9+
> Check out [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) if you need the previews implementation with Next.js pages router, Draft Mode or WordPress Application Passwords.
510
611
## Overview
712

8-
The purpose of this example is to showcase different use cases of HWP Previews. The example demonstrates the usage of [HWP Previews](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews) with Nextjs App Router and REST API. Example uses credentials authentication to fetch the posts in draft status. Unlike [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) this example don't use [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode).
13+
The purpose of this example is to showcase different use cases of HWP Previews. The example demonstrates the usage of [HWP Previews](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews) with Next.js App Router and REST API. Example uses credentials authentication to fetch the posts in draft status. Unlike [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) this example doesn't use [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode).
914

1015
The example includes a wp-env setup, which will allow you to build and start this example quickly. With this wp-env setup, you don't need to have a separate WordPress instance or demo data to inspect the example.
1116

12-
> [!CAUTION]
13-
> The HWP Previews plugin is currently in beta. While it's more stable than earlier versions, you may still encounter occasional bugs or incomplete features. Regular updates will continue as development progresses. Use with care and consider providing feedback to help improve the plugin.
17+
## What does this example do
18+
19+
1. Preview posts, pages and custom post types using WordPress REST API
20+
2. Use JWT authentication for secure access to draft content
21+
3. Next.js App Router implementation without Draft Mode
22+
4. Login modal for front-end authentication
23+
5. Configured WordPress instance with demo data and required plugins, using wp-env.
1424

1525
## Screenshots
1626

@@ -52,47 +62,42 @@ The example includes a wp-env setup, which will allow you to build and start thi
5262

5363
**Note** Please make sure you have all prerequisites installed as mentioned above and Docker running (`docker ps`)
5464

55-
### Setup Repository and Packages
65+
### 1. Setup Repository and Packages
5666

5767
- Clone the repo `git clone https://github.com/wpengine/hwptoolkit.git`
5868
- Install packages `cd hwptoolkit && npm install`
5969

60-
### Build and start the application
70+
### 2. Build and start the application
6171

62-
- `cd examples/next/hwp-preview-rest`
72+
- `cd plugins/hwp-previews/examples/hwp-preview-rest`
6373
- Then run `npm run example:build` will build and start your application.
64-
- This does the following:
65-
- Unzips `wp-env/uploads.zip` to `wp-env/uploads` which is mapped to the wp-content/uploads directory for the Docker container.
66-
- Starts up [wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
67-
- Imports the database from [wp-env/db/database.sql](wp-env/db/database.sql)
68-
- Install Next.js dependencies for `example-app`
69-
- Runs the Next.js dev script
7074

71-
Congratulations, WordPress should now be fully set up.
75+
This starts the wp-env instance and frontend application. You can access them now, but one more installation step remains.
76+
77+
> [!IMPORTANT]
78+
> After logging in to the WordPress instance, ensure that all installed plugins are activated for this example to work properly.
7279
7380
| Frontend | Admin |
7481
| ---------------------- | ------------------------------- |
7582
| http://localhost:3000/ | http://localhost:8888/wp-admin/ |
7683

7784
> **Note:** The login details for the admin is username "admin" and password "password"
7885
79-
### Add environment variable to the Nextjs
80-
81-
Create a .env file under `examples/next/hwp-preview-rest/example-app` and add copy-paste the environment variable below:
86+
### 3. Add environment variable to the Next.js application
8287

88+
Create a .env file under `plugins/hwp-previews/examples/hwp-preview-rest/example-app` and add the environment variable below:
8389

8490
```bash
8591
NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
8692
```
8793

88-
### Usage
94+
> [!CAUTION]
95+
> This setup is intended for demonstration purposes only. For production use, you should consider the security implications and implement appropriate measures based on your project's specific needs.
8996
90-
After completing this step, login to your [WordPress instance](http://localhost:8888) and preview the posts as usual. Since all of the settings are configured for this example, clicking the preview button should redirect you to the front-end URL. To see the draft posts and pages you will need to login your WordPress account on front-end website, using the same credentials.
9197

92-
If you want to learn more about the preview plugin, check out [the documentation](/plugins/hwp-previews/README.md).
98+
After completing this step, clicking the preview button in wp-admin should open the preview in your front-end app. Login with your admin credentials on the frontend to enable draft preview functionality.
9399

94-
> [!CAUTION]
95-
> This setup is intended for demonstration purposes only. For production use, you should consider the security implications and implement appropriate measures based on your project’s specific needs.
100+
If you want to learn more about the preview plugin, check out [the documentation](../../../../docs/plugins/hwp-previews/index.md).
96101

97102
### Command Reference
98103

‎plugins/hwp-previews/examples/hwp-preview-wpgraphql/.wp-env.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"https://github.com/wp-graphql/wp-graphql/releases/latest/download/wp-graphql.zip",
55
"https://github.com/AdvancedCustomFields/acf/releases/latest/download/advanced-custom-fields.zip",
66
"https://github.com/wp-graphql/wpgraphql-acf/releases/latest/download/wpgraphql-acf.zip",
7-
"../../"
7+
"https://github.com/wpengine/hwptoolkit/releases/download/%40wpengine%2Fhwp-previews-wordpress-plugin-0.0.12/hwp-previews.zip"
88
],
99
"config": {
1010
"WP_DEBUG": true,

‎plugins/hwp-previews/examples/hwp-preview-wpgraphql/README.md‎

Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
1+
---
2+
title: "Headless WordPress Previews with Next.js Pages Router and WPGraphQL"
3+
description: "This demonstrates the usage of HWP Previews with Next.js Pages Router and WPGraphQL. It uses WordPress Application Passwords for authentication and implements Draft Mode for secure preview functionality."
4+
---
5+
16
# Example: Headless WordPress Previews with Nextjs Draft Mode
27

38
## Overview
49

5-
This example shows the HWP Previews plugin in action. Example implements the [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode) of Nextjs. It uses WordPress [Application Passwords](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) for the authentication and WPGraphQL for data fetching.
10+
This example shows the HWP Previews plugin in action. Example implements the [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode) of Next.js. It uses WordPress [Application Passwords](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) for the authentication and WPGraphQL for data fetching.
611

712
The example includes a wp-env setup, which will allow you to build and start this example quickly. With this wp-env setup, you don't need to have a separate WordPress instance or demo data to inspect the example.
813

9-
> [!CAUTION]
10-
> The HWP Previews plugin is currently in an beta state. It's still under active development, so you may encounter bugs or incomplete features. Updates will be rolled out regularly. Use with caution and provide feedback if possible.
11-
1214
## What does this example do
1315

14-
1. `/api/preview/` route to enable Nextjs Draft Mode
15-
2. `/api/disable-preview` route to disable Nextjs Draft Mode
16+
1. `/api/preview/` route to enable Next.js Draft Mode
17+
2. `/api/disable-preview` route to disable Next.js Draft Mode
1618
3. Preview posts, pages and custom post types
1719
4. Use WordPress Application Password as an authentication method
18-
5. Configured WordPress instance with demo data and required plugins, using wp-env
20+
5. Configured WordPress instance with demo data and required plugins, using wp-env.
1921

2022
## Screenshots
2123

@@ -55,34 +57,30 @@ The example includes a wp-env setup, which will allow you to build and start thi
5557

5658
**Note** Please make sure you have all prerequisites installed as mentioned above and Docker running (`docker ps`)
5759

58-
### Setup Repository and Packages
60+
### 1. Setup Repository and Packages
5961

6062
- Clone the repo `git clone https://github.com/wpengine/hwptoolkit.git`
6163
- Install packages `cd hwptoolkit && npm install`
6264

63-
### Build and start the application
65+
### 2. Build and start the application
6466

6567
- `cd plugins/hwp-previews/examples/hwp-preview-wpgraphql`
6668
- Then run `npm run example:build` will build and start your application.
67-
- Copy .env.local to .env under example-app `cp example-app/.env.local example-app/.env`
68-
- This does the following:
69-
- Unzips `wp-env/uploads.zip` to `wp-env/uploads` which is mapped to the wp-content/uploads directory for the Docker container.
70-
- Starts up [wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
71-
- Imports the database from [wp-env/db/database.sql](wp-env/db/database.sql)
72-
- Install Next.js dependencies for `example-app`
73-
- Runs the Next.js dev script
7469

75-
Congratulations, WordPress should now be fully set up.
70+
This starts the wp-env instance and frontend application. You can access them now, but one more installation step remains.
71+
72+
> [!IMPORTANT]
73+
> After logging in to the WordPress instance, ensure that all installed plugins are activated for this example to work properly.
7674
7775
| Frontend | Admin |
7876
| ---------------------- | ------------------------------- |
7977
| http://localhost:3000/ | http://localhost:8888/wp-admin/ |
8078

8179
> **Note:** The login details for the admin is username "admin" and password "password"
8280
83-
### Add environment variables to the Nextjs
81+
### 3. Add environment variables to the Nextjs
8482

85-
In this step we will create an Application Password and a secret preview token for the previews. At the end we'll prepare a .env file for the Nextjs application and put it inside `examples/next/hwp-preview-wpgraphql/example-app` folder. Below are the step by step guide to achieve this.
83+
In this step we will create an Application Password and a secret preview token for the previews. At the end we'll prepare a .env file for the Next.js application and put it inside `plugins/hwp-previews/examples/hwp-preview-wpgraphql/example-app` folder. Below are the step by step guide to achieve this.
8684

8785
1. Login to your newly created [wp-env instance](http://localhost:8888/wp-admin/). You can find the credentials above
8886
2. a. Follow [these instructions](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) to create an Application Password. At the end it should look like this:
@@ -95,7 +93,7 @@ In this step we will create an Application Password and a secret preview token f
9593

9694
![index](./screenshots/preview_token.png "Change secret preview token")
9795

98-
4. Create a .env file under `examples/next/hwp-preview-wpgraphql/example-app` and add these values inside:
96+
4. Create a .env file under `plugins/hwp-previews/examples/hwp-preview-wpgraphql/example-app` and add these values inside:
9997

10098
```bash
10199
NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
@@ -110,7 +108,7 @@ WP_PREVIEW_SECRET=YOUR-SECRET-PREVIEW-TOKEN
110108
111109
After completing this step, clicking the preview button in wp-admin should open the preview in your front-end app.
112110

113-
If you want to learn more about the preview plugin, check out [the documentation](/plugins/hwp-previews/README.md).
111+
If you want to learn more about the preview plugin, check out [the documentation](../../../../docs/plugins/hwp-previews/index.md).
114112

115113
### Command Reference
116114

0 commit comments

Comments
 (0)