From 063e8bc52344262ebfbaf18719364d19194e3b26 Mon Sep 17 00:00:00 2001 From: ashfame Date: Fri, 3 Jan 2025 22:25:06 +0400 Subject: [PATCH 1/4] add documentation on integrating with data liberation --- EXTEND.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 EXTEND.md diff --git a/EXTEND.md b/EXTEND.md new file mode 100644 index 00000000..d4190eee --- /dev/null +++ b/EXTEND.md @@ -0,0 +1,94 @@ +# Receive Liberated Data + +## Definitions + +Each identified piece of content is referred to as +a [subject](src/plugin/class-subject.php), and hence has +a [subject type](src/plugin/enum-subject-type.php). + +The act of extracting data is referred to as `liberation` and the act of using the extracted raw data to convert into a +usable form is referred to as `transformation` throughout the documentation and code. + +While liberating data, we always store the raw data that we are handling in hopes of running a better transformation in +the future or any third-party plugin to transform the data upon installation of their plugin. + +## Storage Architecture + +Try WordPress stores all liberated data in a custom post type called `liberated_data`, exposed via a constant: +`\DotOrg\TryWordPress\Engine::STORAGE_POST_TYPE`. + +We maintain references between the source data and transformed output using two post meta keys: + +- `_data_liberation_source`: Points to the source content (exposed via + `\DotOrg\TryWordPress\Transformer::META_KEY_LIBERATED_SOURCE`) +- `_data_liberation_output`: Points to the transformed output (exposed via + `\DotOrg\TryWordPress\Transformer::META_KEY_LIBERATED_OUTPUT`) + +This two-way reference allows both Try WordPress and your plugin to track relationships between original content and +transformed posts. + +However, we recommend integrating using our hook below: + +## Integration + +If your plugin is available during data liberation, it can register handlers for the desired subject types and run its +own transformations. + +You can either use `Ops::handle()` to register a handler for your desired subject type or use our WordPress hook +`data_liberated_{$subject_type}` action hook which would invoke `Ops::handle()` on your behalf. You must return the post +ID of your transformed post from your handler for the preview to show up correctly. + +In your handler, you get access to the raw data through an instance of the Subject class. + +The [Subject class](src/plugin/class-subject.php) provides a clean API to access raw data and existing transformed +output: + +### Code examples: + +For example, to transform "product" (subject type) data into your custom product post type, you would do this: + +`\DotOrg\TryWordPress\Ops::handle( SubjectType::PRODUCT->value', 'myplugin_unique_slug_product_handler' );` + +OR + +`add_action( 'data_liberated_product', 'myplugin_unique_slug_product_handler' );` + +where your handler function would look something like this: + +```php +function myplugin_unique_slug_product_handler( $subject ) { + // process raw data + $title = $subject->title; + $date = $subject->date; + $content = $subject->content; + + // access the entire HTML source of page or its URL + // $subject->source_html + // $subject->source_url + + // Create a product in your custom post type + $my_product_id = wp_insert_post( array( + 'post_type' => 'my_product_type', + 'post_title' => $title, + 'post_date' => $date, + 'post_content' => $content, + 'post_status' => 'publish', + ) ); + + return $my_product_id; // would be used for preview +} +``` + +## Best Practices + +1. Always use the Subject class's public API to access liberated data. Don't rely on internal implementation details. + +## Need Help? + +Open an issue on our [GitHub repository](https://github.com/WordPress/try-wordpress) if you: + +- Need additional integration points +- Have a use case not currently covered +- Want to discuss your integration approach + +We actively work with plugin authors to ensure Try WordPress meets real-world needs. From 5a75a627b544ba7695022bfe1c2cd197179ca4ee Mon Sep 17 00:00:00 2001 From: ashfame Date: Tue, 7 Jan 2025 15:20:27 +0400 Subject: [PATCH 2/4] move storage architecture section to the bottom for now --- EXTEND.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/EXTEND.md b/EXTEND.md index d4190eee..375860ea 100644 --- a/EXTEND.md +++ b/EXTEND.md @@ -12,23 +12,6 @@ usable form is referred to as `transformation` throughout the documentation and While liberating data, we always store the raw data that we are handling in hopes of running a better transformation in the future or any third-party plugin to transform the data upon installation of their plugin. -## Storage Architecture - -Try WordPress stores all liberated data in a custom post type called `liberated_data`, exposed via a constant: -`\DotOrg\TryWordPress\Engine::STORAGE_POST_TYPE`. - -We maintain references between the source data and transformed output using two post meta keys: - -- `_data_liberation_source`: Points to the source content (exposed via - `\DotOrg\TryWordPress\Transformer::META_KEY_LIBERATED_SOURCE`) -- `_data_liberation_output`: Points to the transformed output (exposed via - `\DotOrg\TryWordPress\Transformer::META_KEY_LIBERATED_OUTPUT`) - -This two-way reference allows both Try WordPress and your plugin to track relationships between original content and -transformed posts. - -However, we recommend integrating using our hook below: - ## Integration If your plugin is available during data liberation, it can register handlers for the desired subject types and run its @@ -83,6 +66,21 @@ function myplugin_unique_slug_product_handler( $subject ) { 1. Always use the Subject class's public API to access liberated data. Don't rely on internal implementation details. +## Storage Architecture + +Try WordPress stores all liberated data in a custom post type called `liberated_data`, exposed via a constant: +`\DotOrg\TryWordPress\Engine::STORAGE_POST_TYPE`. + +We maintain references between the source data and transformed output using two post meta keys: + +- `_data_liberation_source`: Points to the source content (exposed via + `\DotOrg\TryWordPress\Transformer::META_KEY_LIBERATED_SOURCE`) +- `_data_liberation_output`: Points to the transformed output (exposed via + `\DotOrg\TryWordPress\Transformer::META_KEY_LIBERATED_OUTPUT`) + +This two-way reference allows both Try WordPress and your plugin to track relationships between original content and +transformed posts. + ## Need Help? Open an issue on our [GitHub repository](https://github.com/WordPress/try-wordpress) if you: From 42f5b4f8402344794a8d48539add7a7bbab1980e Mon Sep 17 00:00:00 2001 From: ashfame Date: Tue, 7 Jan 2025 15:21:27 +0400 Subject: [PATCH 3/4] fix code example for non-WP-y api --- EXTEND.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/EXTEND.md b/EXTEND.md index 375860ea..1c1ea37f 100644 --- a/EXTEND.md +++ b/EXTEND.md @@ -30,7 +30,16 @@ output: For example, to transform "product" (subject type) data into your custom product post type, you would do this: -`\DotOrg\TryWordPress\Ops::handle( SubjectType::PRODUCT->value', 'myplugin_unique_slug_product_handler' );` +```php +\DotOrg\TryWordPress\Ops::handle( + SubjectType::PRODUCT->value, + array( + 'slug' => 'myplugin_unique_slug', + 'description' => 'myplugin handling products', + ), + 'myplugin_unique_slug_product_handler' +); +``` OR From 576b791346438a174a172934e89e4898cbb94bed Mon Sep 17 00:00:00 2001 From: ashfame Date: Tue, 7 Jan 2025 16:38:57 +0400 Subject: [PATCH 4/4] only advertise WP-y API in docs --- EXTEND.md | 24 +++--------------------- 1 file changed, 3 insertions(+), 21 deletions(-) diff --git a/EXTEND.md b/EXTEND.md index 1c1ea37f..b9dfbff5 100644 --- a/EXTEND.md +++ b/EXTEND.md @@ -17,37 +17,19 @@ the future or any third-party plugin to transform the data upon installation of If your plugin is available during data liberation, it can register handlers for the desired subject types and run its own transformations. -You can either use `Ops::handle()` to register a handler for your desired subject type or use our WordPress hook -`data_liberated_{$subject_type}` action hook which would invoke `Ops::handle()` on your behalf. You must return the post -ID of your transformed post from your handler for the preview to show up correctly. - +You can use `data_liberated_{$subject_type}` action hook to run your transformation. In your handler, you get access to the raw data through an instance of the Subject class. The [Subject class](src/plugin/class-subject.php) provides a clean API to access raw data and existing transformed output: -### Code examples: +### Code example: For example, to transform "product" (subject type) data into your custom product post type, you would do this: ```php -\DotOrg\TryWordPress\Ops::handle( - SubjectType::PRODUCT->value, - array( - 'slug' => 'myplugin_unique_slug', - 'description' => 'myplugin handling products', - ), - 'myplugin_unique_slug_product_handler' -); -``` - -OR +add_action( 'data_liberated_product', 'myplugin_unique_slug_product_handler' ); -`add_action( 'data_liberated_product', 'myplugin_unique_slug_product_handler' );` - -where your handler function would look something like this: - -```php function myplugin_unique_slug_product_handler( $subject ) { // process raw data $title = $subject->title;