Skip to content

This plugin will sync your Passle posts and authors into your WordPress instance.

License

Notifications You must be signed in to change notification settings

passle/passle-sync-wordpress

Repository files navigation

Passle Sync for WordPress

Passle Sync is a plugin for Wordpress that syncs your Passle posts and authors into your Wordpress instance.

Get started with the section below, or jump straight to the API documentation.

A great example of how to use the plugin is our demo theme:

⚠️ Before you start

The plugins provided by Passle are designed to act as an example, and in some cases may be suitable to use as a starting point for your integration. They are not designed to be a ready-made solution and will often need further customisation to achieve your project goals. Please see our API and Remote Hosting documentation to support this integration process.

🚀 Getting started

Get started by installing the plugin and activating it.

Once the plugin is installed, admin users can access the settings under Settings > Passle Sync.

⚙️ Configuration

On the first tab of the plugin settings page, you will find the following configuration options:

Option Description
Passle API Key The API key generated in the Passle dashboard, used to fetch content from Passle.
Plugin API Key The API key Passle should use when calling the plugin webhooks after content is updated.
Passle Shortcodes A comma-separated list of the shortcodes of the Passles you want to sync content from.
Post Permalink Template The template that will be used for post permalink URLs. This needs to match what is set in the Passle backend.
Person Permalink Template The template that will be used for person permalink URLs. This needs to match what is set in the Passle backend.
Preview Permalink Template The template that will be used for preview permalink URLs. This needs to match what is set in the Passle backend.
Simulate Remote Hosting Whether or not to force the Passle API to use the domain and paths of the WordPress site.
Include Passle Posts on the Home Page Whether or not to include Passle posts in the WordPress query that generates the home page.
Include Passle Posts on the Tag Page Whether or not to include Passle posts in the WordPress query that generates the tag page.

📙 Basic Usage

Once the plugin has been configured correctly, posts and people can be synced using the Posts and People tabs under Settings > Passle Sync.

1. Fetch from API

First, the plugin has to fetch posts and authors from the Passle API. Use the Fetch Passle Posts and Fetch Passle People buttons to do so. Once the plugin has done the initial fetches from the API, the API responses will be cached, so if you reload the page, the posts and authors you have fetched will be remembered.

2. Sync to WordPress

To sync the posts and authors to WordPress, use the Sync All Posts and Sync All People buttons. This will create a new WordPress post for each post/author under a custom post type. Once all posts/authors have been synced, their statuses will update. Synced posts and authors can be viewed, but not edited, under the Passle Posts and Passle Authors menu items in the sidebar.

3. Webhooks

Whenever a post or author is updated through the Passle interface, the Passle backend will make a call to a webhook exposed by the plugin with the shortcode of the item that was updated, and the plugin will automatically re-sync that item.

4. Theme Templates

To display Passle posts and authors, you should create custom templates as part of your theme that, include the custom post type names, as described in the WordPress documentation. These templates should be called single-passle-post.php and single-passle-author.php.

This plugin provides the PasslePost and PassleAuthor helper classes, which you should use in your templates to access the custom Passle fields attached to a post or author more easily. They also ensure you're using the most up-to-date version of the data available.

For detailed documentation on the available classes, jump to the API documentation.

📰 Handling Featured Posts

Post meta is used to identify the featured post, on both the content hub page and the post page, with the keys post_is_featured_on_passle_page, and post_is_featured_on_post_page.

You can query for featured posts, or exclude them from a query, using one of these values as the meta query key parameter, and either EXISTS or NOT EXISTS as the meta query compare parameter.

An example of how to exclude the post featured on the content hub page from your main query can be found in our demo theme's functions.php.

An example of how to get the content hub featured post in order to display it separately from the rest of the posts can be found in our demo theme's index.php.

🔧 Requirements

  • Permalinks: Permalink Settings must be set to something other than 'Plain'.
  • TBD

👨‍💻 Development

Prerequisites
  • NPM
  • Composer
  • Development environment running a WordPress instance
    • Including a correctly set /etc/hosts config.

To build documentation, you will need to ensure extension=fileinfo is enabled in your php.ini. This extension is disabled by default on Windows.

Environment setup

To develop this plugin, first clone the repository:

git clone https://github.com/passle/passle-sync-wordpress

Next, install all dependencies and build the frontend with the following commands:

npm install
npm run init
Developing the frontend

To develop the frontend, use the watch script available in frontend/package.json.

Building the plugin zip

To build the plugin zip file, use the build:staging and build:production scripts available in package.json. This will install all dependencies (excluding Composer dev dependencies), build the frontend, and create a zip containing all necessary output files.

Generating docs

Documentation is automatically generated with phpDocumentor and phpDocumentor-markdown. To generate documentation, run the docs script available in package.json.

💬 Contributing

If you'd like to request a feature or report a bug, please create a GitHub Issue.

📜 License

The Passle Sync plugin is released under the terms of the MIT License.