Merge branch 'develop' into 736-checkbox-lat-lng

.github/scripts/create-preview-links.js → .github/scripts/playground-preview/index.js

@@ -51,9 +51,6 @@ function createBlueprint(context, number, zipArtifactUrl, phpVersion) {
 			networking: true
 		},
 		steps: [
-			{
-				step: 'enableMultisite',
-			},
 			{
 				step: 'login',
 				username: 'admin',
@@ -107,12 +104,15 @@ function createBlueprint(context, number, zipArtifactUrl, phpVersion) {
 			*/
 			{
 				step: 'unzip',
-				zipPath: '/wordpress/pr/pr.zip',
+				zipFile: {
+					resource: 'vfs',
+					path: '/wordpress/pr/pr.zip',
+				},
 				extractToPath: '/wordpress/pr',
 			},
 			{
 				step: 'installPlugin',
-				pluginZipFile: {
+				pluginData: {
 					resource: 'vfs',
 					path: '/wordpress/pr/gatherpress.zip',
 				},
@@ -124,6 +124,16 @@ function createBlueprint(context, number, zipArtifactUrl, phpVersion) {
 					url: 'https://raw.githubusercontent.com/GatherPress/gatherpress-demo-data/main/GatherPress-demo-data-2024.xml'
 				}
 			},
+			/**
+			 * Run 'enableMultisite' after the plugin activation!
+			 *
+			 * There have been some weird errors with this step, when ran after the login.
+			 * Having it here at the end -kinda- fixes the problem.
+			 * @see https://github.com/GatherPress/gatherpress/issues/950
+			 */
+			{
+				step: 'enableMultisite',
+			},
 		],
 	};
 

.github/workflows/playground-preview.yml

@@ -125,5 +125,5 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            const createPreviewLinks = require('.github/scripts/create-preview-links');
+            const createPreviewLinks = require('.github/scripts/playground-preview');
             createPreviewLinks(github, context);

build/panels.asset.php

@@ -1 +1 @@
-<?php return array('dependencies' => array('moment', 'react-jsx-runtime', 'wp-components', 'wp-compose', 'wp-data', 'wp-date', 'wp-dom-ready', 'wp-editor', 'wp-element', 'wp-i18n', 'wp-plugins'), 'version' => 'd92b459db2bb69605022');
+<?php return array('dependencies' => array('moment', 'react-jsx-runtime', 'wp-components', 'wp-compose', 'wp-data', 'wp-date', 'wp-dom-ready', 'wp-editor', 'wp-element', 'wp-i18n', 'wp-plugins'), 'version' => '5cfc4e82d4b3e03141f6');

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,140 @@
+# Hookable patterns for events & venues
+
+GatherPress registers multiple invisible block-patterns, that are used as template properties for 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`.
+
+## Overview of hookable patterns
+
+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`, which contains the following blocks by default:
+
+    - `gatherpress/event-date`
+    - `gatherpress/add-to-calendar`
+    - `gatherpress/venue`
+    - `gatherpress/rsvp`
+    - `core/paragraph`
+    - `gatherpress/rsvp-response`
+
+
+### New Venue
+
+A new created venue will have the following blocks prepared by default:
+
+- A block-pattern named `gatherpress/venue-template`, which contains the following block by default:
+
+    - `gatherpress/venue`
+
+
+### New Event Queries within any post
+
+...
+
+### Venue Details within any post
+
+...
+
+## Modify the blocks in the patterns
+
+- [Change order of the default blocks](#change-order-of-the-default-blocks)
+- [Add blocks to the default patterns](#add-blocks-to-the-default-patterns)
+- [Remove default blocks](#remove-default-blocks)
+
+### Change order of the default blocks
+
+**Example**: To move the *RSVP-Response* block directly behind the *RSVP* block for every new created Event,
+you could call:
+
+```php
+/**
+ * Move the "RSVP-Response" block directly behind the "RSVP" block.
+ *
+ * @param string[]  $hooked_block_types The list of hooked block types.
+ * @return string[]                     The modified list of hooked block types.
+ */
+add_filter( 'hooked_block_types', function( array $hooked_block_types ) : array {
+    $index  = array_search('gatherpress/rsvp-response', $hooked_block_types);
+    if ( $index !== false ) {
+        // Remove the "RSVP-Response" block from its current position.
+        $block = array_splice( $hooked_block_types, $index, 1 );
+        // Find the index of the "RSVP" block.
+        $rsvp_index = array_search( 'gatherpress/rsvp', $hooked_block_types );
+        // Insert the "RSVP-Response" block directly behind the "RSVP" block.
+        array_splice( $hooked_block_types, $rsvp_index + 1, 0, $block );
+    }
+    return $hooked_block_types;
+});
+```
+
+### Add blocks to the default patterns
+
+**Example**: To add the *Featured Image* block before the *Event Date* block for every new created Event,
+you could call:
+
+```php
+/**
+ * Add the 'Featured Image' block before the 'Event Date' block.
+ *
+ * @see https://developer.wordpress.org/reference/hooks/hooked_block_types/
+ *
+ * @param string[]                 $hooked_block_types The list of hooked  block types.
+ * @param string                   $relative_position  The relative position  of the hooked blocks. Can be one of 'before', 'after', 'first_child', or  'last_child'.
+ * @param string|null              $anchor_block_type  The anchor block type.
+ * @param \WP_Block_Template|array $context            The block template,  template part, or pattern that the anchor block belongs to.
+ * @return string[] The list of hooked block types.
+ */
+add_filter( 'hooked_block_types', function ( array $hooked_block_types, string $relative_position, ?string $anchor_block_type, $context ): array {
+    // Check that the place to hook into is a pattern and
+    // hook block into the "gatherpress/event-template" pattern.
+    if ( 
+        is_array( $context ) &&
+        isset( $context['name'] ) &&
+        'gatherpress/event-template' === $context['name'] &&
+        'gatherpress/event-date' === $anchor_block_type &&
+        'before' === $relative_position
+    ) {
+        $hooked_block_types[] = 'core/post-featured-image';
+    }
+    return $hooked_block_types;
+}, 10, 4 );
+```
+
+### Remove default blocks
+
+**Example**: To remove the *RSVP-Response* block, you could call:
+
+```php
+/**
+ * Remove every use of the RSVP-Response block (everywhere).
+ *
+ * @see https://developer.wordpress.org/reference/hooks/hooked_block_types/
+ *
+ * @param string[]  $hooked_block_types The list of hooked block types.
+ * @return string[]                     The modified list of hooked block types.
+ */
+add_filter( 'hooked_block_types', function( array $hooked_block_types ) : array {
+    return array_diff( $hooked_block_types, array( 'gatherpress/rsvp-response' ) );
+});
+```
+
+## 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"