-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Additional beta docs improvements (#300)
* 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 README typo * Slight rewording in Block Bindings docs * Slight rewording in Airtable tutorial * Reorder tutorials list to be alphabetical * Add more detail to the HTTP tutorial * Add Shopify steps for setting up API access * Formatting fixes * Move warning and use GitHub notice style * Remove outdated instructions * Remove link * Promote Next Steps * Remove footer (it's duplicated on remotedatablocks.com) * Fix tutorial links * Update code example links * Fix tutorials link * Small grammar fix * Update link to LICENSE (not a Markdown file) * Use absolute image references * query examples * finishing up output schema revisions * grammer stuff * Start of a Quickstart * extending extending * grammer changes * update to block patterns * fixing typo * start work on block registration * More content in the quickstart * Auto formatting --------- Signed-off-by: brookewp <[email protected]> Co-authored-by: Jacob Wayne Smith <[email protected]> Co-authored-by: brookewp <[email protected]> Co-authored-by: chriszarate <[email protected]> Co-authored-by: Shekhar Wagh <[email protected]>
- Loading branch information
5 people
authored
Jan 18, 2025
1 parent
e1b6b7a
commit f6968bb
Showing
23 changed files
with
457 additions
and
259 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,52 +1,20 @@ | ||
| --- | ||
| ### :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. | ||
| > [!WARNING] | ||
| > This plugin is currently in Beta. Breaking changes could occur with any update. Please test each release thoroughly before updating. | ||
| 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). | ||
| **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. [Read more about well-supported use cases](docs/concepts/index.md#supported-use-cases). | ||
|
|
||
| [](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 | ||
|
|
||
| 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: | ||
|
|
||
| ```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 | ||
| [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. Read our [tutorials](docs/tutorials/index.md) to dive in. | ||
|
|
||
| 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 | ||
| ## Next steps | ||
|
|
||
| We recommend [activating plugins with code][wpvip-plugin-activate]. | ||
| - Learn about the [core concepts](docs/concepts/index.md) behind Remote Data Blocks. | ||
| - Follow our [tutorials](docs/tutorials/index.md) to create your first connection and 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. | ||
|
|
||
| ## Requirements | ||
|
|
||
|
|
@@ -55,21 +23,10 @@ We recommend [activating plugins with code][wpvip-plugin-activate]. | |
|
|
||
| A [persistent object cache](https://developer.wordpress.org/reference/classes/wp_object_cache/#persistent-cache-plugins) is not strictly required, but it is highly recommended for optimal performance and to help avoid rate limiting from remote data sources. If your WordPress environment does not provide persistent object cache, the plugin will utilize in-memory (per-request) caching. | ||
|
|
||
| ## Next steps | ||
| ## Installation | ||
|
|
||
| - Learn about the [core concepts](docs/concepts/index.md) behind Remote Data Blocks. | ||
| - 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. | ||
| Download [the latest release of the plugin](https://github.com/Automattic/remote-data-blocks/releases/latest/download/remote-data-blocks.zip), unzip, and add it to the `plugins/` directory of your WordPress site. | ||
|
|
||
| ## License | ||
|
|
||
| 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 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,45 +1,95 @@ | ||
| # Data source | ||
|
|
||
| A data source defines basic reusable properties of an API and is used by a [query](query.md) to reduce boilerplate. It helps this plugin represent your data source in the plugin settings screen and other UI. | ||
| A data source defines the basic reusable properties of an API and is used by a [query](query.md) to reduce repeating code with every query. It also helps define how your data source looks in the WordPress admin. | ||
|
|
||
| ## Example | ||
|
|
||
| Most HTTP-powered APIs can be represented by defining a class that extends `HttpDataSource`. Here's an example of a data source for an example HTTP API: | ||
|
|
||
| ```php | ||
| $data_source = HttpDataSource::from_array( [ | ||
| 'service_config' => [ | ||
| '__version' => 1, | ||
| 'display_name' => 'Example API', | ||
| 'endpoint' => 'https://api.example.com/', | ||
| 'request_headers' => [ | ||
| 'Content-Type' => 'application/json', | ||
| 'X-Api-Key': MY_API_KEY_CONSTANT, | ||
| ], | ||
| ], | ||
| 'service_config' => [ | ||
| '__version' => 1, | ||
| 'display_name' => 'Example API', | ||
| 'endpoint' => 'https://api.example.com/', | ||
| 'request_headers' => [ | ||
| 'Content-Type' => 'application/json', | ||
| 'X-Api-Key' => MY_API_KEY_CONSTANT, | ||
| ], | ||
| ], | ||
| ] ); | ||
| ``` | ||
|
|
||
| The configuration array passed to `from_array` is very flexible, so it's usually not necessary to extend `HttpDataSource`, but you can do so if you need to add custom behavior. | ||
| ## HttpDataSource configuration | ||
|
|
||
| ### **version**: number (required) | ||
|
|
||
| There is no built-in versioning logic, but a version number is required for best practice reasons. Changes to the data source could significantly affect [queries](query.md). Checking the data source version is a sensible defensive practice. | ||
|
|
||
| ### display_name: string (required) | ||
|
|
||
| The display name is used in the UI to identify your data source. | ||
|
|
||
| ### endpoint: string | ||
|
|
||
| This is the default endpoint for the data source and can save repeated use in queries. We would suggest putting the root API URL here and then manipulating it as necessary in individual [queries](query.md). | ||
|
|
||
| ### request_headers: array | ||
|
|
||
| Headers will be set according to the properties of the array. When providing authentication credentials, take care to keep them from appearing in code repositories. We strongly recommend using environment variables or other secure means for storage. | ||
|
|
||
| ## Additional parameters | ||
|
|
||
| You can add any additional parameters that are necessary for your data source. In our [Airtable example](../../example/airtable/events/register.php), you can see that we are setting values for the Airtable `base` and `table`. | ||
|
|
||
| Consider adding whatever configuration would be useful to queries. As an example, queries have an `endpoint` property. Our [Zip code example](../../example/rest-api/zip-code/register.php) sets the endpoint with a function: | ||
|
|
||
| ```php | ||
| $zipcode_query = HttpQuery::from_array( [ | ||
| 'data_source' => $zipcode_data_source, | ||
| 'endpoint' => function ( array $input_variables ) use ( $zipcode_data_source ): string { | ||
| return $zipcode_data_source->get_endpoint() . $input_variables['zip_code']; | ||
| }, | ||
| ]) | ||
| ``` | ||
|
|
||
| In this case the `data_source` has a built in `get_endpoint()` method. You could also retrieve the endpoint this way: | ||
|
|
||
| ```php | ||
| $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']; | ||
| }, | ||
| ]) | ||
| ``` | ||
|
|
||
| The goal with design was to provide you with flexibility you need to represent any data source. | ||
|
|
||
| ## Custom data sources | ||
|
|
||
| The configuration array passed to `from_array` is very flexible, so it's usually not necessary to extend `HttpDataSource`, but you can do so if you need to add custom behavior. | ||
|
|
||
| For APIs that use non-HTTP transports, you can also implement `DataSourceInterface` and provide methods that define reusable properties of your API. The actual implementation of your transport will need to be provided by a [custom query runner](./query-runner.md). | ||
|
|
||
| Here is a theoretical example of a data source for a WebDAV server: | ||
|
|
||
| ```php | ||
| class WebDavFilesDataSource implements DataSourceInterface { | ||
| public function get_display_name(): string { | ||
| return 'My WebDAV Files'; | ||
| } | ||
| public function get_display_name(): string { | ||
| return 'My WebDAV Files'; | ||
| } | ||
|
|
||
| public function get_image_url(): string { | ||
| return 'https://example.com/webdav-icon.png'; | ||
| } | ||
| public function get_image_url(): string { | ||
| return 'https://example.com/webdav-icon.png'; | ||
| } | ||
|
|
||
| public function get_webdav_root(): string { | ||
| return 'webdavs://webdav.example.com/'; | ||
| } | ||
| public function get_webdav_root(): string { | ||
| return 'webdavs://webdav.example.com/'; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ``` | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.