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
> This plugin is currently in a 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. You can create an issue at [https://github.com/wpengine/hwptoolkit/issues](https://github.com/wpengine/hwptoolkit/issues)
25
19
26
20
-----
27
21
28
-
## Table of Contents
29
-
30
-
-[Overview](#overview)
31
-
-[Features](#features)
32
-
-[Getting Started](#getting-started)
33
-
-[Configuration](#configuration)
34
-
-[Front-End Integration](#front-end-integration)
35
-
-[Using With Faust.js](#using-with-faustjs)
36
-
-[Extending the Functionality](#extending-the-functionality)
37
-
-[Testing](#testing)
38
-
-[Uninstallation](#uninstallation)
39
-
40
22
## Overview
41
23
42
24
HWP Previews is a robust and extensible WordPress plugin that centralizes all preview configurations into a user-friendly settings interface.
@@ -57,116 +39,34 @@ This fundamental architectural shift creates what we call the "preview problem"
57
39
-**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).
58
40
59
41
60
-
>[!IMPORTANT]
42
+
>[!NOTE]
61
43
> 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.
62
44
63
-
## Getting Started
64
-
65
-
This guide will help you set up your first headless preview link for the "Posts" post type.
66
-
67
-
1.**Activate the Plugin:** Ensure "HWP Previews" is installed and activated.
68
-
2.**Navigate to Settings:** Go to **Settings > HWP Previews** in your WordPress admin dashboard.
69
-
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.
70
-
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.
71
-
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)
85
-
│ └── Autoload.php # PSR-4 autoloader
86
-
├── examples/ # Example front-end integrations for WP GraphQL and REST
87
-
├── tests/ # All test suites
88
-
│ ├── wpunit/ # WPBrowser/Codeception unit
89
-
├── hwp-previews.php
90
-
├── activation.php
91
-
├── composer.json
92
-
├── deactivation.php
93
-
├── ACTIONS_AND_FILTERS.md
94
-
├── TESTING.md
95
-
├── README.md
96
-
```
97
-
98
-
## Configuration
99
-
100
-
HWP Previews configuration located at **Settings > HWP Previews** page in your WP Admin. The settings are organized by post type.
101
-
102
-
### Settings
103
-
104
-
For each public post type, you can configure:
105
-
106
-
-**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.
107
-
-**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.
108
-
-**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.
109
-
-**Preview URL:** You will be redirected to this link whenever you click the preview button for the enabled post type.
110
-
111
-
> [!NOTE]
112
-
> Retrieval of settings is cached for performance.
113
-
114
-
### Parameters
45
+
## Requirements
115
46
116
-
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.
47
+
- WordPress 6.0+
48
+
- PHP 7.4+
117
49
118
-
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.
50
+
## Installation
119
51
120
-
-`{ID}` – Post ID
121
-
-`{author_ID}` – Post author’s user ID
122
-
-`{status}` – Post status slug
123
-
-`{slug}` – Post slug
124
-
-`{parent_ID}` – Parent post ID (hierarchical types)
125
-
-`{type}` – Post type slug
126
-
-`{template}` – Template filename
52
+
### Option 1: Plugin Zip
127
53
128
-
### Default Post Statuses Config:
54
+
You can get the latest release here - <https://github.com/wpengine/hwptoolkit/releases/latest/download/hwp-previews.zip>
129
55
130
-
Default post statuses are `publish`, `future`, `draft`, `pending`, `private`, `auto-draft` but these also modifiable via core hook.
56
+
You can also download it from our release page - <https://github.com/wpengine/hwptoolkit/releases>
131
57
132
-
---
58
+
### Option 2: Composer
133
59
134
-
## Front-End Integration
60
+
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>
135
61
136
-
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).
62
+
Once you have the composer repository setup, please run `composer req wpengine/hwp-previews:*` to install the plugin.
137
63
138
-
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.
64
+
## Documentation
139
65
140
-
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.
66
+
For detailed usage instructions, developer references, and examples, visit our comprehensive documentation:
141
67
142
-
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.
143
-
144
-
-[Next.js Draft Mode with Pages Router](https://nextjs.org/docs/pages/guides/draft-mode)
145
-
-[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.
153
-
154
-
### Automatic Integration
155
-
156
-
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:
157
-
158
-
- The "Enable HWP Previews" toggle is activated by default.
159
-
- The Preview URL is automatically updated to match Faust’s standard structure.
160
-
161
-
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.
162
-
163
-
---
164
-
165
-
## Actions & Filters
166
-
167
-
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