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
-[Extending the Functionality](#extending-the-functionality)
37
-
-[Testing](#testing)
38
-
39
28
## Overview
40
29
41
30
HWP Previews is a robust and extensible WordPress plugin that centralizes all preview configurations into a user-friendly settings interface.
@@ -56,116 +45,34 @@ This fundamental architectural shift creates what we call the "preview problem"
56
45
-**Faust Compatibility**: The plugin is compatible with [Faust.js](https://faustjs.org/) and the [FaustWP plugin](https://github.com/wpengine/faustjs/tree/canary/plugins/faustwp).
57
46
58
47
59
-
>[!IMPORTANT]
48
+
>[!NOTE]
60
49
> For Faust users, HWP Previews integrates seamlessly, automatically configuring settings to match Faust's preview system. This allows you to maintain your existing preview workflow without additional setup.
61
50
62
-
## Getting Started
63
-
64
-
This guide will help you set up your first headless preview link for the "Posts" post type.
65
-
66
-
1.**Activate the Plugin:** Ensure "HWP Previews" is installed and activated.
67
-
2.**Navigate to Settings:** Go to **Settings > HWP Previews** in your WordPress admin dashboard.
68
-
3.**Enable for Posts:** On the "Posts" tab, check the "Enable HWP Previews" box. If you have Faust installed, this option will be enabled by default. Find more information about Faust integration below.
69
-
4.**Set the Preview URL:** In the "Preview URL Template" field for Posts, enter the URL for your front-end application's preview endpoint. Use parameters to add dynamic information that you want to access.
70
-
5.**Save and Test:** Save changes, go to any post, make a change, and click the "Preview" button. You should be redirected to the URL you just configured.
│ ├── Plugin.php # Main plugin class (entry point)
84
-
│ └── Autoload.php # PSR-4 autoloader
85
-
├── examples/ # Example front-end integrations for WP GraphQL and REST
86
-
├── tests/ # All test suites
87
-
│ ├── wpunit/ # WPBrowser/Codeception unit
88
-
├── hwp-previews.php
89
-
├── activation.php
90
-
├── composer.json
91
-
├── deactivation.php
92
-
├── ACTIONS_AND_FILTERS.md
93
-
├── TESTING.md
94
-
├── README.md
95
-
```
96
-
97
-
## Configuration
98
-
99
-
HWP Previews configuration located at **Settings > HWP Previews** page in your WP Admin. The settings are organized by post type.
100
-
101
-
### Settings
102
-
103
-
For each public post type, you can configure:
104
-
105
-
-**Enable HWP Previews:** This is the master switch for the post type. If disabled, WordPress will revert to its default preview behavior for these posts.
106
-
-**Allow All Statuses as Parent:** This option is only available for hierarchical post types like Pages. By default, WordPress only allows published posts to be parents. Enable this to build parent-child relationships using draft or pending posts.
107
-
-**Load Previews in Iframe:** When enabled, the preview will be displayed directly within the WordPress editor in a sandboxed `<iframe>`. This provides a more integrated experience but requires your front-end to be configured to allow embedding. If disabled, clicking "Preview" will open a new browser tab.
108
-
-**Preview URL:** You will be redirected to this link whenever you click the preview button for the enabled post type.
109
-
110
-
> [!NOTE]
111
-
> Retrieval of settings is cached for performance.
112
-
113
-
### Parameters
51
+
## Requirements
114
52
115
-
You can use the parameters on the sidebar to add dynamic context info to your preview URL. This information can be used by your front-end application to better handle the preview requests.
53
+
- WordPress 6.0+
54
+
- PHP 7.4+
116
55
117
-
Currently below parameters are available by default, but you can add your own parameters by extending the plugin via hooks. Check Extending the Functionality section for details.
56
+
## Installation
118
57
119
-
-`{ID}` – Post ID
120
-
-`{author_ID}` – Post author’s user ID
121
-
-`{status}` – Post status slug
122
-
-`{slug}` – Post slug
123
-
-`{parent_ID}` – Parent post ID (hierarchical types)
124
-
-`{type}` – Post type slug
125
-
-`{template}` – Template filename
58
+
### Option 1: Plugin Zip
126
59
127
-
### Default Post Statuses Config:
60
+
You can get the latest release here - <https://github.com/wpengine/hwptoolkit/releases/latest/download/hwp-previews.zip>
128
61
129
-
Default post statuses are `publish`, `future`, `draft`, `pending`, `private`, `auto-draft` but these also modifiable via core hook.
62
+
You can also download it from our release page - <https://github.com/wpengine/hwptoolkit/releases>
130
63
131
-
---
64
+
### Option 2: Composer
132
65
133
-
## Front-End Integration
66
+
To install, you need to follow our guide here to install the plugin via composer - <https://github.com/wpengine/hwptoolkit/blob/main/docs/how-to/install-toolkit-plugins/index.md>
134
67
135
-
HWP Previews is framework and API agnostic, meaning you can integrate it with any front-end application and with any data-fetching method (WPGraphQL, REST).
68
+
Once you have the composer repository setup, please run `composer req wpengine/hwp-previews:*` to install the plugin.
136
69
137
-
To get started quickly you can use our [example based on Next.js and WPGraphQL](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews/examples/hwp-preview-wpgraphql). This example uses the Draft Mode feature of Next.js.
70
+
## Documentation
138
71
139
-
For REST users, you can follow our example [here](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews/examples/hwp-preview-rest) with Next.js App Router.
72
+
For detailed usage instructions, developer references, and examples, visit our comprehensive documentation:
140
73
141
-
To implement your own approach from scratch you can refer to the appropriate documentation pages for each framework. HWP Previews relies on custom preview URLs, allowing you to integrate any method. Below you can find the guides to implement framework-specific preview mode.
142
-
143
-
-[Next.js Draft Mode with Pages Router](https://nextjs.org/docs/pages/guides/draft-mode)
144
-
-[Next.js Draft Mode with App router](https://nextjs.org/docs/app/guides/draft-mode)
This plugin is fully compatible with [Faust.js](https://faustjs.org/). It gives you the option to override Faust’s native preview system, providing granular control over preview URLs for use with any front-end framework.
152
-
153
-
### Automatic Integration
154
-
155
-
HWP Previews automatically detects when the Faust.js plugin is active to ensure a seamless integration. Upon detection, it pre-configures the following settings for all public post types:
156
-
157
-
- The "Enable HWP Previews" toggle is activated by default.
158
-
- The Preview URL is automatically updated to match Faust’s standard structure.
159
-
160
-
This out-of-the-box configuration allows your existing preview workflow to continue functioning, without manual setup. You can continue to use [Faust.js authentication](https://faustjs.org/docs/how-to/authentication/) to access the preview pages.
161
-
162
-
---
163
-
164
-
## Actions & Filters
165
-
166
-
See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehensive list of available hooks and how to use them.
Headless Previews solution for WordPress: fully configurable preview URLs via the settings page which is framework agnostic.
12
+
11
13
== Description ==
12
14
13
-
A headless WordPress plugin for Previews.
15
+
**HWP Previews** is a robust and extensible WordPress plugin that centralizes all preview configurations into a user-friendly settings interface. It enables seamless preview functionality for headless WordPress applications, allowing content creators to preview their changes in the frontend application before publishing.
16
+
17
+
In traditional WordPress, previewing content is straightforward: clicking the "Preview" button shows you a draft version of your post on the same WordPress site. However, in headless WordPress architectures, where the front-end is decoupled from WordPress, this simple mechanism breaks down. HWP Previews bridges this gap, providing a centralized, framework-agnostic solution to preview management.
18
+
19
+
= Key Features =
20
+
21
+
**Framework Agnostic**
22
+
* Works with any front-end framework (Next.js, Nuxt, React, Vue, etc.)
23
+
* Supports any data-fetching method (WPGraphQL, REST API, or custom endpoints)
24
+
* No vendor lock-in
25
+
26
+
**Per Post Type Configuration**
27
+
* Enable or disable previews for each public post type independently
28
+
* Define custom URL templates with dynamic parameters
29
+
* Choose between iframe or new tab preview modes
30
+
* Allow draft posts as parents for hierarchical types
31
+
32
+
**Dynamic URL Templates**
33
+
* Use placeholder tokens to build context-rich preview URLs
34
+
* Available tokens: `{ID}`, `{author_ID}`, `{status}`, `{slug}`, `{parent_ID}`, `{type}`, `{template}`
35
+
* Build flexible preview URLs that pass exactly the data your front-end needs
36
+
37
+
**Extensible Architecture**
38
+
* Extend through WordPress hooks and filters
39
+
* Add custom parameters and modify settings
40
+
* Integrate with other plugins seamlessly
41
+
42
+
**Faust.js Integration**
43
+
* Automatic integration with Faust.js that pre-configures preview URLs
44
+
* Removes conflicts while maintaining existing workflows
45
+
* Works alongside FaustWP plugin
46
+
47
+
= Use Cases =
48
+
49
+
* **Headless CMS**: Preview content in your decoupled front-end before publishing
50
+
* **Multi-site Management**: Configure different preview URLs for different post types
51
+
* **Custom Post Types**: Set up previews for any custom post type
52
+
* **Development Workflow**: Test content changes in staging environments
53
+
* **Client Presentations**: Show draft content to clients before going live
54
+
55
+
= Requirements =
56
+
57
+
* WordPress 6.0 or higher
58
+
* PHP 7.4 or higher
59
+
60
+
= Documentation =
61
+
62
+
For detailed documentation, guides, and examples, visit the [GitHub repository](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews).
63
+
64
+
== Installation ==
65
+
66
+
1. Upload the plugin files to `/wp-content/plugins/hwp-previews/`, or install the plugin through the WordPress plugins screen directly
67
+
2. Activate the plugin through the 'Plugins' screen in WordPress
68
+
3. Navigate to Settings -> HWP Previews in the WordPress admin to configure settings
69
+
4. Enable previews for your desired post types and set preview URL templates
14
70
15
-
== Upgrade Notice ==
16
71
== Frequently Asked Questions ==
17
-
== Screenshots ==
72
+
73
+
= Is this plugin production-ready? =
74
+
75
+
Yes. We recommend thorough testing on a local or staging before deploying to production.
76
+
77
+
= Does this work with my front-end framework? =
78
+
79
+
Yes! HWP Previews is framework-agnostic and works with Next.js, Nuxt, React, Vue, or any other front-end framework. You just need to set up a preview endpoint in your application.
80
+
81
+
= Can I use this with WPGraphQL? =
82
+
83
+
Absolutely! The plugin works with both WPGraphQL and REST API, or any custom data-fetching method you prefer.
84
+
85
+
= Does this work with Faust.js? =
86
+
87
+
Yes, HWP Previews automatically integrates with Faust.js and pre-configures settings to match Faust's preview system.
88
+
89
+
= How do I set up the preview URL? =
90
+
91
+
Go to Settings -> HWP Previews, select the post type tab, enable previews, and enter your front-end preview endpoint URL using dynamic parameters like `{ID}` and `{slug}`.
92
+
93
+
= Can I customize the preview behavior? =
94
+
95
+
Yes, the plugin provides extensive hooks and filters to customize preview behavior, add custom parameters, and integrate with other systems.
96
+
97
+
= Where can I find documentation? =
98
+
99
+
For detailed usage instructions, developer references, and examples, please visit the [Documentation](https://github.com/wpengine/hwptoolkit/blob/main/docs/plugins/hwp-previews/index.md) on GitHub.
100
+
101
+
== Support ==
102
+
103
+
For support, feature requests, or bug reports, please visit our [GitHub issues page](https://github.com/wpengine/hwptoolkit/issues).
0 commit comments