From 6c4473a2f101718b740fce326044f2822132eba7 Mon Sep 17 00:00:00 2001 From: Darin Kotter Date: Tue, 9 Aug 2022 13:45:49 -0600 Subject: [PATCH 1/7] Add support for tutorials in our hookdocs --- .distignore | 1 + .github/hookdoc-tmpl/static/styles-10up.css | 31 ++++++++++++++++++++- hookdoc-conf.json | 3 +- hookdocs/meta.json | 5 ++++ 4 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 hookdocs/meta.json diff --git a/.distignore b/.distignore index 8885bd9e..bfbb01fd 100644 --- a/.distignore +++ b/.distignore @@ -4,6 +4,7 @@ /.wordpress-org /assets /config +/hookdocs /node_modules /tests # DO NOT EXCLUDE /vendor diff --git a/.github/hookdoc-tmpl/static/styles-10up.css b/.github/hookdoc-tmpl/static/styles-10up.css index e477c3b4..c12454fd 100644 --- a/.github/hookdoc-tmpl/static/styles-10up.css +++ b/.github/hookdoc-tmpl/static/styles-10up.css @@ -18,6 +18,36 @@ h1.page-title { margin-top: .5em; } +nav { + display: flex; + flex-direction: column; +} + +nav * { + order: 4; +} + +nav h2 { + order: 1; +} + +nav h3:nth-of-type(3) { + order: 2; + visibility: hidden; + position: relative; +} + +nav h3:nth-of-type(3):after { + content: 'Docs'; + visibility: visible; + position: absolute; + left: 0; +} + +nav ul:nth-of-type(3) { + order: 3; +} + nav ul { font-size: 1.2rem; } @@ -94,5 +124,4 @@ footer { .prettyprint code { padding: 2px 10px; line-height: 16px; - height: 16px; } diff --git a/hookdoc-conf.json b/hookdoc-conf.json index d9947202..25acbe85 100644 --- a/hookdoc-conf.json +++ b/hookdoc-conf.json @@ -3,7 +3,8 @@ "destination": "docs", "template": "node_modules/wp-hookdoc/template", "recurse": true, - "readme": "./.github/hookdoc-tmpl/README.md" + "readme": "./.github/hookdoc-tmpl/README.md", + "tutorials": "./hookdocs" }, "source": { "includePattern": ".+\\.(php|inc)?$" diff --git a/hookdocs/meta.json b/hookdocs/meta.json new file mode 100644 index 00000000..5296a5ae --- /dev/null +++ b/hookdocs/meta.json @@ -0,0 +1,5 @@ +{ + "supported-post-types": { + "title": "Change Supported Post Types" + } +} From f65c5af13b1ab7b86d5cb0591b6faed4bb22b5ae Mon Sep 17 00:00:00 2001 From: Darin Kotter Date: Tue, 9 Aug 2022 13:50:57 -0600 Subject: [PATCH 2/7] Add tutorial for changing the supported post types --- hookdocs/supported-post-types.md | 72 ++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 hookdocs/supported-post-types.md diff --git a/hookdocs/supported-post-types.md b/hookdocs/supported-post-types.md new file mode 100644 index 00000000..182b6da1 --- /dev/null +++ b/hookdocs/supported-post-types.md @@ -0,0 +1,72 @@ +By default, the Sophi for WordPress plugin only adds support for the standard `post` and `page` post types. This value is passed through a custom filter ([`sophi_supported_post_types`]{@link sophi_supported_post_types}), which allows you to customize those values. See below for a few examples of how to utilize this filter. + +A few things to note: + +1. Where you add this code will depend on your individual setup. Often it makes sense to drop these in your main `functions.php` file +2. The examples here are set up to support any other code that may be using the same filters. If you're sure that's not the case, the code can be simplified as needed + +### Remove a default post type + +The `post` and `page` post types are supported by default. If you want to remove the `page` post type, for instance, you can do the following: + +```php +/** + * Change the post types Sophi supports. + * + * Remove the `page` post type from being supported. + * + * @param array $post_types Default supported post types. + * @return array + */ +function custom_prefix_sophi_supported_post_types( $post_types = [] ) { + $post_types_to_remove = [ 'page' ]; + return array_diff( $post_types, $post_types_to_remove ); +} +add_filter( 'sophi_supported_post_types', 'custom_prefix_sophi_supported_post_types' ); +``` + +### Add a new post type to the default list + +If you have a custom post type that you want to support, along with the `post` and `page` post types, you can do the following: + +```php +/** + * Change the post types Sophi supports. + * + * Add our custom `video` post type while still + * supporting the default post types. + * + * @param array $post_types Default supported post types. + * @return array + */ +function custom_prefix_sophi_supported_post_types( $post_types = [] ) { + $post_types_to_add = [ 'video' ]; + return array_merge( $post_types, $post_types_to_add ); +} +add_filter( 'sophi_supported_post_types', 'custom_prefix_sophi_supported_post_types' ); +``` + +### Replace default post types with custom ones + +If you only want to support custom post types and not the defaults, you can do the following: + +```php +/** + * Change the post types Sophi supports. + * + * Remove the `post` and `page` post types + * and add our custom video and gallery post types. + * + * @param array $post_types Default supported post types. + * @return array + */ +function custom_prefix_sophi_supported_post_types( $post_types = [] ) { + $post_types_to_remove = [ 'post', 'page' ]; + $post_types_to_add = [ 'video', 'gallery' ]; + return array_merge( + array_diff( $post_types, $post_types_to_remove ), + $post_types_to_add + ); +} +add_filter( 'sophi_supported_post_types', 'custom_prefix_sophi_supported_post_types' ); +``` From 13d660f3af1dffe21444ee97e46a9f90a8b0f078 Mon Sep 17 00:00:00 2001 From: Darin Kotter Date: Tue, 9 Aug 2022 14:33:20 -0600 Subject: [PATCH 3/7] Add tutorial for changing the data we send to Sophi --- hookdocs/meta.json | 3 + hookdocs/modify-post-data.md | 125 +++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 hookdocs/modify-post-data.md diff --git a/hookdocs/meta.json b/hookdocs/meta.json index 5296a5ae..e4269765 100644 --- a/hookdocs/meta.json +++ b/hookdocs/meta.json @@ -1,5 +1,8 @@ { "supported-post-types": { "title": "Change Supported Post Types" + }, + "modify-post-data": { + "title": "Modify Post Data" } } diff --git a/hookdocs/modify-post-data.md b/hookdocs/modify-post-data.md new file mode 100644 index 00000000..e18e9e00 --- /dev/null +++ b/hookdocs/modify-post-data.md @@ -0,0 +1,125 @@ +When a supported post item is saved (whether a publish, update, delete or unpublish event), data about that item is synced over to the Sophi service. While the intention of this plugin is to accurately capture all the necessary information automatically, there are some use cases that will need to modify this data prior to it being synced. + +The data about each supported post item is passed through a custom filter ([`sophi_post_data`]{@link sophi_post_data}), which allows you to customize this information. See below for a few examples of how to utilize this filter. + +A few things to note: + +1. Where you add this code will depend on your individual setup. Often it makes sense to drop these in your main `functions.php` file +2. If data is changed or added, you may need to coordinate with the Sophi.io team to ensure content is appropriately received +3. Data that is changed needs to stay the same type as it is currently. For instance, if something is currently an array, it should stay an array + +### Replace existing data + +One of the fields that is sent is called `byline`. This is currently set to the author display name. If you need to change this to something else, like the author's nickname, you can do the following: + +```php +/** + * Change the post data we send to Sophi. + * + * Update the byline value to use the author's nickname. + * + * @param array $post_data Formatted post data. + * @return array + */ +function custom_prefix_sophi_post_data( $post_data = [] ) { + // Ensure we have a proper post object. + $post = get_post( (int) $post_data['contentId'] ); + if ( ! $post || ! is_a( $post, 'WP_Post' ) ) { + return $post_data; + } + + // This field needs to be an array, even though it only has one value. + $post_data['byline'] = [ get_the_author_meta( 'nickname', $post->post_author ) ]; + + return $post_data; +} +add_filter( 'sophi_post_data', 'custom_prefix_sophi_post_data' ); +``` + +Another field that is sent is called `isSponsored`. This is currently hardcoded to `false`. If you need to change this to `true`, you can do the following: + +```php +/** + * Change the post data we send to Sophi. + * + * Update the isSponsored value to true. + * + * @param array $post_data Formatted post data. + * @return array + */ +function custom_prefix_sophi_post_data( $post_data = [] ) { + // Ensure we have a proper post object. + $post = get_post( (int) $post_data['contentId'] ); + if ( ! $post || ! is_a( $post, 'WP_Post' ) ) { + return $post_data; + } + + $post_data['isSponsored'] = true; + + return $post_data; +} +add_filter( 'sophi_post_data', 'custom_prefix_sophi_post_data' ); +``` + +### Modify existing data + +One of the fields that is sent is called `allSections`. This is currently set to an array of category paths. If you want to add additional taxonomy paths to this value, you can do the following: + +```php +/** + * Change the post data we send to Sophi. + * + * Add more paths to the allSections value. + * + * @param array $post_data Formatted post data. + * @return array + */ +function custom_prefix_sophi_post_data( $post_data = [] ) { + // Ensure we have a proper post object. + $post = get_post( (int) $post_data['contentId'] ); + if ( ! $post || ! is_a( $post, 'WP_Post' ) ) { + return $post_data; + } + + $current_sections = $post_data['allSections']; + + // This custom function is not provided here but this would be similar to the + // SophiWP\Utils\get_post_categories_paths utility function + $new_sections = custom_prefix_get_taxonomy_paths( $post->ID, 'custom_taxonomy_slug' ); + + // Add our new sections to the end of our existing sections. + $post_data['allSections'] = array_merge( $current_sections, $new_sections ); + + return $post_data; +} +add_filter( 'sophi_post_data', 'custom_prefix_sophi_post_data' ); +``` + +### Add new data + +If you need to add an entirely new field, that can be done as well: + +```php +/** + * Change the post data we send to Sophi. + * + * Add a new field called videoIds. + * + * @param array $post_data Formatted post data. + * @return array + */ +function custom_prefix_sophi_post_data( $post_data = [] ) { + // Ensure we have a proper post object. + $post = get_post( (int) $post_data['contentId'] ); + if ( ! $post || ! is_a( $post, 'WP_Post' ) ) { + return $post_data; + } + + // This custom function is not provided here but this would + // run some logic to get video IDs from the post object. + $post_data['videoIds'] = custom_prefix_get_video_ids( $post->ID ); + + return $post_data; +} +add_filter( 'sophi_post_data', 'custom_prefix_sophi_post_data' ); +``` From 300ee8fc618afd7a0ce127b4ec33feb4c2732fc3 Mon Sep 17 00:00:00 2001 From: Darin Kotter Date: Tue, 9 Aug 2022 14:34:35 -0600 Subject: [PATCH 4/7] Ensure headings have IDs, so we can link directly there. Rename a file to make it show first --- hookdoc-conf.json | 3 +++ ...{supported-post-types.md => change-supported-post-types.md} | 0 hookdocs/meta.json | 2 +- 3 files changed, 4 insertions(+), 1 deletion(-) rename hookdocs/{supported-post-types.md => change-supported-post-types.md} (100%) diff --git a/hookdoc-conf.json b/hookdoc-conf.json index 25acbe85..705a8281 100644 --- a/hookdoc-conf.json +++ b/hookdoc-conf.json @@ -13,6 +13,9 @@ "node_modules/wp-hookdoc/plugin", "plugins/markdown" ], + "markdown": { + "idInHeadings": true + }, "templates": { "default": { "layoutFile": "./.github/hookdoc-tmpl/layout.tmpl", diff --git a/hookdocs/supported-post-types.md b/hookdocs/change-supported-post-types.md similarity index 100% rename from hookdocs/supported-post-types.md rename to hookdocs/change-supported-post-types.md diff --git a/hookdocs/meta.json b/hookdocs/meta.json index e4269765..c589093d 100644 --- a/hookdocs/meta.json +++ b/hookdocs/meta.json @@ -1,5 +1,5 @@ { - "supported-post-types": { + "change-supported-post-types": { "title": "Change Supported Post Types" }, "modify-post-data": { From 05bcb29e93a0da3869f2a73da338588348b2b403 Mon Sep 17 00:00:00 2001 From: Darin Kotter Date: Tue, 9 Aug 2022 14:41:52 -0600 Subject: [PATCH 5/7] Add notes to the READMEs about the new tutorials --- .github/hookdoc-tmpl/README.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/hookdoc-tmpl/README.md b/.github/hookdoc-tmpl/README.md index de85275e..1beb6314 100644 --- a/.github/hookdoc-tmpl/README.md +++ b/.github/hookdoc-tmpl/README.md @@ -1,6 +1,6 @@ # Welcome to the Sophi for WordPress Plugin Developer Documentation -This resource is generated documentation on actions and filters found in the Sophi for WordPress plugin. Use the sidebar to browse and navigate. +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. If you're looking to contribute to or extend the Sophi for WordPress plugin, then the following sub-sections are things to be aware of in terms of how the plugin is architected. diff --git a/README.md b/README.md index c5664986..78c4cb0a 100644 --- a/README.md +++ b/README.md @@ -171,7 +171,7 @@ If the Sophi API returns an empty Post ID array, the plugin will result in a "no ## 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/) +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/) ## Debugging From b90dd3b3667f6ed4715225c8f245fcc6a47c1877 Mon Sep 17 00:00:00 2001 From: Darin Kotter Date: Wed, 10 Aug 2022 10:03:39 -0600 Subject: [PATCH 6/7] Text updates --- hookdocs/change-supported-post-types.md | 2 +- hookdocs/modify-post-data.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/hookdocs/change-supported-post-types.md b/hookdocs/change-supported-post-types.md index 182b6da1..d97d5abd 100644 --- a/hookdocs/change-supported-post-types.md +++ b/hookdocs/change-supported-post-types.md @@ -2,7 +2,7 @@ By default, the Sophi for WordPress plugin only adds support for the standard `p A few things to note: -1. Where you add this code will depend on your individual setup. Often it makes sense to drop these in your main `functions.php` file +1. Where you add this code will depend on your individual setup. If you are using a custom theme, you can add these to your main `functions.php` file. If you're using a public theme, you might want to create a custom plugin to hold these code changes, so you don't lose those changes when you update your theme 2. The examples here are set up to support any other code that may be using the same filters. If you're sure that's not the case, the code can be simplified as needed ### Remove a default post type diff --git a/hookdocs/modify-post-data.md b/hookdocs/modify-post-data.md index e18e9e00..0629f9e6 100644 --- a/hookdocs/modify-post-data.md +++ b/hookdocs/modify-post-data.md @@ -4,7 +4,7 @@ The data about each supported post item is passed through a custom filter ([`sop A few things to note: -1. Where you add this code will depend on your individual setup. Often it makes sense to drop these in your main `functions.php` file +1. Where you add this code will depend on your individual setup. If you are using a custom theme, you can add these to your main `functions.php` file. If you're using a public theme, you might want to create a custom plugin to hold these code changes, so you don't lose those changes when you update your theme 2. If data is changed or added, you may need to coordinate with the Sophi.io team to ensure content is appropriately received 3. Data that is changed needs to stay the same type as it is currently. For instance, if something is currently an array, it should stay an array From 54785bf99b4e881363cda708c5dd4241e5858da4 Mon Sep 17 00:00:00 2001 From: Darin Kotter Date: Wed, 10 Aug 2022 10:04:05 -0600 Subject: [PATCH 7/7] Remove space --- hookdocs/change-supported-post-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hookdocs/change-supported-post-types.md b/hookdocs/change-supported-post-types.md index d97d5abd..83112ca3 100644 --- a/hookdocs/change-supported-post-types.md +++ b/hookdocs/change-supported-post-types.md @@ -2,7 +2,7 @@ By default, the Sophi for WordPress plugin only adds support for the standard `p A few things to note: -1. Where you add this code will depend on your individual setup. If you are using a custom theme, you can add these to your main `functions.php` file. If you're using a public theme, you might want to create a custom plugin to hold these code changes, so you don't lose those changes when you update your theme +1. Where you add this code will depend on your individual setup. If you are using a custom theme, you can add these to your main `functions.php` file. If you're using a public theme, you might want to create a custom plugin to hold these code changes, so you don't lose those changes when you update your theme 2. The examples here are set up to support any other code that may be using the same filters. If you're sure that's not the case, the code can be simplified as needed ### Remove a default post type