WP Discourse plugin installation and setup

wordpress

(Simon Cossar) #1

Installation

From your WordPress dashboard

  1. Visit ‘Plugins > Add New’
  2. Search for ‘WP Discourse’
  3. Activate WP Discourse from your Plugins page

From wordpress.org

  1. Download WP Discourse
  2. Upload the ‘wp-discourse’ directory to your ‘/wp-content/plugins/’ directory
  3. Activate WP Discourse from your Plugins page

With Composer

If you’re using Composer to manage WordPress, add WP-Discourse to your project’s dependencies. Run:

composer require discourse/wp-discourse ~1.6.1

Or manually add it to your composer.json:

{
  "require": {
    "php": ">=5.4.0",
    "discourse/wp-discourse": "~1.6.1"
  }
}

Plugin setup

TL;DR install and activate the plugin. Click on the ‘Discourse’ menu item. Read the setting’s descriptions and configure them as you like. Don’t enable SSO unless you have a good reason to do it.

Connection

When you activate the plugin a ‘Discourse’ menu item will be added to your WordPress admin menu. Selecting it will bring you to the WP Discourse options page.

The notice at the top of the page will indicate that you are not connected to your Discourse forum. To establish a connection, enter:

  • the URL of your forum into the ‘Discourse URL’ settings field

  • your forum’s API key (the API key for ‘All Users’, found at /admin/api in your forum’s admin section) in the ‘API Key’ settings field

The ‘Publishing username’ setting defaults to ‘system’. Unless you have changed that name on your forum, you can leave the default value, or change it to the username of any admin user on your forum.

The Publishing Username is the default name under which WordPress posts will be published to Discourse. For WordPress users to publish posts to Discourse with their Discourse username, they need to set their Discourse Username on their WordPress profile page. If a user attempts to publish a post to Discourse without having set their Discourse Username, they will be prompted to set it before they publish the post.

Now click the ‘Save Options’ button. If everything is correctly configured, you should see a notice that ‘You are connected to Discourse’ at the top of the page. If you are ever having issues with the plugin’s connection to your forum, navigate to this page and check the connection status notice.

Publishing Settings

Next click on the ‘Publishing’ Settings tab. This section is for configuring how the plugin publishes posts to Discourse.

The Default Discourse Category option sets the default category in which your posts will be published on Discourse. This setting can be overridden for individual posts in the ‘Publish to Discourse’ metabox on the WordPress post-new screen.

The ‘Display Subcategories’ checkbox indicates whether or not you want to your forum’s subcategories to be available as categories that you can publish to from WordPress. You will need to save this setting before subcategories become available in the Default Discourse Category option input.

Use the ‘Force Category Update’ when you have added new categories to your forum and would like them to be available on your WordPress site. Enabling this setting makes a single API call to Discourse to retrieve the Discourse categories. After enabling it, the next time you navigate back to the Commenting tab, you will find the setting disabled.

Select the ‘Use full post content’ setting if you would like to publish full WordPress posts, rather than excerpts, to your Discourse forum. Note: to keep the ‘Show Full Post’ button from appearing under your post on Discourse, you must unselect the ‘embed truncate’ setting on Discourse (found at yourforum.com/admin/site_settings/category/posting.)

If you have not selected the ‘Use Full Post Content’ setting, the ‘Custom excerpt length’ setting will create excerpts of that length to be published to Discourse. You can also manually create excerpts when you create a WordPress post by adding the excerpt to the ‘Excerpt’ meta-box.

Selecting the ‘Auto Publish’ setting will pre-check the ‘Publish to Discourse’ checkbox that appears on the post-new screen for post-types that are to be published to Discourse. This setting can be overridden for individual posts.

The ‘Auto Track Published Topics’ setting is enabled by default. When enabled, the author of a post published to Discourse from WordPress will automatically be ‘Watching’ the topic (they will receive Discourse notifications about every new reply)

The ‘Post Types to Publish’ setting must be set. It defaults to ‘post’, but pages and custom post types may also be selected.

Click the ‘Save Options’ button to save your settings.

Commenting Settings

Next, click on the ‘Commenting’ settings tab. This section is for configuring how Discourse comments are displayed on your WordPress site.

To have Discourse comments show up on your WordPress site, you must select the ‘Use Discourse Comments’ setting. Alternatively, you can select Link to Comments Without Displaying Them to display a ‘Join Discussion’ link to the Discourse post instead of displaying the comments on WordPress.

The Load Comments WIth Ajax setting is used to load comments from the client, instead of loading them from the server. This is useful if page caching is preventing fresh comments from being loaded on your site.

The Load Comment CSS setting loads a stylesheet that fixes issues with Discourse oneboxes and quotes when they are displayed on WordPress.

To also show existing WordPress comments for posts that have also been published to Discourse, select the ‘Show Existing WP Comments’ setting.

If you are showing existing comments, The ‘Existing Comments Heading’ setting will add a heading above the WordPress comments.

The next group of settings, from ‘Max Visible Comments’ to ‘Only Import Moderator-Liked’ (excluding ‘Custom Datetime Format’, which I now see should be moved ) is for configuring which comments from Discourse should be published on your WordPress site. The default values are a reasonable place to start. If you would like to have complete control over which comments are published, select the ‘Only Import Moderator-Liked’ setting. (Note: comments must be liked by a forum moderator, not an admin.)

The ‘Custom Datetime Format’ setting formats the date that is displayed for each Discourse comment that appears on your WordPress site. Start with the default value. If you find you want to change the date format, click on the link in the settings description for details on how to do that.

Click the ‘Save Options’ button to save your settings.

Text Content Settings

Next, click on the ‘Text Content’ settings tab. This section is for configuring the plugin’s user facing text. If you like, you can leave the default values for this setting in place.

If your site is in a language other than English, you can use this section to translate the plugin’s user facing text.

The ‘Discourse Link Text’, ‘Start Discussion Text’, and ‘Continue Discussion Text’ settings work together to create the text for links from your WordPress site to your Discourse form.

As an example, my forum has the title ‘The Constructive Learning Space’. I would like the ‘Start discussion’ link, that occurs under published posts when there are no comments, and the ‘Continue discussion’ link, that occurs under published posts when there are comments, to read:

’Start the discussion on the Constructive Learning Space

and

’Continue the discussion on the Constructive Learning Space

To do that I add the text ‘Constructive Learning Space’ to the ‘Discourse Link Text’ setting, the text ‘Start the discussion on the’ to the ‘Start Discussion Text’ setting, and the text ‘Continue the discussion on the’ to the ‘Continue Discussion Text’ setting.

The three settings that are prefixed with Join Discussion Link: are for when the ‘Join Discussion’ link is being used instead of displaying Discourse comments. The no Comments link is the text that will be displayed before any comments have been added to the Discourse topic. After that, the Comments Singular and Comments Plural text will be used. The number of comments will be prepended to the text for each of these settings.

Webhook Settings

Webhooks can be used to synchronize data between Discourse and WordPress.

To use the Sync Comment Data webhook, visit the Discourse URL provided in the setting’s description (http://forum.example.com/admin/api/web_hooks.) On that page, click the ‘New Webhook’ button. That will bring you to a page that looks like this:

In the Payload URL field, enter the URL that is provided in the description of the WP Discourse Sync Comment Data field. It will be something like this, except using your WordPress site’s URL: http://wp-discourse.dev/wp-json/wp-discourse/v1/update-topic-content.

Make sure the Content Type field is set to application/json.

In the Secret input, enter a string of text, at least 12 characters long. Then copy this same key into the WP Discourse Webhook Secret Key setting. The plugin will not process webhooks if the secret key is missing, or if it doesn’t match the key supplied on Discourse.

In the ‘Which events should trigger this webhook?’ box, make sure that ‘Post Event’ is selected.

Use the Triggered Categories field if you only publish posts from WordPress to specific categories. That way, your WordPress site will not need to process webhook requests for topics that don’t have an associated Discourse post.

Leave the Check TLS certificate of payload url setting enabled.

Enable the ‘Active’ checkbox, and click create. When the webhook has saved, click the Go to events button.

On WordPress, enable the Sync Comment Data webhook setting. Make sure that you have entered the webhook secret from Discourse into the Webhook Secret Key field. Then save the options.

The Discourse webhook should now be ready to use. You can check it by clicking the webhook’s Ping button (found at /admin/api/web_hooks/:webhook_id/events.) Doing that should return a status code of 200.

SSO Settings

The ‘SSO’ settings tab is for configuring Single Sign On options between WordPress and Discourse.

Note: unless you have a need to either manage the authentication of Discourse users through WordPress, or the authentication of WordPress users through Discourse, you can leave this section alone.

SSO can be configured to either use your WordPress site as the Single Sign On provider for your Discourse forum, or to use your Discourse forum as a Single Sign On provider for your WordPress site. When Discourse is functioning as the SSO provider, your WordPress site will be the SSO ‘client’.

The SSO options page has three sub-tabs: ‘SSO Secret Key’, ‘SSO Provider’, and ‘SSO Client’.

To use your site as either an SSO provider or client, go to the ‘SSO Secret Key’ tab and enter a string of text (numbers, letters, and symbols are all allowed), at least 10 characters long. Use the same rules for creating this as you would to create a strong password.

Now go to your Discourse forum’s admin settings section.

All SSO options on your forum can be found a the URL yourforum.com/admin/site_settings/category/all_results?filter=sso. In the Discourse ‘sso secret’ field, enter the same value as you have set on WordPress for your Secret Key. Click the green arrow to save the value.

WordPress as the SSO Provider

To enable your site to function as the SSO Provider for your forum, click on the ‘SSO Provider’ tab. Select the ‘Enable SSO Provider’ checkbox and save your settings.

Next, go to your forum’s SSO settings:

  • select ‘enable sso’

  • enter the ‘home URL’ of your WordPress site in the ‘sso url’ input (this can be found in the documentation at the top of the WordPress ‘SSO Provider’ tab.)

Save the settings by clicking the green checkmarks that appear beside each setting.

To make sure that SSO is setup correctly, log out of your forum. After logging out, you’ll notice that the Discourse ‘Sign Up’ button no longer appears. Click on the ‘Log In’ button. If you are currently logged in to your WordPress site, you should now be logged into Discourse. If you are not logged in to WordPress, you will be redirected to the WordPress login screen. Log yourself in there, and you should be redirected back to Discourse and logged in.

If your aren’t able to log back in to your Discourse site, there are a few possible things that could have gone wrong. To fix them, you’ll first need to disable SSO on Discourse so that you can get back into your site. Here is how to to that:

Disable SSO Through the Discourse Console:

cd /var/discourse
./launcher enter app
rails c
SiteSetting.enable_sso=false
exit
exit

Login Through the /users/admin-login Path

  • enter the URL in your browser yourforum.com/users/admin-login
  • enter your admin email address
  • wait for the email and follow it’s instructions

If you’re having issues with using WordPress as the SSO provider for your forum, the first things to check are:

  • that the SSO Secret keys set on WordPress and Discourse are the same

  • make sure that you have selected ‘Enable SSO Provider’ on your WordPress site

  • make sure you have entered the correct ‘sso url’ on Discourse.

If your problem persists, create a topic on this forum in the support/wordpress category, and someone will be able to help you.

There are a few advanced features on the ‘SSO Provider’ tab that can be used for automatically creating and logging in Discourse users when they are created/logged in on WordPress. They are fairly well documented in the plugin. If you have any questions about them, create a topic in the support/wordpress category.

Email Verification When WordPress is the SSO Provider

Discourse expects all user’s email addresses to be verified; WordPress doesn’t force users to verify their email address. In a default WordPress setup it is fairly easy to verify a user’s email address during the registration process, but if a site is using a plugin that creates a front end registration form - for example, the registration form that can be added with WooCommerce - the WP Discourse plugin isn’t able to verify the user’s email. In this case, before a WordPress user will be able to login to the forum, they will need to respond to an email verification notice that is sent out by Discourse. The plugin has a couple of filters that can be used to override this behaviour. Take a look at the code, starting here, for details.

WordPress as the SSO Client

To enable your site to function as an SSO Client for Discourse, click on the ‘SSO Client’ tab. Select:

  • ’Enable SSO Client’

  • ’Add Login Link’

Now visit your forum at yourforum.com/admin/site_settings/category/all_results?filter=sso. Then:

  • select the ‘enable sso provider’ setting

  • make sure you have added your WordPress Secret Key to the ‘sso secret’ setting

Discourse should now be functioning as a Single Sign On provider for your WordPress site.

Logout of your WordPress site. When you now go to your login page, you should see a ‘Log in with Discourse’ link underneath the login form. Click it. If you’re not currently logged in to Discourse, you’ll be taken to the Discourse login form. Login there, and you’ll be redirected back to the WordPress login page with a notice saying that you need to sync your account with Discourse. Follow the instructions in the notice to link your accounts, and you should now be able to log into your WordPress site through Discourse.

Note: this behaviour only affects users who have existing accounts on both WordPress and Discourse. New WordPress accounts that are created through Discourse SSO will be able to login freely to WordPress the first time the click the ‘Log in with Discourse’ link. To make it easier for users with existing accounts on both your WordPress site and your Discourse forum to login through Discourse, select the ‘Sync Existing Users by Email’ checkbox on the ‘SSO Client’ options tab.

Syncing Discourse logout when using WordPress as either the SSO client or the SSO provider

When SSO is enabled, logout from Discourse can be synced with your WordPress site by adding your site’s home_url with the query parameter request=logout to the Discourse setting ‘logout redirect’. The setting is in the Discourse settings section at /admin/site_settings/category/users.

Here’s an example ‘logout redirect’ URL:

http://example.com/?request=logout

Customizing the plugin's HTML templates

The HTML templates that are used for publishing WordPress posts to Discourse, and displaying Discourse comments on WordPress can be customized. For details on doing this, see the WP Discourse template customization #howto topic.

Publishing Posts to Discourse

The plugin adds a ‘Publish to Discourse’ metabox to the WordPress ‘post-new’ and ‘post-edit’ screens for post-types that you have selected in the plugin’s options. To publish a post, make sure that the ‘Publish post to Discourse’ checkbox is selected, and select the category you wish to publish to from the category options input. If you edit a published post, the new content will be sent to Discourse. It’s currently not possible to change the Discourse category of a post once it’s been published.

Multisite Support

The WP Discourse plugin works with WordPress multisite setups for everything except using WordPress as an SSO Client for your Discourse site.

Using WordPress as the SSO Provider for Discourse is supported for multisite setups.

The plugin has a Multisite Configuration option for the case where one Discourse forum is connected to a network of multiple WordPress. This option is available on the Connection settings tab of the main site of a network. Selecting it allows some of the plugin’s setting to be used over the entire network (all the connection options, the Webhook options, the SSO Secret Key, and Enable SSO setting.) Enabling this setting will create an extra database table that’s used for associating Discourse topic_ids with WordPress blog_ids when posts are published from WordPress to Discourse.

Tips and Tricks

For tips and tricks on customizing the plugin in your theme’s functions.php file see WP Discourse Plugin tips and tricks


Where can I find API key?
SSO Configured but Not Working
Discourse comments are not reflected on Wordpress blog
WP Discourse 1.0.0 release
How to kick start a community?
Wordpress SSO stuck in redirect loop
WP Discourse 1.4.0 Release
Where can I find API key?
Announcing v1.0 of WP Discourse
Disable email verification with SSO and Discobot messages
An interesting question for people linking discourse to wordpress - embedding calendars
(Simon Cossar) #13

11 posts were split to a new topic: WordPress as SSO Client in a Multisite Installation


(Erlend Sogge Heggen) #73

A post was split to a new topic: Value of integrating Discourse and WordPress


(Simon Cossar) #81

5 posts were merged into an existing topic: Link existing forum topic to new WordPress post


(Simon Cossar) #103

4 posts were split to a new topic: Confirming Discourse username when publishing posts from WordPress


(Simon Cossar) #107

4 posts were split to a new topic: Only Import Moderator Liked setting hides moderator’s posts


(Simon Cossar) #114

6 posts were split to a new topic: Move the Discourse Username field out of WordPress Contact Info section


(Simon Cossar) #121

A post was split to a new topic: Allow publishing unlisted topics to be configured by category