In this tutorial, we are going to display recently joined Discourse members in a WordPress widget.
What will you need
- Admin rights in your Discourse (or ask an admin for an API key)
- Twig Anything WordPress plugin
- 10-15 minutes of time
Table of contents
- Locate the information you need in Discourse
- Find the right Discourse API to use
- A trick to make it really easy
- Learn the data returned by API
- Create a Twig Template in WordPress
- More about Data URL
- Enter HTML template
- Make usernames clickable
- Display avatars
- Display time since joined
- Filter out blocked and suspended users
- Limit to only show 5 users
- Save & Publish your template
- Embed in a WordPress widget
Step 1. Locate the information you need in Discourse
For some reason, the only place you can get the list of your forum members ordered by creation time is the administration panel.
Open your Admin panel in Discourse, click Users, then click New. You will see the list of your forum members recently joined, the most recent ones coming first:
Step 2. Find the right Discourse API to use
Now that we can literally see the information that we want to retrieve from Discourse, we have to identify which API we want to call to get the information.
Open Developer Tools in Google Chrome:
Select the Chrome menu 
at the top-right of your browser window, then select Tools > Developer Tools.
Click on the Network tab and then on the XHR section:
A trick to make it really easy
Now, here is a trick. Click on the Active tab and then immediately on the New tab and notice how new requests are sent to the server - active.json and new.json respectively:
It is intuitively understood that new.json is what we need, so click on it and copy the Request URL, but without the ?_=143… part:
http://forum.kozovod.com/admin/users/list/new.json
Step 3. Learn the data returned by API
Click on the response tab and copy all text:
Open a json viewer tool
and paste the response text into the left panel,
then click on the arrow to beautify it:
Now you can explore your API data in a nice way and figure out which information you want for your widget in WordPress.
Step 4. Create a Twig Template in WordPress
Click on the Add New under the Twig Templates menu in your WordPress administration panel:
Give your template a title and configure as on the following screenshot:
- Source Type = URL - this means we want to fetch data from a URL
- Data Format = JSON - this means the data fetched is in JSON format
- Cache lifetime in seconds - keep empty for now, will explain later
- Data errors handling - leave as is, more explanations below
- Data URL - this is where we have to put our URL from step 2.
Data URL
Because the information we need from Discourse is found in the discourse admin panel, we can only access it by appending an API key to our URL. So, add this to the end of your URL:
?api_username=XXX&api_key=YYY
Replace XXX with a discourse username and YYY with the corresponding API key.
Step 5. Enter HTML template
We can start making up the output that we want in WordPress.
We will need a bit of HTML and Twig syntax, but both are pretty easy, just keep reading.
Back to our json editor from Step 3, let’s see what data we will need:
First of all, notice that the topmost element is an array. This means we can loop over it in our HTML template.
The data retrieved via API is passed to your template as data variable.
To loop over it, use the Twig’s for syntax:
{% for user in data %}
{{ user.username }} <br/>
{% endfor %}
Enter the code above into your Twig Template and click on the Preview button:
The preview screen opens and here we go!
Make usernames clickable
Public user profiles in Discourse can be accessed via a link like this:
http://your-discourse-website.com/users/XXX (replace XXX with a lowercase username)
To make the usernames in our widget clickable, let’s use the <a> HTML tag:
{% for user in data %}
<a href="http://forum.kozovod.com/users/{{user.username_lower}}">
{{user.username}}
</a>
<br/>
{% endfor %}
Notice how we use another field from the API - username_lower.
Clicking on the Preview button shows our new template code in action:
Display avatars
In the JSON-editor, you will see there is a field named avatar_template:
If you append this avatar template to your Discourse URL and replace {size} with a number indicating the size of the avatar square, you will get the actual avatar image. For example:
http://forum.kozovod.com/letter_avatar/olga_kashubina/70/5_fcf819f9b3791cb8c87edf29c8984f83.png
Or a smaller version:
http://forum.kozovod.com/letter_avatar/olga_kashubina/26/5_fcf819f9b3791cb8c87edf29c8984f83.png
(the links above can break with time)
We can use this knowledge to show user avatars in our “recently joined” list:
{% for user in data %}
<img src="http://forum.kozovod.com{{ user.avatar_template|replace({'{size}':'26'}) }}" />
<a href="http://forum.kozovod.com/users/{{user.username_lower}}">
{{user.username}}
</a>
<br/>
{% endfor %}
Here we’re using the Twig’s replace function.
Now if you click the Preview button, you will see something like this:
Display time since joined
To display the age since a user registered, use the created_at_age field:
{% for user in data %}
<img src="http://forum.kozovod.com{{ user.avatar_template|replace({'{size}':'26'}) }}" />
<a href="http://forum.kozovod.com/users/{{user.username_lower}}">
{{user.username}}
</a>
<small style="color: gray">{{ user.created_at_age }}</small>
<br/>
{% endfor %}
And voila!
Filter out blocked and suspended users
It would be logical not to show any blocked and/or suspended users in our list.
For this, we would use these two fields from our API result:
Adding an if in the loop would do the job:
{% for user in data if (not user.suspended and not user.blocked) %}
...
{% endif %}
Limit to only show 5 users
This one may seem a bit more complicated, but let me break it down so that it is easy to understand.
First, we will need a counter of how many posts have been displayed already, so add this in the very beginning of your HTML template:
{% set num = 1 %}
Next, we want to increment the counter every time a username is rendered, so just before the end of the loop, add this:
...
{% set num = num + 1 %}
{% endfor %}
Finally, wrap your output inside the loop in {% if %}:
{% if num <= 5 %}
...
{% endif %}
Now altogether:
{% set num = 1 %}
{% for user in data if (not user.suspended and not user.blocked) %}
{% if num <= 5 %}
<img src="http://forum.kozovod.com{{ user.avatar_template|replace({'{size}':'26'}) }}" />
<a href="http://forum.kozovod.com/users/{{user.username_lower}}">
{{user.username}}
</a>
<small style="color: gray">{{ user.created_at_age }}</small>
<br/>
{% endif %}
{% set num = num + 1 %}
{% endfor %}
Now only 5 most recent new forum members are shown in the preview:
Save & Publish your template
Once you are satisfied with the template output, don’t forget to publish it by clicking the Publish button. Only published templates can be embedded in WordPress. This follows the same logic as with posts and pages: if a post is not published, it is not seen by the public.
Step 6. Embed in a WordPress widget
It’s show time!
Copy the slug of your template, which can be found just under the template title:
In your Widgets administration panel, drag the Twig Template widget to a widget area (you might have more than one widget areas available):
Give your widget a title and enter the slug we just copied:
Click Save. Done! Now check your home page’s sidebar and smile!
What next?
-
Grab Twig Anything and install it to your WordPress
-
Read the Twig Anything announcement topic
-
Read about what happens if WordPress can’t fetch data from Discourse at some point in time
-
If you are using Visual Composer, see the demo
-
Read the Twig documentation
-
Ask me any questions in this thread: another tutorial? template snippets? more features?
-
If you are using Twig Anything already, show us how!
