Adding a Custom Welcome Guide to the WordPress Block Editor

This article details creating a WordPress plugin that provides in-app documentation, avoiding the need for external links to separate documentation. The solution integrates a helpful guide directly into the WordPress block editor, accessible while users actively work with the plugin.

The plugin utilizes custom post types (CPTs) and a modal-style guide component. The challenge lies in seamlessly integrating this guide into the editor without disrupting the user workflow.

The Goal: The plugin, a GraphQL server for WordPress, features CPTs edited via custom blocks ("GraphiQL client" and "Persisted query options"). Since GraphQL query creation can be complex, an integrated guide is crucial. This guide, accessed via a panel in the Document settings ("Welcome Guide"), provides a tutorial video and detailed instructions across multiple pages.

Implementation Steps:

1. Creating the Script: The process starts by scaffolding a new script to register a custom sidebar panel in the editor's Document settings. The author initially encounters challenges using the PluginDocumentSettingPanel component due to the need for a JavaScript build step (ESNext/JSX). The solution involves leveraging the @wordpress/create-block package to scaffold a block, then modifying the generated code to register a regular script instead. This allows for ESNext compilation via webpack. A key detail is adding a dependency to the wp-edit-post script to ensure proper loading of the wp.editPost variable.

2. Panel Restriction: To prevent the panel from appearing on unrelated CPTs, the author implements a PHP-based solution. This method checks the current post type using get_editing_post_type() and only registers the script if it matches the target CPT. This is a more efficient approach than using JavaScript to conditionally render the panel.

3. Building the Guide: The guide itself is built using the WordPress <guide></guide> component and its associated <guidepage></guidepage> for pagination. The author details the process of discovering this component through code searching and exploring the Gutenberg Storybook. The guide includes a video tutorial (hosted externally) and subsequent pages with detailed instructions.

4. Content Integration: The guide's content is structured using <guidepage></guidepage> components, each containing HTML, potentially including other custom components. The author notes minor issues such as video embedding limitations within the <guide></guide> component and the need for CSS improvements.

Bonus: Independent Documentation Access:

The author demonstrates how to create reusable components for documentation. A CacheControlDescription component, for example, can be used within both the guide and a separate modal, improving user experience. Conditional rendering of the documentation access button based on block selection enhances usability.

Conclusion:

This detailed walkthrough effectively showcases the development of an integrated, in-app documentation system within the WordPress block editor. The author's experience highlights the importance of understanding both React and the WordPress block editor's architecture for successful plugin development. The solution provides a practical and reusable model for other plugin developers seeking to improve user onboarding and support.

The above is the detailed content of Adding a Custom Welcome Guide to the WordPress Block Editor. For more information, please follow other related articles on the PHP Chinese website!