pybossa-discourse¶
A PyBossa plugin for Discourse integration.
- Features:
- Use SSO to sign your PyBossa users into Discourse
- Make Discourse API requests from your PyBossa theme
- Add users’ unread Discourse notification counts to your PyBossa theme
- Embed Discourse comments into your PyBossa theme
Installation¶
Copy the pybossa_discourse folder into your PyBossa plugins directory, configure the plugin as below and restart the server.
Configuration¶
The following settings should be added to your PyBossa configuration file:
DISCOURSE_SECRET | Secret string of your choice (at least 10 characters). |
DISCOURSE_API_USERNAME | Username of an administrator of your Discourse application. |
DISCOURSE_API_KEY | The API key generated for the same Discourse administrator. |
DISCOURSE_URL | The base URL of your Discourse application. |
In order to enable SSO you should also ensure that your Discourse application is configured as follows (via Admin > Settings):
enable_sso | Enabled |
sso_url | http://{your-pybossa-domain}/discourse/oauth-authorized |
sso_secret | The value chosen for DISCOURSE_SECRET. |
sso_overides_email | Enabled |
sso_overides_username | Enabled |
sso_overrides_name | Enabled |
sso_overrides_avatar | Enabled |
allow_uploaded_avatars | Disabled |
logout_redirect | http://{your-pybossa-domain}/discourse/signout |
In order for the API client to work you should also make sure that the IP address of your server is added to the Discourse whitelist (via Admin > Logs > Screened IPs).
Theme Integration¶
To achieve better integration with your PyBossa theme you can add navigation links as follows:
<!-- Go to your Discourse homepage -->
{% if 'pybossa_discourse' in plugins %}
<a href="{{ url_for('discourse.index') }}">Community</a>
{% endif %}
<!-- Sign a user out of Discourse when they sign out of PyBossa -->
{% if 'pybossa_discourse' in plugins %}
<a href="{{ url_for('discourse.signout') }}">Sign out</a>
{% endif %}
SSO¶
With the plugin enabled, users that sign in via your PyBossa application will be automatically signed in to Discourse. Discourse accounts will be created automatically the first time any of the following things happen:
- The user visits
http://{pybossa-site-url}/discourse/index
. - The user clicks the Log In button from within the Discourse application.
- An API call is made regarding the user, such as one to retrieve their notifications.
Notification counts¶
You can add a user’s unread Discourse notification count to your PyBossa theme with the following snippet:
{% if 'pybossa_discourse' in plugins %}
{{ discourse.notifications() }}
{% endif %}
Embedding Comments¶
To embed Discourse comments in your PyBossa theme:
- Visit Admin > Customize > Embedding in your Discourse application.
- Create an embeddable host using your PyBossa domain as the hostname.
- Enter the name of the Discourse user who will create the topics in the Embed by Username field.
- Use the following snippet wherever you want comments to appear in your PyBossa theme:
{% if 'pybossa_discourse' in plugins %}
{{ discourse.comments() }}
{% endif %}
The above function takes a single optional parameter that specifies the URL of the page that will be crawled to create a topic. By default this is set to the URL of the page where the snippet is embedded.
You can also create a new topic by category ID and embed these comments on multiple pages using this snippet:
{% if 'pybossa_discourse' in plugins %}
{{ discourse.category_comments(1) }}
{% endif %}
The pages that will be crawled to create these topics are those at:
http://{pybossa-site-url}/project/category/{category-short-name}
API variable¶
You can make API calls directly from your PyBossa theme via the discourse.api variable, for example:
<!-- List the latest topics -->
{% if 'pybossa_discourse' in plugins %}
<ul>
{% for topic in discourse.api.latest_topics() %}
<li>{{ topic['title'] }}</li>
{% endfor %}
</ul>
{% endif %}
The variable points to an instance of pybossa_discourse.client.DiscourseClient.