Add initial API to register patterns from themes and plugins

docs/designers-developers/developers/block-api/block-patterns.md

@@ -0,0 +1,37 @@
+# Patterns (Experimental)
+
+Patterns are predefined block layouts, ready to insert and tweak. 
+
+**Note** Patterns are still under heavy development and the APIs are subject to change.
+
+#### register_pattern
+
+The editor comes with a list of built-in patterns. Theme and plugin authors can register addition custom patterns using the `register_pattern` function.
+
+The `register_pattern` function receives the name of the pattern as the first argument and an array describing properties of the pattern as the second argument.
+
+The properties of the style array must include `name` and `label`: 
+ - `title`: A human-readable title for the pattern.
+ - `content`: Raw HTML content for the pattern.
+
+```php
+register_pattern(
+    'my-plugin/my-awesome-pattern',
+    array(
+		'title'   => __( 'Two buttons', 'my-plugin' ),
+        'content' => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">Button One</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">Button Two</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
+    )
+);
+```
+
+#### unregister_pattern
+
+`unregister_pattern` allows unregistering a pattern previously registered on the server using `register_pattern`.
+
+The function's argument is the registered name of the pattern.
+
+The following code sample unregisters the style named 'my-plugin/my-awesome-pattern':
+
+```php
+unregister_pattern( 'my-plugin/my-awesome-pattern' );
+```

docs/manifest.json

@@ -83,6 +83,12 @@
 		"markdown_source": "../docs/designers-developers/developers/block-api/block-templates.md",
 		"parent": "block-api"
 	},
+	{
+		"title": "Patterns",
+		"slug": "block-patterns",
+		"markdown_source": "../docs/designers-developers/developers/block-api/block-patterns.md",
+		"parent": "block-api"
+	},
 	{
 		"title": "Annotations",
 		"slug": "block-annotations",

docs/toc.json

@@ -15,6 +15,7 @@
 			{ "docs/designers-developers/developers/block-api/block-attributes.md": [] },
 			{"docs/designers-developers/developers/block-api/block-deprecation.md": [] },
 			{ "docs/designers-developers/developers/block-api/block-templates.md": [] },
+			{ "docs/designers-developers/developers/block-api/block-patterns.md": [] },
 			{ "docs/designers-developers/developers/block-api/block-annotations.md": [] }
 		] },
 		{ "docs/designers-developers/developers/filters/README.md": [

lib/class-wp-patterns-registry.php

@@ -0,0 +1,137 @@
+<?php
+/**
+ * Blocks API: WP_Patterns_Registry class
+ *
+ * @package Gutenberg
+ */
+
+/**
+ * Class used for interacting with patterns.
+ */
+final class WP_Patterns_Registry {
+	/**
+	 * Registered patterns array.
+	 *
+	 * @var array
+	 */
+	private $registered_patterns = array();
+
+	/**
+	 * Container for the main instance of the class.
+	 *
+	 * @var WP_Patterns_Registry|null
+	 */
+	private static $instance = null;
+
+	/**
+	 * Registers a pattern.
+	 *
+	 * @param string $pattern_name       Pattern name including namespace.
+	 * @param array  $pattern_properties Array containing the properties of the pattern: label, content.
+	 * @return boolean True if the pattern was registered with success and false otherwise.
+	 */
+	public function register( $pattern_name, $pattern_properties ) {
+		if ( ! isset( $pattern_name ) || ! is_string( $pattern_name ) ) {
+			$message = __( 'Pattern name must be a string.', 'gutenberg' );
+			_doing_it_wrong( __METHOD__, $message, '7.8.0' );
+			return false;
+		}
+
+		$this->registered_patterns[ $pattern_name ] = $pattern_properties;
+
+		return true;
+	}
+
+	/**
+	 * Unregisters a pattern.
+	 *
+	 * @param string $pattern_name     Pattern name including namespace.
+	 * @return boolean True if the pattern was unregistered with success and false otherwise.
+	 */
+	public function unregister( $pattern_name ) {
+		if ( ! $this->is_registered( $pattern_name ) ) {
+			/* translators: 1: Pattern name. */
+			$message = sprintf( __( 'Pattern "%1$s" not found.', 'gutenberg' ), $pattern_name );
+			_doing_it_wrong( __METHOD__, $message, '7.8.0' );
+			return false;
+		}
+
+		unset( $this->registered_patterns[ $pattern_name ] );
+
+		return true;
+	}
+
+	/**
+	 * Retrieves an array containing the properties of a registered pattern.
+	 *
+	 * @param string $pattern_name       Pattern name including namespace.
+	 * @return array Registered pattern properties.
+	 */
+	public function get_registered( $pattern_name ) {
+		if ( ! $this->is_registered( $pattern_name ) ) {
+			return null;
+		}
+
+		return $this->registered_patterns[ $pattern_name ];
+	}
+
+	/**
+	 * Retrieves all registered patterns.
+	 *
+	 * @return array Array of arrays containing the registered patterns properties,
+	 *               and per style.
+	 */
+	public function get_all_registered() {
+		return array_values( $this->registered_patterns );
+	}
+
+	/**
+	 * Checks if a pattern is registered.
+	 *
+	 * @param string $pattern_name       Pattern name including namespace.
+	 * @return bool True if the pattern is registered, false otherwise.
+	 */
+	public function is_registered( $pattern_name ) {
+		return isset( $this->registered_patterns[ $pattern_name ] );
+	}
+
+	/**
+	 * Utility method to retrieve the main instance of the class.
+	 *
+	 * The instance will be created if it does not exist yet.
+	 *
+	 * @since 5.3.0
+	 *
+	 * @return WP_Patterns_Registry The main instance.
+	 */
+	public static function get_instance() {
+		if ( null === self::$instance ) {
+			self::$instance = new self();
+		}
+
+		return self::$instance;
+	}
+}
+
+/**
+ * Registers a new pattern.
+ *
+ * @param string $pattern_name       Pattern name including namespace.
+ * @param array  $pattern_properties Array containing the properties of the pattern.
+ *
+ * @return boolean True if the pattern was registered with success and false otherwise.
+ */
+function register_pattern( $pattern_name, $pattern_properties ) {
+	return WP_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
+}
+
+/**
+ * Unregisters a pattern.
+ *
+ * @param string $pattern_name       Pattern name including namespace.
+ *
+ * @return boolean True if the pattern was unregistered with success and false otherwise.
+ */
+function unregister_pattern( $pattern_name ) {
+	return WP_Patterns_Registry::get_instance()->unregister( $pattern_name );
+}

lib/client-assets.php

@@ -639,15 +639,21 @@ function gutenberg_extend_settings_block_patterns( $settings ) {
 	}
 
 	$settings['__experimentalBlockPatterns'] = array_merge(
-		[
-			gutenberg_load_block_pattern( 'text-two-columns' ),
-			gutenberg_load_block_pattern( 'two-buttons' ),
-			gutenberg_load_block_pattern( 'cover-abc' ),
-			gutenberg_load_block_pattern( 'two-images' ),
-		],
+		WP_Patterns_Registry::get_instance()->get_all_registered(),
 		$settings['__experimentalBlockPatterns']
 	);
 
 	return $settings;
 }
 add_filter( 'block_editor_settings', 'gutenberg_extend_settings_block_patterns', 0 );
+
+
+/*
+ * Register default patterns if not registered in Core already.
+ */
+if ( ! WP_Patterns_Registry::get_instance()->is_registered( 'text-two-columns' ) ) {
+	register_pattern( 'core/text-two-columns', gutenberg_load_block_pattern( 'text-two-columns' ) );
+	register_pattern( 'core/two-buttons', gutenberg_load_block_pattern( 'two-buttons' ) );
+	register_pattern( 'core/cover-abc', gutenberg_load_block_pattern( 'cover-abc' ) );
+	register_pattern( 'core/two-images', gutenberg_load_block_pattern( 'two-images' ) );
+}

lib/load.php

@@ -59,6 +59,10 @@ function gutenberg_is_experiment_enabled( $name ) {
 	require dirname( __FILE__ ) . '/class-wp-block-styles-registry.php';
 }
 
+if ( ! class_exists( 'WP_Patterns_Registry' ) ) {
+	require dirname( __FILE__ ) . '/class-wp-patterns-registry.php';
+}
+
 require dirname( __FILE__ ) . '/compat.php';
 
 require dirname( __FILE__ ) . '/blocks.php';