Skip to content

Commit 4e93ed6

Browse files
ahuseynahuseyn
committed
docs: add Faust usage info and update readme
1 parent 788f0a9 commit 4e93ed6

File tree

2 files changed

+73
-36
lines changed

2 files changed

+73
-36
lines changed

‎plugins/hwp-previews/ACTIONS_AND_FILTERS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Modify which post types appear in the settings UI:
3232
```php
3333
// Removes attachment post type from the settings page configuration.
3434

35-
add_filter( 'hwp_previews_filter_post_type_setting', 'hwp_previews_filter_post_type_setting_callback' );
35+
add_filter( 'hwp_previews_filter_available_post_types', 'hwp_previews_filter_post_type_setting_callback' );
3636
function hwp_previews_filter_post_type_setting_callback( $post_types ) {
3737
if ( isset( $post_types['attachment'] ) ) {
3838
unset( $post_types['attachment'] );

‎plugins/hwp-previews/README.md‎

Lines changed: 72 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,14 @@
1111

1212
## Table of Contents
1313

14-
* [Overview](#overview)
15-
* [Features](#features)
16-
* [Configuration](#configuration)
17-
* [Hooks & Extensibility](#hooks--extensibility)
18-
* [Integration](#integration)
14+
- [Overview](#overview)
15+
- [Features](#features)
16+
- [Getting Started](#getting-started)
17+
- [Configuration](#configuration)
18+
- [Front-End Integration](#front-end-integration)
19+
- [Using With Faust.js](#using-with-faustjs)
20+
- [Extending the Functionality](#extending-the-functionality)
21+
- [Testing](#testing)
1922

2023
## Overview
2124

@@ -27,51 +30,62 @@ With HWP Previews, you can define dynamic URL templates, enforce unique slugs fo
2730

2831
## Features
2932

30-
* **Enable/Disable Previews**: Turn preview functionality on or off for each public post type (including custom types).
31-
* **Custom URL Templates**: Define preview URLs using placeholder tokens for dynamic content. Default tokens include:
33+
- **Enable/Disable Previews**: Turn preview functionality on or off for each public post type (including custom types).
34+
- **Custom URL Templates**: Define preview URLs using placeholder tokens for dynamic content.
35+
- **Parent Status**: Allow posts of **all** statuses to be used as parent within hierarchical post types.
36+
- **Highly Customizable**: Extend core behavior with a comprehensive set of actions and filters.
3237

33-
* `{ID}` – Post ID
34-
* `{author_ID}` – Post author’s user ID
35-
* `{status}` – Post status slug
36-
* `{slug}` – Post slug
37-
* `{parent_ID}` – Parent post ID (hierarchical types)
38-
* `{type}` – Post type slug
39-
* `{template}` – Template filename
38+
---
39+
40+
## Getting Started
41+
42+
This guide will help you set up your first headless preview link for the "Posts" post type.
4043

41-
* **Unique Post Slugs**: Force unique slugs for all post statuses in the post status config.
42-
* **Parent Status**: Allow posts of **all** statuses to be used as parent within hierarchical post types.
43-
* **Default Post Statuses Config**: `publish`, `future`, `draft`, `pending`, `private`, `auto-draft` (modifiable via core hook).
44-
* **Parameter Registry**: Register, unregister, or customize URL tokens through the `hwp_previews_core` action.
45-
* **Iframe Template for Previews**: Allows enable previews in the iframe on the WP Admin side. User can override the iframe preview template via `hwp_previews_template_path` filter.
44+
1. **Activate the Plugin:** Ensure "HWP Previews" is installed and activated.
45+
2. **Navigate to Settings:** Go to **Settings > HWP Previews** in your WordPress admin dashboard.
46+
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.
47+
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.
48+
5. **Save and Test:** Save changes and go to any post, make a change, and click the "Preview" button. You should be redirected to the URL you just configured.
4649

4750
---
4851

52+
## Configuration
4953

50-
## Actions & Filters
54+
HWP Previews configuration located at **Settings > HWP Previews** page in your WP Admin. The settings are organized by post type.
5155

52-
See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehensive list of available hooks and how to use them.
56+
### Settings
5357

54-
## Configuration
58+
For each public post type, you can configure:
5559

56-
### Default Post Types Config:
57-
All public post types are enabled by default on the settings page. It is filterable via `hwp_previews_filter_post_type_setting` filter hook.
60+
- **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.
61+
- **Allow All Statuses as Parent:** This option is only available for Pages type. By default, WordPress only allows published posts to be parents. Enable this to build parent-child relationships using draft or pending posts.
62+
- **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.
63+
- **Preview URL:** You will be redirected to this link, whenever you click the preview button for the enabled post type.
5864

59-
### Default Post Statuses Config:
60-
Post statuses are `publish`, `future`, `draft`, `pending`, `private`, `auto-draft` (modifiable via core hook).
65+
> [!NOTE]
66+
> Retrieving of settings is cached for performance.
6167
62-
### Configure HWP Previews Plugin:
63-
Navigate in WP Admin to **Settings › HWP Previews**. For each public post type, configure:
68+
### Parameters
6469

65-
* **Enable HWP Previews** – Master switch
66-
* **Allow All Statuses as Parent** – (Hierarchical types only)
67-
* **Preview URL Template** – Custom URL with tokens like `{ID}`, `{slug}`
68-
* **Load Previews in Iframe** – Toggle iframe-based preview rendering
70+
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.
6971

70-
_Note: Retrieving of settings is cached for performance._
72+
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.
73+
74+
- `{ID}` – Post ID
75+
- `{author_ID}` – Post author’s user ID
76+
- `{status}` – Post status slug
77+
- `{slug}` – Post slug
78+
- `{parent_ID}` – Parent post ID (hierarchical types)
79+
- `{type}` – Post type slug
80+
- `{template}` – Template filename
81+
82+
### Default Post Statuses Config:
83+
84+
Default post statuses are `publish`, `future`, `draft`, `pending`, `private`, `auto-draft` but these also modifiable via core hook.
7185

7286
---
7387

74-
## Integration
88+
## Front-End Integration
7589

7690
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).
7791

@@ -83,10 +97,33 @@ To implement your own approach from scratch you can refer to the appropriate doc
8397
- [Next.js Draft Mode with App router](https://nextjs.org/docs/app/guides/draft-mode)
8498
- [Nuxt usePreviewMode](https://nuxt.com/docs/api/composables/use-preview-mode)
8599

100+
---
101+
102+
## Using With Faust.js
103+
104+
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.
105+
106+
### Automatic Integration
107+
108+
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:
109+
110+
- The "Enable HWP Previews" toggle is activated by default.
111+
- The Preview URL is automatically updated to match Faust’s standard structure.
112+
113+
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.
114+
115+
---
116+
117+
## Extending the Functionality
118+
119+
The plugin's behavior can be extended using its PHP hooks. Developers can control which post types are configurable in the settings via the `hwp_previews_filter_available_post_types` filter. The `hwp_previews_core` action allows for registering new URL parameters or unregistering default ones. Additionally, the `hwp_previews_template_path` filter can be used to replace the default preview iframe with a custom PHP template.
120+
121+
### Actions & Filters
122+
123+
See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehensive list of available hooks and how to use them.
86124

87125
---
88126

89127
## Testing
90128

91129
See [Testing.md](TESTING.md) for details on how to test the plugin.
92-

0 commit comments

Comments
 (0)