From b7134f5ddfc93e2a4626cf3978187d0297328e15 Mon Sep 17 00:00:00 2001 From: Dharmesh Patel Date: Mon, 3 Oct 2022 12:22:43 +0530 Subject: [PATCH 1/2] documentation updates. --- .github/hookdoc-tmpl/README.md | 48 +-------------------- .github/hookdoc-tmpl/static/styles-10up.css | 2 +- README.md | 41 +----------------- hookdocs/canonical-url.md | 3 ++ hookdocs/meta.json | 19 +++++++- hookdocs/object-caching.md | 3 ++ hookdocs/post-content-type.md | 18 ++++++++ hookdocs/sophi-api-empty-response.md | 1 + hookdocs/wp-cli-commands.md | 43 ++++++++++++++++++ readme.txt | 39 +---------------- 10 files changed, 90 insertions(+), 127 deletions(-) create mode 100644 hookdocs/canonical-url.md create mode 100644 hookdocs/object-caching.md create mode 100644 hookdocs/post-content-type.md create mode 100644 hookdocs/sophi-api-empty-response.md create mode 100644 hookdocs/wp-cli-commands.md diff --git a/.github/hookdoc-tmpl/README.md b/.github/hookdoc-tmpl/README.md index 1beb6314..c6d4ef2f 100644 --- a/.github/hookdoc-tmpl/README.md +++ b/.github/hookdoc-tmpl/README.md @@ -1,4 +1,4 @@ -# Welcome to the Sophi for WordPress Plugin Developer Documentation +# Sophi for WordPress Developer Documentation This resource is generated documentation on actions and filters found in the Sophi for WordPress plugin, as well as some helpful tutorials on how to utilize those hooks. Use the sidebar to browse and navigate. @@ -32,52 +32,6 @@ If you're looking to contribute to or extend the Sophi for WordPress plugin, the - `composer lint` (lint PHP files) - `composer lint-fix` (lint PHP files and automatically correct coding standard violations) -### WP-CLI Commands - -### Sync content to Sophi Collector - -`$ wp sophi sync [--post_types=] [--limit=] [--per_page=] [--include=]` - -Sync all supported content to Sophi Collector, firing off update events for all of them. The expected use case with the Sophi for WordPress plugin is that someone will install it on an existing site and instead of having to manually update each piece of content to ensure that it makes it to the Collector, they can run this script to handle that all at once. - -#### Options - -**`--post_types=`** - -Post types to be processed. Comma separated for passing multiple post types. - -default: `false` -options: -- any post type name -- `false` - -**`--limit=`** - -Limit the amount of posts to be synced. - -default: `false` -options: -- `false`, no limit -- `N`, max number of posts to sync - -**`--per_page=`** - -Number of posts to process each batch. - -default: `false` -options: -- `false`, no limit -- `N`, max number of posts to sync each batch - -**`--include=`** - -Post IDs to process. Comma separated for passing multiple item. - -default: `false` -options: -- `false`, no limit -- `N`, Post IDs to sync - For more information about using Sophi for WordPress, please see the [Sophi website](https://sophi.io/). To report an issue with Sophi for WordPress or contribute back to the project, please visit the [GitHub repository](https://github.com/globeandmail/sophi-for-wordpress/). diff --git a/.github/hookdoc-tmpl/static/styles-10up.css b/.github/hookdoc-tmpl/static/styles-10up.css index c12454fd..94a37501 100644 --- a/.github/hookdoc-tmpl/static/styles-10up.css +++ b/.github/hookdoc-tmpl/static/styles-10up.css @@ -38,7 +38,7 @@ nav h3:nth-of-type(3) { } nav h3:nth-of-type(3):after { - content: 'Docs'; + content: 'Tutorials'; visibility: visible; position: absolute; left: 0; diff --git a/README.md b/README.md index 78c4cb0a..8adcdb6b 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ * [Using the plugin](#usage) * [Site Automation block](#site-automation-block) * [Query integration](#query-integration) -* [Documentation](#documentation) +* [Developer Documentation](#developer-documentation) * [FAQs](#frequently-asked-questions) * [Changelog](#changelog) * [Contributing](#contributing) @@ -132,44 +132,7 @@ While the above query integration works just fine, it has been observed on [Word `phpcs:ignore WordPressVIPMinimum.Functions.RestrictedFunctions.get_posts_get_posts` -### Post content type - -By default, Sophi for WordPress uses post format as the content type. This plugin uses `content_type` internally to distinguish between WordPress post type and Sophi type. - -Sophi accepts 4 types: article, video, audio, and image. The default type is `article`. Any other types that are not included above will be treated as `article`. - -If you're not using post format for content type, you can utilize `sophi_post_content_type` to set the content type. - -```php -add_filter( - 'sophi_post_content_type', - function( $type, $post ) { - // You logic here. - - return $new_type; - }, - 10, - 2 -); -``` - -### Canonical URL - -Sophi for WordPress uses `wp_get_canonical_url` function introduced in WordPress 4.6 to get the canonical URL for given post. The plugin compares this canonical URL to post permalink to set the `isCanonical` attribute. - -WordPress SEO (Yoast) canonical is supported out of the box. For other SEO plugins and custom implementations, [`get_canonical_url`](https://developer.wordpress.org/reference/functions/wp_get_canonical_url/) filter can be used to change the canonical URL. - -### Object caching - -Object caching is encouraged, as the plugin saves Sophi data as a transient. If you do not have object caching, then the data will be saved as a transient in the options table but note that these will eventually expire. - -The default caching period is five minutes. This can be modified with the `sophi_cache_duration` hook. - -### Sophi API empty response - -If the Sophi API returns an empty Post ID array, the plugin will result in a "no results" response. The `sophi_curated_post_list` filter can be used to modify the Sophi API response to allow manual posts to be injected into the final array previous to returning the filterable value from `posts_pre_query` (e.g., via a fallback method to inject posts that would be a good fit). - -## Documentation +## Developer Documentation Sophi for WordPress has an in-depth documentation site that details the available actions and filters found within the plugin, as well as some helpful tutorials on how to use those hooks. [Visit the developer docs ☞](https://globeandmail.github.io/sophi-for-wordpress/) diff --git a/hookdocs/canonical-url.md b/hookdocs/canonical-url.md new file mode 100644 index 00000000..9d386e3c --- /dev/null +++ b/hookdocs/canonical-url.md @@ -0,0 +1,3 @@ +Sophi for WordPress uses `wp_get_canonical_url` function introduced in WordPress 4.6 to get the canonical URL for given post. The plugin compares this canonical URL to post permalink to set the `isCanonical` attribute. + +WordPress SEO (Yoast) canonical is supported out of the box. For other SEO plugins and custom implementations, [`get_canonical_url`](https://developer.wordpress.org/reference/functions/wp_get_canonical_url/) filter can be used to change the canonical URL. diff --git a/hookdocs/meta.json b/hookdocs/meta.json index 4e9348c4..1fad56c9 100644 --- a/hookdocs/meta.json +++ b/hookdocs/meta.json @@ -6,6 +6,21 @@ "title": "Modify Post Data" }, "modify-tracking-data": { - "title": "Modify tracking data" - } + "title": "Modify tracking data" + }, + "wp-cli-commands": { + "title": "WP-CLI Commands" + }, + "post-content-type": { + "title": "Post Content Type" + }, + "canonical-url": { + "title": "Canonical URL" + }, + "object-caching": { + "title": "Object Caching" + }, + "sophi-api-empty-response": { + "title": "Sophi API Empty Response" + } } diff --git a/hookdocs/object-caching.md b/hookdocs/object-caching.md new file mode 100644 index 00000000..1ee1a647 --- /dev/null +++ b/hookdocs/object-caching.md @@ -0,0 +1,3 @@ +Object caching is encouraged, as the plugin saves Sophi data as a transient. If you do not have object caching, then the data will be saved as a transient in the options table but note that these will eventually expire. + +The default caching period is five minutes. This can be modified with the `sophi_cache_duration` hook. diff --git a/hookdocs/post-content-type.md b/hookdocs/post-content-type.md new file mode 100644 index 00000000..d1a47148 --- /dev/null +++ b/hookdocs/post-content-type.md @@ -0,0 +1,18 @@ +By default, Sophi for WordPress uses post format as the content type. This plugin uses `content_type` internally to distinguish between WordPress post type and Sophi type. + +Sophi accepts 4 types: article, video, audio, and image. The default type is `article`. Any other types that are not included above will be treated as `article`. + +If you're not using post format for content type, you can utilize `sophi_post_content_type` to set the content type. + +```php +add_filter( + 'sophi_post_content_type', + function( $type, $post ) { + // You logic here. + + return $new_type; + }, + 10, + 2 +); +``` diff --git a/hookdocs/sophi-api-empty-response.md b/hookdocs/sophi-api-empty-response.md new file mode 100644 index 00000000..ae66bfa6 --- /dev/null +++ b/hookdocs/sophi-api-empty-response.md @@ -0,0 +1 @@ +If the Sophi API returns an empty Post ID array, the plugin will result in a "no results" response. The `sophi_curated_post_list` filter can be used to modify the Sophi API response to allow manual posts to be injected into the final array previous to returning the filterable value from `posts_pre_query` (e.g., via a fallback method to inject posts that would be a good fit). diff --git a/hookdocs/wp-cli-commands.md b/hookdocs/wp-cli-commands.md new file mode 100644 index 00000000..df3ef4ed --- /dev/null +++ b/hookdocs/wp-cli-commands.md @@ -0,0 +1,43 @@ +### Sync content to Sophi Collector + +`$ wp sophi sync [--post_types=] [--limit=] [--per_page=] [--include=]` + +Sync all supported content to Sophi Collector, firing off update events for all of them. The expected use case with the Sophi for WordPress plugin is that someone will install it on an existing site and instead of having to manually update each piece of content to ensure that it makes it to the Collector, they can run this script to handle that all at once. + +#### Options + +**`--post_types=`** + +Post types to be processed. Comma separated for passing multiple post types. + +default: `false` +options: +- any post type name +- `false` + +**`--limit=`** + +Limit the amount of posts to be synced. + +default: `false` +options: +- `false`, no limit +- `N`, max number of posts to sync + +**`--per_page=`** + +Number of posts to process each batch. + +default: `false` +options: +- `false`, no limit +- `N`, max number of posts to sync each batch + +**`--include=`** + +Post IDs to process. Comma separated for passing multiple item. + +default: `false` +options: +- `false`, no limit +- `N`, Post IDs to sync diff --git a/readme.txt b/readme.txt index 12b2152b..f2933eca 100644 --- a/readme.txt +++ b/readme.txt @@ -115,44 +115,7 @@ While the above query integration works just fine, it has been observed on [Word `phpcs:ignore WordPressVIPMinimum.Functions.RestrictedFunctions.get_posts_get_posts` -= Post content type = - -By default, Sophi for WordPress uses post format as the content type. This plugin uses `content_type` internally to distinguish between WordPress post type and Sophi type. - -Sophi accepts 4 types: article, video, audio, and image. The default type is `article`. Any other types that are not included above will be treated as `article`. - -If you're not using post format for content type, you can utilize `sophi_post_content_type` to set the content type. - -` -add_filter( - 'sophi_post_content_type', - function( $type, $post ) { - // You logic here. - - return $new_type; - }, - 10, - 2 -); -` - -= Canonical URL = - -Sophi for WordPress uses `wp_get_canonical_url` function introduced in WordPress 4.6 to get the canonical URL for given post. The plugin compares this canonical URL to post permalink to set the `isCanonical` attribute. - -WordPress SEO (Yoast) canonical is supported out of the box. For other SEO plugins and custom implementations, [`get_canonical_url`](https://developer.wordpress.org/reference/functions/wp_get_canonical_url/) filter can be used to change the canonical URL. - -= Object caching = - -Object caching is encouraged, as the plugin saves Sophi data as a transient. If you do not have object caching, then the data will be saved as a transient in the options table but note that these will eventually expire. - -The default caching period is five minutes. This can be modified with the `sophi_cache_duration` hook. - -= Sophi API empty response = - -If the Sophi API returns an empty Post ID array, the plugin will result in a "no results" response. The `sophi_curated_post_list` filter can be used to modify the Sophi API response to allow manual posts to be injected into the final array previous to returning the filterable value from `posts_pre_query` (e.g., via a fallback method to inject posts that would be a good fit). - -== Documentation == +== Developer Documentation == Sophi for WordPress has an in-depth documentation site that details the available actions and filters found within the plugin. [Visit the developer docs ☞](https://globeandmail.github.io/sophi-for-wordpress/) From a3caf2a922224fde7dfe691700eefc6a603b8cbe Mon Sep 17 00:00:00 2001 From: Dharmesh Patel Date: Mon, 3 Oct 2022 12:26:42 +0530 Subject: [PATCH 2/2] Headless integration note. --- hookdocs/headless-integration.md | 1 + hookdocs/meta.json | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 hookdocs/headless-integration.md diff --git a/hookdocs/headless-integration.md b/hookdocs/headless-integration.md new file mode 100644 index 00000000..70559957 --- /dev/null +++ b/hookdocs/headless-integration.md @@ -0,0 +1 @@ +Headless WordPress setups will want to ensure they handle the JavaScript and AMP tracking needed for Sophi as well as the direct calls to Sophi Curator to receive Post IDs for site automation functionality within the frontend codebase. The Sophi plugin otherwise handles both these functions for non-headless setups, but will prove to be additional custom work needed for any site using a headless setup. diff --git a/hookdocs/meta.json b/hookdocs/meta.json index 1fad56c9..bb6d5a98 100644 --- a/hookdocs/meta.json +++ b/hookdocs/meta.json @@ -11,6 +11,9 @@ "wp-cli-commands": { "title": "WP-CLI Commands" }, + "headless-integration": { + "title": "Headless Integration" + }, "post-content-type": { "title": "Post Content Type" },