Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Developer Documentation updates. #332

Merged
merged 2 commits into from
Oct 3, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 1 addition & 47 deletions .github/hookdoc-tmpl/README.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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=<string>] [--limit=<number>] [--per_page=<number>] [--include=<number>]`

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=<string>`**

Post types to be processed. Comma separated for passing multiple post types.

default: `false`
options:
- any post type name
- `false`

**`--limit=<number>`**

Limit the amount of posts to be synced.

default: `false`
options:
- `false`, no limit
- `N`, max number of posts to sync

**`--per_page=<number>`**

Number of posts to process each batch.

default: `false`
options:
- `false`, no limit
- `N`, max number of posts to sync each batch

**`--include=<number>`**

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/).
Expand Down
2 changes: 1 addition & 1 deletion .github/hookdoc-tmpl/static/styles-10up.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
41 changes: 2 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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/)

Expand Down
3 changes: 3 additions & 0 deletions hookdocs/canonical-url.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions hookdocs/headless-integration.md
Original file line number Diff line number Diff line change
@@ -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.
22 changes: 20 additions & 2 deletions hookdocs/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,24 @@
"title": "Modify Post Data"
},
"modify-tracking-data": {
"title": "Modify tracking data"
}
"title": "Modify tracking data"
},
"wp-cli-commands": {
"title": "WP-CLI Commands"
},
"headless-integration": {
"title": "Headless Integration"
},
"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"
}
}
3 changes: 3 additions & 0 deletions hookdocs/object-caching.md
Original file line number Diff line number Diff line change
@@ -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.
18 changes: 18 additions & 0 deletions hookdocs/post-content-type.md
Original file line number Diff line number Diff line change
@@ -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
);
```
1 change: 1 addition & 0 deletions hookdocs/sophi-api-empty-response.md
Original file line number Diff line number Diff line change
@@ -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).
43 changes: 43 additions & 0 deletions hookdocs/wp-cli-commands.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
### Sync content to Sophi Collector

`$ wp sophi sync [--post_types=<string>] [--limit=<number>] [--per_page=<number>] [--include=<number>]`

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=<string>`**

Post types to be processed. Comma separated for passing multiple post types.

default: `false`
options:
- any post type name
- `false`

**`--limit=<number>`**

Limit the amount of posts to be synced.

default: `false`
options:
- `false`, no limit
- `N`, max number of posts to sync

**`--per_page=<number>`**

Number of posts to process each batch.

default: `false`
options:
- `false`, no limit
- `N`, max number of posts to sync each batch

**`--include=<number>`**

Post IDs to process. Comma separated for passing multiple item.

default: `false`
options:
- `false`, no limit
- `N`, Post IDs to sync
39 changes: 1 addition & 38 deletions readme.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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/)

Expand Down