Merge branch 'trunk' into add/igdb-example

.wp-env.json

@@ -10,5 +10,6 @@
     "./example",
     "https://downloads.wordpress.org/plugin/query-monitor.3.16.4.zip",
     "https://downloads.wordpress.org/plugin/redis-cache.2.5.3.zip"
-  ]
+  ],
+  "themes": [ "./example/theme" ]
 }

.wp-env.override.example.json

@@ -0,0 +1,7 @@
+{
+  "config": {
+    "REMOTE_DATA_BLOCKS_EXAMPLE_AIRTABLE_ELDEN_RING_ACCESS_TOKEN": "",
+    "REMOTE_DATA_BLOCKS_EXAMPLE_AIRTABLE_EVENTS_ACCESS_TOKEN": "",
+    "REMOTE_DATA_BLOCKS_EXAMPLE_SHOPIFY_ACCESS_TOKEN": ""
+  }
+}

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+## Guidelines
+
+- As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://make.wordpress.org/handbook/community-code-of-conduct/).
+
+- Contributors should review WordPress' [PHP coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/), WordPress' [JavaScript coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/) and [accessibility coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/).
+
+- Accessibility should be top of mind and thoroughly tested.
+
+- You maintain copyright over any contribution you make. By submitting a pull request you agree to release that code under [Remote Data Blocks' License](LICENSE.md).
+
+- When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
+
+## Development Setup
+
+For WP monolith:
+
+```
+npm install && npm run start:monolith
+```
+
+For WP backend + WP Components w/Next.js frontend, make sure the [wp-components repo](https://github.com/Automattic/wp-components) is at a peer level in your file system and then run from root here:
+
+```
+npm install && npm run start:decoupled
+```
+
+## Reporting Security Issues
+
+Please see [SECURITY.md](SECURITY.md).

README.md

@@ -1,10 +1,10 @@
 # Remote Data Blocks
 
-Remote Data Blocks is a WordPress plugin that brings an assortment of flexible, data-enrichable WordPress blocks to your Gutenberg Editor. The blocks are designed to make local data, remote data, and layout seamless, smooth, and productive so you can get your content to your customers your way.
+Remote Data Blocks is a WordPress plugin that brings an assortment of flexible, data-enrichable WordPress blocks into Gutenberg. These blocks make it easy for authors to mix local WordPress data, remote data, and layouts in the block editor.
 
 ## Setup
 
-1. Download the Remote Data Blocks plugin zip file.
+1. Download the [Remote Data Blocks plugin zip file](https://github.com/Automattic/remote-data-blocks/releases/latest/download/remote-data-blocks.zip).
 2. Log in to your WordPress admin panel.
 3. Navigate to Plugins > Add New.
 4. Click the "Upload Plugin" button at the top of the page.
@@ -17,11 +17,11 @@ Remote Data Blocks is a WordPress plugin that brings an assortment of flexible,
 2. Search for "remote" in the block inserter.
 3. Choose from the available blocks, such as:
 
-   - Airtable Event
-   - Elden Ring Map
+   - Airtable Events
    - Art Institute of Chicago
-   - Zip Code
-   - Shopify Product
+   - GitHub Files
+   - Zip Code Information
+   - Shopify Products
 
 4. Configure the block settings in the sidebar:
 
@@ -35,18 +35,4 @@ Remote Data Blocks is a WordPress plugin that brings an assortment of flexible,
 
 6. Use the blocks to display dynamic content from various sources directly in your posts or pages.
 
-7. Developers: extend the plugin by creating new datasources and queries. See the example files in the `example` directory for reference.
-
-## Contributing
-
-For WP monolith:
-
-```
-npm install && npm run start:monolith
-```
-
-For WP backend + WP Components w/Next.js frontend dev environment, make sure the [wp-components repo](https://github.com/Automattic/wp-components) is at peer level on your file system and then run from root here:
-
-```
-npm install && npm run start:decoupled
-```
+_Developers! You can [extend](https://github.com/Automattic/remote-data-blocks/blob/trunk/docs/extending.md) the plugin by creating new datasources and queries._

SECURITY.md

@@ -0,0 +1,5 @@
+# Reporting Security Issues
+
+WPVIP and Automattic take security bugs seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.
+
+To report a security issue, please visit [Automattic's HackerOne](https://hackerone.com/automattic) program.

docs/concepts.md

@@ -0,0 +1,28 @@
+# Core Concepts
+
+Remote Data Blocks is a WordPress plugin that enhances the Gutenberg editor by providing flexible, data-enrichable blocks. These blocks allow authors to seamlessly integrate local WordPress data, remote data, and custom layouts within the block editor.
+
+### Block-Based Architecture
+
+The plugin leverages WordPress's block editor (Gutenberg) to create custom blocks that can fetch and display data from various sources. Each block is designed to be modular and reusable.
+
+### Remote Data Integration
+
+Remote data is bound to blocks and, later, rendered via WordPress' Block Binding API.
+This enables dynamic content display directly within posts or pages using external data sources, such as:
+
+- Airtable
+- Elden Ring Map API
+- Art Institute of Chicago API
+- Zip Code databases
+- Shopify
+
+### Flexible Configuration
+
+Each block comes with its own set of configurable options, allowing users to customize the data retrieval and display according to their needs.
+
+### Developer Extensibility
+
+The plugin is designed to be extendable, allowing developers to create new datasources and queries to expand its functionality.
+
+See the [extending](extending.md) documentation for more information.

docs/extending.md

@@ -0,0 +1,94 @@
+# Extending
+
+Remote Data Blocks is designed to be extensible, allowing developers to create new data sources and queries. This guide will walk you through the process of extending the core plugin.
+
+## 1. Create a New Data Source
+
+To create a new data source:
+
+1. Create a new PHP class that extends the `HttpDatasource` class.
+2. Implement the required methods for fetching and processing data.
+
+Example:
+
+```php
+class YourCustomDatasource extends HttpDatasource {
+	public function get_endpoint(): string {
+        // Implement your endpoint logic here
+	}
+
+	public function get_request_headers(): array {
+        // Implement your headers logic here
+	}
+}
+```
+
+## 2. Create a New Query
+
+To create a new query:
+
+1. Create a new PHP class that extends the `HttpQueryContext` class.
+2. Implement the required input and output variables for executing the query.
+3. Optionally implement overrides of base class methods if needed.
+
+Example:
+
+```php
+class YourCustomQuery extends HttpQueryContext {
+    public array $input_variables = [
+        // Implement your input variables here
+    ];
+
+    public array $output_variables = [
+        // Implement your output variables here
+    ];
+
+    public function get_endpoint( array $input_variables ): string {
+        // Optionally implemented override of datasource endpoint logic here
+        // eg, to add additional query parameters
+    }
+}
+```
+
+## 3. Register Your New Block
+
+To register your new block:
+
+1. Create a new PHP file for registering your block.
+2. Use the `ConfigurationLoader` class to register your block, queries, and patterns.
+
+Example:
+
+```php
+use RemoteDataBlocks\Editor\ConfigurationLoader;
+
+function register_your_custom_block() {
+    $block_name = 'Your Custom Block';
+    $your_datasource = new YourCustomDatasource();
+    $your_query = new YourCustomQuery( $your_datasource );
+    ConfigurationLoader::register_block( $block_name, $your_query );
+    ConfigurationLoader::register_list_query( $block_name, $your_query );
+    $block_pattern = file_get_contents( __DIR__ . '/your-pattern.html' );
+    ConfigurationLoader::register_block_pattern( $block_name, 'your-namespace/your-pattern', $block_pattern );
+}
+add_action( 'register_remote_data_blocks', 'YourNamespace\\register_your_custom_block' );
+```
+
+## 4. Create Block Patterns
+
+Create HTML patterns for your block to define how the data should be displayed. Use the Remote Data Blocks binding syntax to connect data to your pattern.
+
+Example:
+
+```html
+<!-- wp:group {"layout":{"type":"constrained"}} -->
+<div class="wp-block-group">
+	<!-- wp:heading {"metadata":{"bindings":{"content":{"source":"remote-data/binding","args":{"field":"title"}}}}} -->
+	<h2 class="wp-block-heading"></h2>
+	<!-- /wp:heading -->
+	<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"remote-data/binding","args":{"field":"description"}}}}} -->
+	<p></p>
+	<!-- /wp:paragraph -->
+</div>
+<!-- /wp:group -->
+```

docs/how-it-works.md

@@ -0,0 +1,30 @@
+# How It Works
+
+At a high level, step by step, here is what is happening:
+
+1. **Block Insertion**:
+
+   - User adds a Remote Data Block to their post/page.
+   - The block is initialized with default settings.
+
+2. **Block Configuration**:
+
+   - User configures the block settings in the sidebar.
+   - For data-driven blocks, users can search or select specific items.
+
+3. **Data Fetching**:
+
+   - The block sends a request to the appropriate API or data source.
+   - Data is retrieved based on the block's configuration.
+
+4. **Data Processing**:
+
+   - Retrieved data is processed and formatted according to the block's requirements.
+
+5. **Rendering**:
+
+   - The block renders the processed data within the editor.
+   - On the frontend, the block displays the data to site visitors.
+
+6. **Updates and Real-time Changes**:
+   - Some blocks may support real-time updates or periodic data refreshes.

example/airtable/elden-ring-map/inc/queries/class-airtable-elden-ring-list-locations-query.php

@@ -2,9 +2,9 @@
 
 namespace RemoteDataBlocks\Example\Airtable\EldenRingMap;
 
-use RemoteDataBlocks\Config\QueryContext;
+use RemoteDataBlocks\Config\HttpQueryContext;
 
-class AirtableEldenRingListLocationsQuery extends QueryContext {
+class AirtableEldenRingListLocationsQuery extends HttpQueryContext {
 	public array $input_variables = [
 		'map_name' => [
 			'type' => 'string',

example/airtable/elden-ring-map/inc/queries/class-airtable-elden-ring-list-maps-query.php

@@ -2,9 +2,9 @@
 
 namespace RemoteDataBlocks\Example\Airtable\EldenRingMap;
 
-use RemoteDataBlocks\Config\QueryContext;
+use RemoteDataBlocks\Config\HttpQueryContext;
 
-class AirtableEldenRingListMapsQuery extends QueryContext {
+class AirtableEldenRingListMapsQuery extends HttpQueryContext {
 	public array $input_variables = [
 		'search' => [
 			'type' => 'string',

example/airtable/elden-ring-map/inc/queries/class-airtable-elden-ring-map-datasource.php

@@ -10,6 +10,10 @@ class AirtableEldenRingMapDatasource extends HttpDatasource {
 
 	public function __construct( private string $access_token ) {}
 
+	public function get_display_name(): string {
+		return 'Elden Ring Map';
+	}
+
 	public function get_endpoint(): string {
 		return 'https://api.airtable.com/v0/appqI3sJ9R2NcML8Y';
 	}

example/airtable/events/inc/queries/class-airtable-events-datasource.php

@@ -7,6 +7,10 @@
 class AirtableEventsDatasource extends HttpDatasource {
 	public function __construct( private string $access_token ) {}
 
+	public function get_display_name(): string {
+		return 'Events';
+	}
+
 	public function get_endpoint(): string {
 		return 'https://api.airtable.com/v0/appVQ2PAl95wQSo9S/tblyGtuxblLtmoqMI';
 	}

example/airtable/events/inc/queries/class-airtable-get-event-query.php

@@ -2,9 +2,9 @@
 
 namespace RemoteDataBlocks\Example\Airtable\Events;
 
-use RemoteDataBlocks\Config\QueryContext;
+use RemoteDataBlocks\Config\HttpQueryContext;
 
-class AirtableGetEventQuery extends QueryContext {
+class AirtableGetEventQuery extends HttpQueryContext {
 	public array $input_variables = [
 		'event_id' => [
 			'name'      => 'Event ID',

example/airtable/events/inc/queries/class-airtable-list-events-query.php

@@ -2,9 +2,9 @@
 
 namespace RemoteDataBlocks\Example\Airtable\Events;
 
-use RemoteDataBlocks\Config\QueryContext;
+use RemoteDataBlocks\Config\HttpQueryContext;
 
-class AirtableListEventsQuery extends QueryContext {
+class AirtableListEventsQuery extends HttpQueryContext {
 	public array $input_variables = [
 		'search' => [
 			'type' => 'string',

example/github/remote-data-blocks/inc/queries/class-github-datasource.php

@@ -15,6 +15,10 @@ public function __construct( string $repo_owner, string $repo_name, string $ref
 		$this->ref        = $ref;
 	}
 
+	public function get_display_name(): string {
+		return 'GitHub';
+	}
+
 	public function get_endpoint(): string {
 		return sprintf(
 			'https://api.github.com/repos/%s/%s/git/trees/%s?recursive=1',

example/github/remote-data-blocks/inc/queries/class-github-get-file-as-html-query.php

@@ -2,9 +2,9 @@
 
 namespace RemoteDataBlocks\Example\GitHub;
 
-use RemoteDataBlocks\Config\QueryContext;
+use RemoteDataBlocks\Config\HttpQueryContext;
 
-class GitHubGetFileAsHtmlQuery extends QueryContext {
+class GitHubGetFileAsHtmlQuery extends HttpQueryContext {
 	public array $input_variables = [
 		'file_path' => [
 			'name' => 'File Path',

example/github/remote-data-blocks/inc/queries/class-github-list-files-query.php

@@ -2,10 +2,10 @@
 
 namespace RemoteDataBlocks\Example\GitHub;
 
-use RemoteDataBlocks\Config\HttpDatasourceConfig;
-use RemoteDataBlocks\Config\QueryContext;
+use RemoteDataBlocks\Config\HttpDatasource;
+use RemoteDataBlocks\Config\HttpQueryContext;
 
-class GitHubListFilesQuery extends QueryContext {   
+class GitHubListFilesQuery extends HttpQueryContext {   
 	public array $input_variables = [
 		'file_extension' => [
 			'name' => 'File Extension',
@@ -40,7 +40,7 @@ class GitHubListFilesQuery extends QueryContext {
 		],
 	];
 
-	public function __construct( private HttpDatasourceConfig $datasource, string $file_extension ) {
+	public function __construct( private HttpDatasource $datasource, string $file_extension ) {
 		parent::__construct( $datasource );
 		$this->output_variables['root_path'] = sprintf( '$.tree[?(@.path =~ /\\.%s$/)]', ltrim( $file_extension, '.' ) );
 	}

example/rest-api/art-institute/inc/queries/class-art-institute-datasource.php

@@ -5,6 +5,10 @@
 use RemoteDataBlocks\Config\HttpDatasource;
 
 class ArtInstituteOfChicagoDatasource extends HttpDatasource {
+	public function get_display_name(): string {
+		return 'Art Institute of Chicago';
+	}
+
 	public function get_endpoint(): string {
 		return 'https://api.artic.edu/api/v1/artworks';
 	}