Merge pull request #318 from globeandmail/feature/tutorials

Add tutorials to our documentation site

.distignore

@@ -4,6 +4,7 @@
 /.wordpress-org
 /assets
 /config
+/hookdocs
 /node_modules
 /tests
 # DO NOT EXCLUDE /vendor

.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.
 

.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;
 }

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
 

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)?$"
@@ -12,6 +13,9 @@
       "node_modules/wp-hookdoc/plugin",
       "plugins/markdown"
     ],
+    "markdown": {
+      "idInHeadings": true
+    },
     "templates":  {
       "default": {
         "layoutFile": "./.github/hookdoc-tmpl/layout.tmpl",

hookdocs/change-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. 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
+
+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' );
+```

hookdocs/meta.json

@@ -0,0 +1,8 @@
+{
+    "change-supported-post-types": {
+        "title": "Change Supported Post Types"
+    },
+    "modify-post-data": {
+        "title": "Modify Post Data"
+    }
+}

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. 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
+
+### 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' );
+```