Prepare for new block variations 1/x: hookable-patterns, slot-fills & docs

docs/developer/blocks/README.md

@@ -0,0 +1,6 @@
+# Blocks in GatherPress
+
+1. All blocks in general (LINK to /docs/user/...)
+2. [Hookable patterns for events & venues](./hookable-patterns/)
+    - Add to or Remove blocks from the post type block templates
+3. [Slots & fills in GatherPress Admin UI](./slot-fills/)

docs/developer/blocks/hookable-patterns/README.md

@@ -0,0 +1,42 @@
+# Hookable patterns for events & venues
+
+GatherPress registers multiple invisible block-patterns, that are used as template properties of the main post types.
+
+Patterns allow to be filtered by the (upgraded since WordPress 6.5) Block Hooks API. Making use of this API brings some advantages, which are at least:
+
+- GatherPress' blocks can be easily moved, modified or removed by extenders via standardized core code
+- GatherPress provides central entry points for plugin developers to hook in own blocks, to extend GatherPress
+- GatherPress' blocks will provide their hooking code themself, which keeps concerns separate and code clean
+
+For example when you create a new event post, it gets pre-poulated with a set of blocks, curated within a block-pattern named `gatherpress/event-template`.
+
+GatherPress combines four of such block-patterns to curate the creation of:
+
+- [New Events](#new-event)
+- [New Venues](#new-venue)
+- [New Event Queries within any post](#new-event-queries-within-any-post)
+- [Venue Details within any post](#venue-details-within-any-post)
+
+## New Event
+
+GatherPress adds the following blocks by default into a new created event:
+
+- A block-pattern named `gatherpress/event-template`.
+
+
+## New Venue
+
+A new created venue will have the following blocks prepared by default:
+
+- A block-pattern named `gatherpress/venue-template`
+    - A block-pattern named `gatherpress/venue-details`, which keeps detailed information about a selected venue in the shape of blocks
+
+## New Event Queries within any post
+
+## Venue Details within any post
+
+### Resources
+
+- [@wordpress/hooks - Block Editor Handbook | Developer.WordPress.org](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-hooks/)
+- [#devnote - Introducing Block Hooks for dynamic blocks - Make WordPress Core](https://make.wordpress.org/core/2023/10/15/introducing-block-hooks-for-dynamic-blocks/)
+- [Exploring the Block Hooks API in WordPress 6.5 - WordPress Developer Blog](https://developer.wordpress.org/news/2024/03/25/exploring-the-block-hooks-api-in-wordpress-6-5/)

docs/developer/blocks/slot-fills/README.md

@@ -0,0 +1,42 @@
+# Slots & fills in GatherPress Admin UI
+
+Similar to the central entry points for blocks – GatherPress' [hookable-patterns](./../hookable-patterns/), the plugin provides central administrative entry-points within the post- and site-editor for all block settings.
+
+GatherPress keeps relevant post data about the currently edited venue or event post within slot inside the `InseptorControls` panel, specific for each post type. These open slots are used by GatherPress itself and can be filled externally.
+
+Every slot belongs to one of each post type. Additionally the venue-slot will be added to the event-slot automatically.
+
+Every GatherPress block with own administrative sidebar-elements registers a fill for either the venue- or the events-slot. Plugin developers should provide their additions to GatherPress within the slots as well, which will help keeping the overall admin interface clean & consistent.
+
+## Available Slots
+
+- `EventPluginDocumentSettings` A slot that has all settings related to an event.
+- `VenuePluginDocumentSettings` A slot that has all settings related to a venue.
+
+All slots will be rendered into the `PluginDocumentSettingPanel` imported from the `@wordpress/editor` package. This panel is shown in the document sidebar for the event and venue post types [in both the post and site editor][devnote]. 
+
+## Fills by GatherPress
+
+- `VenuePluginFill` loads the `VenuePluginDocumentSettings` slot into the `EventPluginDocumentSettings` slot, so that venue changes can be made from within an event context.
+
+
+## Add or remove UI elements
+
+```js
+export default function GatherPressAwesomeFill() {
+	return (
+		<>
+			<Fill name="EventPluginDocumentSettings">
+				<p>A note that will be seen in the document sidebar under "Event settings".</p>
+			</Fill>
+		</>
+	);
+}
+```
+
+
+### Resources
+
+- [Unified Extensibility APIs in 6.6][devnote]
+
+[devnote]: https://make.wordpress.org/core/2024/06/18/editor-unified-extensibility-apis-in-6-6/ "#devnote - Editor: Unified Extensibility APIs in 6.6 – Make WordPress Core"

includes/core/classes/class-block.php

@@ -49,6 +49,7 @@ protected function __construct() {
 	 * @return void
 	 */
 	protected function setup_hooks(): void {
+		add_action( 'init', array( $this, 'register_block_patterns' ), 10 );
 		// Priority 11 needed for block.json translations of title and description.
 		add_action( 'init', array( $this, 'register_blocks' ), 11 );
 	}
@@ -72,4 +73,73 @@ public function register_blocks(): void {
 			);
 		}
 	}
+
+
+	/**
+	 * Register block patterns.
+	 *
+	 * This method registers multiple different block-patterns for GatherPress.
+	 *
+	 * @since 1.0.0
+	 * @see   https://developer.wordpress.org/reference/functions/register_block_pattern/
+	 *
+	 * @return void
+	 */
+	public function register_block_patterns(): void {
+
+		/**
+		 * Made to be used with the 'template' parameter
+		 * when registering the 'gatherpress_event' post type
+		 * and will not be visible to the editor at any point.
+		 */
+		\register_block_pattern(
+			'gatherpress/event-template',
+			array(
+				'title'    => 'Invisible Event Template Block Pattern',
+				// Even this paragraph seems useless, it's not.
+				// It is the entry point for all our hooked blocks
+				// and as such absolutely important!
+				'content'  => '<!-- gatherpress:event-date /--><!-- wp:pattern {"slug":"gatherpress/venue-details"} /-->', // Other blocks are hooked-in here.
+				'inserter' => false,
+				'source'   => 'plugin',
+			)
+		);
+
+		/**
+		 * Made to be used with the 'template' parameter
+		 * when registering the 'gatherpress_venue' post type
+		 * and will not be visible to the editor at any point.
+		 */
+		\register_block_pattern(
+			'gatherpress/venue-template',
+			array(
+				'title'    => 'Invisible Venue Template Block Pattern',
+				// Even this paragraph seems useless, it's not.
+				// It is the entry point for all our hooked blocks
+				// and as such absolutely important!
+				'content'  => '<!-- wp:post-featured-image /--><!-- wp:paragraph {"placeholder":"Add some infos about the venue and maybe a nice picture."} --><p></p><!-- /wp:paragraph -->', // Other blocks are hooked-in here.
+				'inserter' => false,
+				'source'   => 'plugin',
+			)
+		);
+
+		/**
+		 * Mainly for use with the 'venue-details' block,
+		 * which is a group block under the hood
+		 * and uses this pattern as innerBlocks template,
+		 * it will not be visible to the editor at any point.
+		 */
+		\register_block_pattern(
+			'gatherpress/venue-details',
+			array(
+				'title'    => 'Invisible Venue Details Block Pattern',
+				// Even this post-title seems useless, it's not.
+				// It is the entry point for all our hooked blocks
+				// and as such absolutely important!
+				'content'  => '<!-- wp:post-title /-->', // Other blocks are hooked-in here.
+				'inserter' => false,
+				'source'   => 'plugin',
+			)
+		);
+	}
 }

includes/core/classes/class-event-setup.php

@@ -128,6 +128,7 @@ public function register_post_type(): void {
 						),
 					),
 					array( 'gatherpress/rsvp-response' ),
+					// The future! // array( 'core/pattern', array( 'slug' => 'gatherpress/event-template' ) ), // phpcs:ignore Squiz.PHP.CommentedOutCode.Found !
 				),
 				'menu_position' => 4,
 				'supports'      => array(

includes/core/classes/class-venue.php

@@ -132,6 +132,7 @@ public function register_post_type(): void {
 				'menu_icon'    => 'dashicons-location',
 				'template'     => array(
 					array( 'gatherpress/venue' ),
+					// The future! // array( 'core/pattern', array( 'slug' => 'gatherpress/venue-template' ) ), // phpcs:ignore Squiz.PHP.CommentedOutCode.Found !
 				),
 				'has_archive'  => true,
 				'rewrite'      => array(
@@ -230,6 +231,8 @@ public function register_taxonomy(): void {
 				'show_in_rest'       => true,
 			)
 		);
+		// It is necessary to make this taxonomy visible on event posts, within REST responses.
+		register_taxonomy_for_object_type( self::TAXONOMY, Event::POST_TYPE );
 	}
 
 	/**

src/panels/event-settings/index.js

@@ -8,7 +8,7 @@ import {
 	__experimentalVStack as VStack,
 } from '@wordpress/components';
 import { registerPlugin } from '@wordpress/plugins';
-import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
+import { PluginDocumentSettingPanel } from '@wordpress/editor';
 
 /**
  * Internal dependencies.
@@ -22,6 +22,7 @@ import MaxAttendanceLimitPanel from './max-attendance-limit';
 import NotifyMembersPanel from './notify-members';
 import OnlineEventLinkPanel from './online-link';
 import VenueSelectorPanel from './venue-selector';
+import { EventPluginDocumentSettings } from './slot';
 
 /**
  * A settings panel for event-specific settings in the block editor.
@@ -44,6 +45,9 @@ const EventSettings = () => {
 				initialOpen={true}
 				className="gatherpress-event-settings"
 			>
+				{/* Extendable entry point for "Event Settings" panel. */}
+				<EventPluginDocumentSettings.Slot />
+
 				<VStack spacing={4}>
 					<DateTimeRangePanel />
 					<VenueSelectorPanel />

src/panels/event-settings/slot.js

@@ -0,0 +1,17 @@
+/**
+ * Defines an extensibility slot for the "Event Settings" panel.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { createSlotFill, PanelRow } from '@wordpress/components';
+
+export const { Fill, Slot } = createSlotFill('EventPluginDocumentSettings');
+export const EventPluginDocumentSettings = ({ children, className }) => (
+	<Fill>
+		<PanelRow className={className}>{children}</PanelRow>
+	</Fill>
+);
+
+EventPluginDocumentSettings.Slot = Slot;

src/panels/venue-settings/fill.js

@@ -0,0 +1,24 @@
+/**
+ * Fill the "Venue Settings" slot into the "Event Settings" slot by default,
+ * so that venue changes can be made from within an event context.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { Fill } from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import { VenuePluginDocumentSettings } from './slot';
+
+export default function VenuePluginFill() {
+	return (
+		<>
+			<Fill name="EventPluginDocumentSettings">
+				<VenuePluginDocumentSettings.Slot />
+			</Fill>
+		</>
+	);
+}

src/panels/venue-settings/index.js

@@ -8,13 +8,15 @@ import {
 	__experimentalVStack as VStack,
 } from '@wordpress/components';
 import { registerPlugin } from '@wordpress/plugins';
-import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
+import { PluginDocumentSettingPanel } from '@wordpress/editor';
 
 /**
  * Internal dependencies.
  */
 import { isVenuePostType } from '../../helpers/venue';
 import VenueInformationPanel from './venue-information';
+import { VenuePluginDocumentSettings } from './slot';
+import VenuePluginFill from './fill';
 
 /**
  * VenueSettings Component
@@ -35,6 +37,9 @@ const VenueSettings = () => {
 				initialOpen={true}
 				className="gatherpress-venue-settings"
 			>
+				{/* Extendable entry point for "Venue Settings" panel. */}
+				<VenuePluginDocumentSettings.Slot />
+
 				<VStack spacing={6}>
 					<VenueInformationPanel />
 				</VStack>
@@ -56,6 +61,10 @@ registerPlugin('gatherpress-venue-settings', {
 	render: VenueSettings,
 });
 
+registerPlugin('gatherpress-venue-settings-at-events', {
+	render: VenuePluginFill,
+});
+
 /**
  * Toggle Venue Settings Panel
  *

src/panels/venue-settings/slot.js

@@ -0,0 +1,17 @@
+/**
+ * Defines as extensibility slot for the "Venue Settings" panel.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { createSlotFill, PanelRow } from '@wordpress/components';
+
+export const { Fill, Slot } = createSlotFill('VenuePluginDocumentSettings');
+export const VenuePluginDocumentSettings = ({ children, className }) => (
+	<Fill>
+		<PanelRow className={className}>{children}</PanelRow>
+	</Fill>
+);
+
+VenuePluginDocumentSettings.Slot = Slot;