@Simon_Cossar wrote:
Installation
From your WordPress dashboard
- Visit 'Plugins > Add New'
- Search for 'WP Discourse'
- Activate WP Discourse from your Plugins page
From wordpress.org
- Download WP Discourse
- Upload the 'wp-discourse' directory to your '/wp-content/plugins/' directory
- 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 dev-beta
Or manually add it to your
composer.json
:{ "require": { "php": ">=5.4.0", "discourse/wp-discourse": "dev-beta" } }
Note: requiring
'dev-beta'
will soon be changed to'1.0.0'
, I'll update the instructions here and on the plugin's README when that happens.Upgrading from earlier versions
Upgrading the plugin from earlier versions should be seamless. Follow the normal WordPress upgrade procedure through your WordPress dashboard. Your previous settings should be transferred to the new options tabs. If you have any issues with upgrading the plugin, please let me know.
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 this menu 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, and 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.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.
Note: the API key in these screenshots is from my local development environment. Be careful to keep your API key private!
Publishing settings
Next click on the 'Publishing' Settings tab. This section is for configuring how the plugin publishes posts to Discourse.
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.
The 'Published category' setting selects a default Discourse category to publish to. This setting can be overridden when you create a new WordPress post.
The 'Force category update' setting is useful if you have added new categories to your forum and would like them to be immediately available on your WordPress site. Don't leave this setting permanently enabled, it will force your site to make unnecessary requests to Discourse.
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.
The 'Post types to publish to Discourse' 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 comments are published on your WordPress site.
To have Discourse comments show up on your WordPress site, you must select the 'Use Discourse Comments' setting.
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 comments liked by a moderator' (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 comments liked by a moderator' 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.
The 'Debug mode' setting is useful if you are testing the plugin in a development environment, or when you are fist testing the plugin on your site. When this setting is not enabled, comments from your forum will not be synced more often than once every 10 minutes. When this setting is enabled, comments are refreshed on each request. Note: Enabling this setting in a production environment may put a very heavy load on your server.
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.
Note: 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.
SSO settings
Next click on the 'SSO Settings' tab. This section is for configuring WordPress as the Single Sign On provider for Discourse. Unless you have a need to manage your forum's users through your WordPress site, you can leave this setting alone.
To enable SSO, select the 'Enable SSO' setting.
Note: don't enable SSO on your Discourse forum until you have all the SSO settings configured on your WordPress site.The 'Path to your login page' setting is useful if your login page is somewhere other than the default WordPress login at
/wp-login.php
. You can check this on your WordPress site by addinglogin
to your site's root URL in your browser's address bar. If you are taken toyourdomain.com/wp-login.php
you have the default setup and can leave this setting alone. If your login page is somewhere else, enter the relative path to your login page, starting with a '/
', in this setting.The SSO Secret key is set on your Discourse forum. Go to
yourforum.com/admin/site-settings/category/login
. Look for the 'sso secret' setting and either retrieve or create a key. Copy this value and paste it into the wp-discourse *'SSO Secret key'** setting field.By default, enabling SSO in the plugin will turn all links to Discourse that are created by the plugin on your site into SSO links. Clicking on one of these links will force a user to either login or register before they can visit the Discourse site. If you would like users to be able to visit your forum without first having to login or register, enable the 'Redirect Without Login' setting.
SSO setup on Discourse
Once you have your SSO setup configured on WordPress, go to
yourforum.com/admin/site-settings/category/login
on your Discourse forum. Look for the SSO settings fields on that page (they begin with 'enable sso'.)You should already have set the 'sso secret' key setting field.
You now need to enter the path to your login page in the 'sso url' setting. In all cases this should be
yourdomain.com/login
. WordPress will redirect from that to the correct login path for your site.You then need to select the 'enable sso provider' setting and the 'enable sso' setting. After doing that, SSO should work between your forum and your WordPress site.
There are additional SSO settings on Discourse. The setting 'sso overrides username' will change the users Discourse username to match their WordPress username. The setting 'sso overrides avatar' will change the user's Discourse avatar to match their WordPress user avatar.
Note: enabling the setting 'sso overrides email' is not recommended at this point. If a user changes their email on WordPress it will not be revalidated by Discourse. Instead, for now, if your WordPress users change their email address, have them visit their Discourse users profile page and update their email address there.
Customizing the plugin's HTML templates
For details on how to customize the plugin's HTML templates see the WP Discourse template customization #howto
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
Posts: 1
Participants: 1