Update/documentation/extending last looks (#320)

* changing example. * adding overrides detail * adding link * adding direct playground link * review changes * grammar and spelling * grammar and spelling * grammar and spelling * switching title case * revising block patterns * formatting changes * removing backtic * Update docs/extending/data-source.md Co-authored-by: Chris Zarate <[email protected]> * fixing formatting and error * Update docs/extending/overrides.md Co-authored-by: Chris Zarate <[email protected]> * Update docs/extending/overrides.md Co-authored-by: Chris Zarate <[email protected]> * wording update * Update docs/extending/overrides.md Co-authored-by: Chris Zarate <[email protected]> * Update docs/extending/overrides.md Co-authored-by: Chris Zarate <[email protected]> * Update docs/extending/overrides.md Co-authored-by: Chris Zarate <[email protected]> * Update docs/extending/query-output_schema.md Co-authored-by: Chris Zarate <[email protected]> * Update docs/extending/query-output_schema.md Co-authored-by: Chris Zarate <[email protected]> * Update docs/extending/query.md Co-authored-by: Chris Zarate <[email protected]> * Update data source example with Jacob's suggestion * Formatting updates --------- Co-authored-by: Chris Zarate <[email protected]>
Automattic · Jan 27, 2025 · 0ae1d02 · 0ae1d02
1 parent 7546768
commit 0ae1d02
Show file tree

Hide file tree

Showing 8 changed files with 51 additions and 17 deletions.
diff --git a/docs/extending/block-patterns.md b/docs/extending/block-patterns.md
@@ -1,8 +1,16 @@
 # Block patterns
 
-Patterns allow you to represent your remote data in different ways. The plugin registers an unstyled block pattern anytime you register a remote data block either in the WordPress admin or with `register_remote_data_block`. You can create additional patterns in the WordPress Site Editor or programmatically by passing a `patterns` property to your block options.
+Patterns allow you to represent your remote data in different ways.
 
-You cannot edit the default pattern, but you can duplicate it and make changes. We recommend starting with a duplicate and then making changes in the Site Editor. If you want to lock the pattern down from further edits, copy the block markup from the editor and associate the pattern via code.
+The plugin registers an unstyled block pattern any time you register a remote data block either in the WordPress admin or with `register_remote_data_block`.
+
+You can create additional patterns in the WordPress Site Editor or programmatically by passing a `patterns` property to your block options.
+
+You cannot edit the default pattern, but you can duplicate it and make changes.
+
+We recommend duplicating the default pattern and then making changes in the Site Editor. Once you've created your preferred pattern, you can associate it with the block in the `register_remote_data_block` call.
+
+If you want to make the pattern uneditable in the Site Editor, you can copy the block markup to a file and commit it to your repository.
 
 ## Example
 

diff --git a/docs/extending/block-registration.md b/docs/extending/block-registration.md
@@ -2,8 +2,8 @@
 
 Use the `register_remote_data_block` function to register your block and associate it with your query and data source. This example:
 
-1. Creates a data source
-2. Associates the data source with a query
+1. Creates a data source.
+2. Associates the data source with a query.
 3. Defines the output schema of a query, which tells the plugin how to map the query response to blocks.
 4. Registers a remote data block.
 

diff --git a/docs/extending/data-source.md b/docs/extending/data-source.md
@@ -53,15 +53,31 @@ $zipcode_query = HttpQuery::from_array( [
 ])
 ```
 
-In this case the `data_source` has a built in `get_endpoint()` method. You could also retrieve the endpoint this way:
+In this case the `data_source` has a built in `get_endpoint()` method. Other configuration options can be retrieved directly:
 
 ```php
+$data_source = HttpDataSource::from_array( [
+    'service_config' => [
+        '__version' => 1,
+        'display_name' => 'More Complicated Example API',
+        'endpoint' => 'https://api.complexexample.com/',
+        'request_headers' => [
+            'Content-Type' => 'application/json',
+            'X-Api-Key' => MY_API_KEY_CONSTANT,
+        ],
+    ],
+] );
+
+$my_config = [
+ 'some_identifier' => 'id-123'
+];
+
 $zipcode_query = HttpQuery::from_array( [
-    'data_source' => $zipcode_data_source,
-    'endpoint' => function ( array $input_variables ) use ( $zipcode_data_source ): string {
-        return  $zipcode_data_source->to_array()['service_config']['endpoint'] . $input_variables['zip_code'];
+    'data_source' => $data_source,
+    'endpoint' => function ( array $input_variables ) use ( $data_source, $my_config ): string {
+        return  return $data_source->get_endpoint() . $my_config['some_identifier'] . "/" . $input_variables['search'];
     },
-])
+] )
 ```
 
 The goal with design was to provide you with flexibility you need to represent any data source.

diff --git a/docs/extending/index.md b/docs/extending/index.md
@@ -5,7 +5,7 @@
 
 Data sources and queries can be configured in the plugin UI, but sometimes, you need to extend the plugin to implement custom functionality. Remote Data Blocks provides extendable classes, global functions, hooks, and filters to help you connect to any data source, parse responses, and customize the display of data.
 
-## Data flow
+## Data Flow
 
 Here's a short overview of how data flows through the plugin when a post with a remote data block is rendered:
 
@@ -23,7 +23,7 @@ Providing a custom data source, query, or query runner gives you complete contro
 
 Here are some detailed overviews of these classes with notes on how and why to extend them:
 
-- [Data source](data-source.md)
+- [Data Source](data-source.md)
 - [Query](query.md)
 
 Once you've defined your data source and queries, you can [register a remote data block](block-registration.md) that uses them. That block can use a [pattern](block-patterns.md) for display. You can also use [overrides](./overrides.md) to dynamically select the displayed content.

diff --git a/docs/extending/overrides.md b/docs/extending/overrides.md
@@ -1,8 +1,14 @@
 # Overrides
 
-Overrides provide a way to customize the behavior of remote data blocks on a per-block basis. You can use them to modify the underlying query input variables, adjust the query response, or change the caching behavior. Overrides are defined when you register a remote data block and can be enabled or disabled via the block settings in the editor.
+Overrides provide a way to customize the behavior of remote data blocks on a per-block basis. You can use them to modify the underlying query input variables, adjust the query response, or change the caching behavior. Overrides are defined when you register a remote data block and can be enabled or disabled via the block settings in the WordPress editor.
 
-The actual implementation of overrides is left to you. Here is an example of an override that modifies the query input variables based on a query variable (supplied by a rewrite rule):
+If you have multiple instances of the same remote data block in a piece of content, each instance can have different overrides enabled. By default, no overrides are enabled.
+
+Here is an example of an override that modifies the query input variables based on the URL.
+
+You could use this to build a "product page" in the WordPress admin that would be able to display any product, using an ID from the URL, e.g.: https://example.com/product/123456
+
+The example takes advantage of the [`add_rewrite_rule`](https://developer.wordpress.org/reference/functions/add_rewrite_rule/) function and the [`query_vars`](https://developer.wordpress.org/reference/hooks/query_vars/) filter that are built into WordPress.
 
 ```php
 register_remote_data_block( [
@@ -39,6 +45,8 @@ add_filter( 'remote_data_blocks_query_input_variables', function ( array $input_
 }, 10, 2 );
 ```
 
+As you can see, the `remote_data_blocks_query_input_variables` filter is passed a list of enabled overrides. You need to add logic to identify which filters are enabled and act accordingly.
+
 The `overrides` property in the block registration array enables a panel in the block settings that allows content authors to enable or disable the override:
 
 <img width="276" alt="An overrides panel in a remote data block settings panel" src="https://github.com/user-attachments/assets/e701e621-99f9-4c2e-b34d-cfef352af2ae" />
diff --git a/docs/extending/query-output_schema.md b/docs/extending/query-output_schema.md
@@ -1,6 +1,6 @@
-# The Query `output_schema` property
+# Query `output_schema` property
 
-The `output_schema` property is where your data shape definition happens. It should be created with care and requires updates anytime the incoming response changes.
+The `output_schema` property is where your data shape definition happens. It should be created with care and requires updates whenever the incoming response changes.
 
 Unless your API returns a single value, `type` will be constructed of an associative array of nested output schemas that eventually resolve to one of the accepted primitive types:
 

diff --git a/docs/extending/query-runner.md b/docs/extending/query-runner.md
@@ -4,7 +4,7 @@ A query runner executes a query and processes the results of a query. The defaul
 
 - Your API does not respond with JSON or requires custom deserialization logic.
 - Your API uses a non-HTTP transport.
-- You want to implement custom processing of the response data, which is not possible with the provided filters.
+- You want to implement custom processing of the response data, which is not possible with the [provided filters](./hooks.md).
 
 ## Custom QueryRunner for HTTP queries
 

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -1,6 +1,8 @@
 # Quickstart
 
-The most basic way to see Remote Data Blocks in action is to launch the plugin in WordPress Playground. You can do this by clicking the "Launch in WordPress Playground" badge in the [README](../README.md).
+The easiest way to see Remote Data Blocks in action is to launch the plugin in WordPress Playground.
+
+[![Launch in WordPress Playground](https://img.shields.io/badge/Launch%20in%20WordPress%20Playground-DA9A45?style=for-the-badge&logo=wordpress)](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/Automattic/remote-data-blocks/trunk/blueprint.json)
 
 However, the more advanced use case is providing your own custom configuration through code. This guide will walk you through the steps to do this.