Update documentation and examples

* initial changes

* adding strengths and weaknesses

* edits and renaming

* another name change and airtable stuff

* updating google sheets

* adding screen shot

* adding screen shot

* adding shopify and Salesforce skeleton

* final first-pass updates to tutorials

* Airtable tutorial grammatical fixes

Signed-off-by: brookewp <[email protected]>

* Google sheets tutorial grammatical fixes

Signed-off-by: brookewp <[email protected]>

* Salesforce tutorial grammatical fixes

Signed-off-by: brookewp <[email protected]>

* Shopify tutorial grammatical fixes

Signed-off-by: brookewp <[email protected]>

* HTTP tutorial grammatical fixes

Signed-off-by: brookewp <[email protected]>

* Concepts grammatical fixes and formatting

Signed-off-by: brookewp <[email protected]>

* Tutorial docs formatting

Signed-off-by: brookewp <[email protected]>

* Remaining proof-read docs

Signed-off-by: brookewp <[email protected]>

* adding block-bindings document

* cleaning up final changes from Workflows to Tutorials

* Add links from concepts index page

* Fix formatting

* Reordering to reflect sequence of events and utility

* Flesh out block registration options

* small updates

* updates to query

* settings forms fixes (#297)

* allow undefined values for handleOnChange to match allowed undefined in state values

* allow adding invalid string in google credentials input

* reset google spreadsheet and sheet inputs on credentials change

* reset airtable base and tables on token change

* update the register blocks function names in airtable conference event block registration

* url encode sheet name to fix invalid endpoint error (#298)

* url encode sheet name to fix invalid endpoint error

* use bracket notation for defining JSON path for Google Sheets

* Remove example glue code and example access tokens

* Update "Conference events" example

* Fix formatting

* adding better type documentation

* Fix block registration code example

Signed-off-by: brookewp <[email protected]>

* Add ServerSideRender package and types

* Update Elden Ring Map example to Leaflet Map block

To simplify, this block no longer uses register_remote_data_block or the
Interactivity API.

* fix typo and improve link by linking to a section of file

* fix formatting

* Update GitHub example

* Update Google Sheets example

* Minor example README updates

* Update Shopify example

* Restore linting to example code

* Remove unused suppression

* Update Beta warning

* Update Zip code example

* Update Art example

* Fix typo

* Add entrypoint README

---------

Signed-off-by: brookewp <[email protected]>
Co-authored-by: brookewp <[email protected]>
Co-authored-by: chriszarate <[email protected]>
Co-authored-by: Shekhar Wagh <[email protected]>
Co-authored-by: Shekhar Wagh <[email protected]>

.wp-env.json

@@ -12,9 +12,7 @@
   },
   "plugins": [
     ".",
-    "./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" ]
+  ]
 }

README.md

@@ -1,16 +1,54 @@
+---
+### :warning: This plugin is currently in Beta. Breaking changes could occur with any update. Please test each release thoroughly before updating.
+---
+
 # Remote Data Blocks
 
 **Remote Data Blocks** is a WordPress plugin that makes it easy to combine content and remote data in the block editor. Easily register blocks that load data from Airtable, Google Sheets, Shopify, GitHub, or any other API. Your data stays in sync. Built-in caching ensures performance and reliability.
 
-[![Launch in WordPress Playground](https://img.shields.io/badge/Launch%20in%20WordPress%20Playground-blue?style=for-the-badge)](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/Automattic/remote-data-blocks/trunk/blueprint.json)
+Remote Data Blocks lets you take tabular data, stored elsewhere and display it as headings, paragraphs, images and buttons in WordPress. Either as a list of all the rows in your table or as a single entry. [Read more about well supported use cases](docs/concepts/index.md#supported-use-cases).
+
+[![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)
 
 [Launch the plugin in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/Automattic/remote-data-blocks/trunk/blueprint.json) and explore. An example API ("Conference Event") is included, or visit Settings > Remote Data Blocks to add your own. Visit the [workflows guide](docs/workflows/index.md) to dive in.
 
 ## Installation
 
-[![Download Latest Release](https://img.shields.io/badge/Download%20Latest%20Release-blue?style=for-the-badge)](https://github.com/Automattic/remote-data-blocks/releases/latest/download/remote-data-blocks.zip)
+The latest version of the plugin is available in the default `trunk` branch of this repository.
+
+### Install via `git subtree`
+
+We recommend installing the latest plugin version [via `git subtree`][wpvip-plugin-subtrees] within your site's repository:
+
+```bash
+# Enter your project's root directory:
+cd my-site-repo/
+
+# Add a subtree for the trunk branch:
+git subtree add --prefix plugins/remote-data-blocks [email protected]:Automattic/remote-data-blocks.git trunk --squash
+```
+
+To deploy the plugin to a remote branch, `git push` the committed subtree.
+
+The `trunk` branch will stay up to date with the latest version of the plugin. Use this command to pull the latest `trunk` branch changes:
 
-### Requirements
+```bash
+git subtree pull --prefix plugins/remote-data-blocks [email protected]:Automattic/remote-data-blocks.git trunk --squash
+```
+
+Ensure that the plugin is up-to-date by pulling changes often.
+
+Note: We **do not recommend** using `git submodule`. [Submodules on WPVIP that require authentication][wpvip-plugin-submodules] will fail to deploy.
+
+### Install via ZIP file
+
+The latest version of the plugin can be downloaded from the [repository's Releases page](https://github.com/Automattic/remote-data-blocks/releases/latest/download/remote-data-blocks.zip). Unzip the downloaded plugin and add it to the `plugins/` directory of your site's GitHub repository.
+
+### Plugin activation
+
+We recommend [activating plugins with code][wpvip-plugin-activate].
+
+## Requirements
 
 - PHP 8.1+
 - WordPress 6.7+
@@ -19,11 +57,8 @@ A [persistent object cache](https://developer.wordpress.org/reference/classes/wp
 
 ## Next steps
 
-> [!WARNING]
-> This plugin is under heavy active development and breaking changes may land without warning. If you are interested in evaluating or testing this plugin, please [open an issue](https://github.com/Automattic/remote-data-blocks/issues/new/choose) and we'll be in touch!
-
 - Learn about the [core concepts](docs/concepts/index.md) behind Remote Data Blocks.
-- Follow along with [example workflows](docs/workflows/index.md) to see Remote Data Blocks in action.
+- Create your first connecting following our [tutorials](docs/tutorials/index.md) to see Remote Data Blocks in action.
 - If you're a developer, you're ready to [extend Remote Data Blocks with custom code](docs/extending/index.md).
 - Interested in contributing? Issues, pull requests, and discussions are welcome. Please see our [contribution guide](CONTRIBUTING.md) for more information.
 
@@ -34,3 +69,7 @@ Remote Data Blocks is licensed under the [GPLv2 (or later)](LICENSE).
 ---
 
 Made with ❤️ by [WordPress VIP](https://wpvip.com/).
+
+[wpvip-plugin-activate]: https://docs.wpvip.com/how-tos/activate-plugins-through-code/
+[wpvip-plugin-submodules]: https://docs.wpvip.com/technical-references/plugins/installing-plugins-best-practices/#h-submodules
+[wpvip-plugin-subtrees]: https://docs.wpvip.com/technical-references/plugins/installing-plugins-best-practices/#h-subtrees

docs/concepts/block-bindings.md

@@ -1 +1,9 @@
 # Block bindings
+
+Remote Data Blocks takes advantage of the [Block Bindings API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-bindings/). This Core WordPress API allows you to “bind” dynamic data to the block's attributes, which are then reflected in the final HTML markup.
+
+The Block Bindings API allows Remote Data Blocks to read from different sources without needing to write custom block boilerplate, React, block registration, and other particulars of writing custom blocks from scratch for each new source you want to read from.
+
+For a quick overview, the [announcement post](https://make.wordpress.org/core/2024/03/06/new-feature-the-block-bindings-api/) is very helpful. The Block Bindings API is evolving, and an in-depth understanding isn't necessary for day-to-day use.
+
+But if you want to dig deeper into the internals of how Remote Data Blocks works, the [public documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-bindings/) is available.

docs/concepts/field-shortcodes.md

@@ -1 +1,13 @@
 # Field shortcodes
+
+One of the current limitations of the [block bindings API](./block-bindings.md) is that it is restricted to a small number of core blocks and attributes. For example, currently, you cannot bind to the content of a table block or a custom block. You also cannot bind to a _subset_ of a block's content.
+
+As a partial workaround, this plugin provides a way to use remote data in some places where block bindings are not supported. We call this feature "field shortcodes," and it is available in any block that uses [rich text](https://developer.wordpress.org/block-editor/reference-guides/richtext/), such as tables, lists, and custom blocks. Look for the field shortcode button in the rich text formatting toolbar:
+
+<img width="535" alt="Field shortcode button" src="https://github.com/user-attachments/assets/8ce0bd18-367e-46d5-a870-22819c42ff4a" />
+
+Clicking this button will open a modal that allows you to select a field from a remote data source, resulting in an inline remote data binding. Just like remote data blocks, this binding will load the latest data from the remote source when the content is rendered.
+
+<img width="684" alt="A bulleted list using several field shortcodes to describe three conference events" src="https://github.com/user-attachments/assets/6527dcc0-c0ed-42ab-9655-b8fc2510e15b" />
+
+Field shortcodes compile to HTML, so they are portable, safe, and have a built-in fallback.

docs/concepts/index.md

@@ -2,44 +2,95 @@
 
 Remote Data Blocks allows you to integrate remote data into posts, pages, patterns, or anywhere else on your site where you use the block editor. This guide will help you understand the core concepts of the plugin and how they work.
 
-## Remote data
+## Supported use cases
 
-**Remote data** refers to data that is fetched from an external source, such as an API or a third-party service. This might be a product in your Shopify store, data in an Airtable or Google Sheet, or a file in a GitHub repository. Remote data is usually fetched via HTTP requests but you can [extend the plugin](../extending/index.md) to support other transports.
+Like WordPress, Remote Data Blocks is flexible. It can be used to enable advanced integrations with external data.
 
-## Remote data block
+Below, you'll find specific use cases where Remote Data Blocks shines. We are working to expand these use cases, but before you start, consider if Remote Data Blocks is the right tool for the job.
 
-A **remote data block** is a custom block that fetches and displays data from a specific remote source. Each remote data block has a unique name and provides a specific kind of data.
+### Remote Data Blocks is a good fit if:
 
-For example, you might have a remote data block named "Shopify Product" that fetches a product from your Shopify store and displays the product's name, description, price, and image. Or, you might have a remote data block named "Conference event" that displays rows from an Airtable and displays the event's name, location, and type.
+- Your remote data represents entities with a consistent schema.
+  - **Example:** Product data representing items of clothing with defined attributes like “Name,” “Price,” “Color,” “Size,” etc.
+- You want humans to select specific entities for display within the block editor.
+  - **Example:** Select and display an item of clothing within a marketing post.
+- You want to display arbitrary remote data based on a URL parameter and are willing to write a small amount of code.
+  - **Example:** Create a page and rewrite rule for /products/{product_id}/ and configure a Remote Data Block on that page to display the referenced product.
+- Your presentation of remote data aligns with the capabilities of Block Bindings.
+  - **Example:** Display an item of clothing using a core paragraph, heading, image, and button blocks.
+- You do not require complex filtering or pagination.
+  - **Example:** To select an item of clothing, load a finite list of top-selling products or search all products by a specific term.
+- Your data is denormalized and relatively flat.
+  - **Example:** A row from a Google Sheet with no references to external entities.
+
+### Remote Data Blocks may not be a good fit if:
+
+- Your remote data is schema-less, or the schema changes over time.
+  - Queries for remote data must define a schema for their return data. Schema changes result in broken blocks.
+- You want to display remote data outside the context of the block editor.
+  - Block bindings are only available in block content—posts, pages, or full-site editing. Using our plugin may still provide some benefit (e.g., caching) but could require significant custom PHP code.
+- Your data is normalized (and cannot be denormalized automatically by your API).
+  - Some APIs can denormalize data by automatically “inflating” referenced records for you. For example, data representing an item of clothing might reference a color by ID instead of a renderable string like “forest green.” If your API does not denormalize this relationship automatically, you will need to write custom code to perform additional queries and stitch the responses together.
+  - This can lead to a large number of API requests that your API may not tolerate. Airtable’s API, for example, imposes a rate limit of five requests per second, making multiple calls impractical.
+- You have multiple remote data sources that require interaction. Or, you want to implement a complex content architecture using Remote Data Blocks instead of leveraging WordPress custom post types and/or taxonomies.
+  - These two challenges are directly related to the issues with normalized data. If you have data sources that relate to one another, you have to write custom code to query missing data and stitch them together.
+  - Judging complexity is difficult, but implementing large applications using Remote Data Blocks is not advisable.
+- You require complex filtering or rely heavily on pagination.
+  - Our UI components for filtering and pagination are still under development.
+
+Over time, Remote Data Blocks will grow and improve and these guidelines will change.
+
+## Remote data source
+
+**Remote data source** refers to data that is fetched from an external source, such as an API or a third-party service. This might be a product in your Shopify store, data in an Airtable or Google Sheet, or a file in a GitHub repository. Remote data is usually fetched via HTTP requests, but you can [extend the plugin](../extending/index.md) to support other transports.
+
+Simple data sources can be configured via the plugin's settings screen, while others may require custom PHP code (see [extending](../extending/index.md)).
+
+## Queries
 
-Remote data blocks are **container blocks** that contain other blocks and provide remote data to them. You retain full control over the layout, design, and content. You can leverage patterns to enable consistent styling and workflows, and you can customize the block's appearance using the block editor or `theme.json`.
+**Queries** defines how data is fetched, processed, and displayed. Queries delegate some logic to a **data source**, which can be reused by multiple queries. For example, one query to retrieve a single item, and one to retrieve a list.
 
-Remote data blocks are custom blocks, but they are created and registered by our plugin and don't require custom block development. Remote data is loaded via [the block bindings API](https://make.wordpress.org/core/2024/03/06/new-feature-the-block-bindings-api/).
+Simple queries can be configured via the plugin's settings screen, while others may require custom PHP code (see [extending](../extending/index.md)).
 
-## Data sources and queries
+## Remote data block
+
+A **remote data block** is a custom block connected to a specific query. Each remote data block has a unique name and is strictly tied to a data source.
 
-Each remote data block is associated with at least one **query** that defines how data is fetched, processed, and displayed. Queries delegate some logic to a **data source**, which can be reused by multiple queries.
+For example, you might have a remote data block named "Shopify Product" that fetches a product from your Shopify store and displays the product's name, description, price, and image. Or, you might have a remote data block named "Conference event" that displays rows from an Airtable and displays the event's name, location, and type.
 
-Simple data sources and queries can be configured via the plugin's settings screen, while others may require custom PHP code (see [extending](../extending/index.md)).
+Remote data blocks are **container blocks** that contain other blocks and provide remote data to them. You retain complete control over the layout, design, and content. You can leverage patterns to enable consistent styling and customize the block's appearance using the block editor or `theme.json`.
+
+Remote data blocks are custom blocks, but they are created and registered by our plugin and don't require custom block development. Remote data is loaded via [the block bindings API](./block-bindings.md) or [field shortcodes](./field-shortcodes.md).
 
 ## Data fetching
 
-Data fetching is handled by the plugin and wraps `wp_remote_request`. When a request to your site resolves to one or more remote data blocks, the remote data will be fetched and potentially cached by our plugin. Multiple requests for the same data within a single page load will be deduped, even if the requests are not cacheable.
+The plugin handles data fetching and wraps[`wp_remote_request`](https://developer.wordpress.org/reference/functions/wp_remote_request/).
+
+When a request to your site renders one or more remote data blocks, our plugin will fetch and potentially cache the remote data. Multiple requests for the same data within a single page load will be deduped, even if the requests are not cacheable.
 
 ### Caching
 
-The plugin offers a caching layer for optimal performance and to help avoid rate limiting from remote data sources. If your WordPress environment has configured a [persistent object cache](https://developer.wordpress.org/reference/classes/wp_object_cache/#persistent-cache-plugins), it will be used. Otherwise, the plugin will utilize in-memory (per-page-load) caching. Deploying to production without a persistent object cache is not recommended.
+The plugin offers a caching layer for optimal performance and helps avoid rate limiting from remote data sources. It will be used if your WordPress environment configures a [persistent object cache](https://developer.wordpress.org/reference/classes/wp_object_cache/#persistent-cache-plugins). Otherwise, the plugin will utilize in-memory (per-page-load) caching. Deploying to production without a persistent object cache is not recommended.
 
-The default TTL for all cache objects is 60 seconds, but it can be [configured per query or per request](../extending/query.md#get_cache_ttl).
+The default TTL for all cache objects is 60 seconds, but it can be [configured per query or request](../extending/query.md#get_cache_ttl).
 
 ## Theming
 
 Remote data blocks can be styled using the block editor's style settings, `theme.json`, or custom stylesheets. See the [example child theme](https://github.com/Automattic/remote-data-blocks/tree/trunk/example/theme) for more details.
 
 ## Patterns
 
-Since remote data blocks are container blocks, you can use patterns to create reusable layouts and to streamline your workflows. Patterns can be associated with a remote data block in the "Pattern" settings in the sidebar of the pattern editor. Once associated with a remote data block, patterns will appear in the pattern selection modal. The plugin supports both synced and unsynced patterns.
+Since remote data blocks are container blocks, you can associate a remote data block with a pattern to create reusable layouts. You link a pattern to a particular remote data block in the Site Editor. You will see a new Remote Data Blocks section in the right-hand panel when editing a pattern.
+
+![Screenshot showing the right hand panel of the WordPress Site Editor](patterns-right-panel.png)
+
+Select the specific block that is appropriate for this pattern. Once saved, content creators can select this pattern when adding the associated remote data block.
+
+You can also create a pattern directly from the content.
+<video src="https://github.com/user-attachments/assets/358d9d40-557b-4f39-b943-ed73d6f18adb"></video>
+
+The plugin supports both synced and unsynced patterns.
 
 ## Technical concepts
 
-If you're a developer and want to understand the internals of Remote Data Blocks so that you can extend its functionality, head over the [extending guide](../extending/index.md).
+If you want to understand the internals of Remote Data Blocks so that you can extend its functionality, head over to the [extending guide](../extending/index.md).

docs/extending/block-patterns.md

@@ -1,6 +1,6 @@
 # Block patterns
 
-Patterns allow you to represent your remote data if different ways. By default, the plugin registers a unstyled block pattern that you can use out of the box. You can create additional patterns in the WordPress Dashboard or programmatically by passing a `patterns` property to your block options.
+Patterns allow you to represent your remote data in different ways. By default, the plugin registers an unstyled block pattern that you can use out of the box. You can create additional patterns in the WordPress Dashboard or programmatically by passing a `patterns` property to your block options.
 
 Example: