Posted by Simon Goodchild  at February 12th, 2012

Let’s make a forum page template! In the order of things, it’s best if you follow the profile page template tutorial first as it explains a few things that I’ll take for granted here, like what a class is!

I’m using wps_forum_page_1.php and wps_forum_page.css files for this part – you’ll find them in the tutorials folder in the wp-symposium plugin, or download them from here.

The basis for the page template is the same as the profile and mail templates, except that I’m going to allow content added via the admin dashboard to appear – lucky you ;)

That’s simply a matter of including two lines. Try taking them out and see what disappears!

<?php the_post(); ?>
<?php get_template_part( 'content', 'page' ); ?>

You can add these to the other page templates if you would like to be able to add content, or you can hardcode the content into the page template – your choice. It just feels that a forum often benefits from having a little introductory text, that you may want to easily and quickly change. Up to you ;)

So, the class we want to include is the wps_forum class:

require_once(WP_PLUGIN_DIR.'/wp-symposium/class.wps_forum.php');
$wps_forum = new wps_forum();

This should be familiar if you’ve been through the profile page template tutorial. The above assumes you are keeping the class files where they should be – i.e., in the wp-symposium folder.

We also tell WP Symposium about our new page, over-riding the WPS installation page that looks for a shortcode:

$wps->set_forum_url('/aa-forum');

Finally, to prepare things, we include the CSS file:

<link rel="stylesheet" type="text/css" href="<?php bloginfo('template_url'); ?>/wps_forum_page.css" />

Take a quick gander at the CSS file, notice the first section “WordPress style changes”. I’m making some changes to the default TwentyEleven theme CSS to push the content that I’m now including up and out – filling the available area. I also move the “Edit” button over to the top-right to keep things tidy.

Let the fun begin!

Ok, so we are ready to pull in some forum content. Having done the profile (and hopefully mail) tutorials, you should find this relatively easy to understand, so we won’t hang about!

This is what we are aiming for in this part of the tutorial, it’s a clean and minimalist look and feel:

We start building up the “table” DIVs at line 56, before getting the list of categories at line 65:

$categories = $wps_forum->get_categories();

This will return (and pop into $categories) all the categories in the forum. Without a parameter, the “top level” returned will be the very top of the forum category hierarchy. If you have created sub-categories via the WPS admin, you could pass the ID of a “parent” category to return its “children”. But for now, we are interested in getting the lot!

What it won’t do is return “children” categories, so if you want to display any of those children categories here, you’d need a little recursive function to do so – but that’s out of the scope of this tutorial, it’s more in the PHP tutorial territory – take a stroll down Google Lane and you’ll find a wealth of info!

So we have our collection of categories, and we are going to loop through those returned (line 66):

foreach ($categories as $category) {
   ...
}

$category is now going to be each of our categories, we can handle each in turn. So in between a bunch of DIVs (and corresponding styles) we display some information about our category using:

echo stripslashes($category->title);

Note the stripslashes which, bizarrely, strips the slashes that may be needed to store the title in the database. Note that the WPS Wiki lists the fields that are returned that you might also want to display, and I’ve also listed the fields at the bottom of this article.

Last topic for each category

So far so good, and now I’m interested in showing the last topic created for each category. Other fields available for use are listed at the end of this article, or on www.wpswiki.com.

Something like that shown to the right.

So I get the last topic as follows:

$last_topic = $wps_forum->get_topics($category->cid, 0, 1);

The get_topics() method is passed up to five parameters:

• The category ID (mandatory, 0 for top level of the forum)
• Where to start from (default is 0)
• How many to return (default is 9999)
• The order of the topics by creation date (default is most recent first, pass “ASC” to reverse)
• The group ID if focussing on a group (default is 0, ie. not a group)

So we are passing the first three only: the category ID, start from 0, stop after 1. Why just 1 for the third parameter? Because we only want to most recent and it cuts down on server load and the amount of content to return.

If 1 topic is returned, as here, it is returned as a recordset. If more than 1 (as in the next part of the tutorial), an array is returned.

If there is a last topic for the category (checked on line 73), then we display the information about the last topic in between our DIVs.

Showing the last topic avatar

To jazz up the forum a bit, it would be nice to display the avatar of the author of the last topic. This is where familiarity with the profile page template tutorial comes in handy, I won’t go into detail again. Suffice to say, using $last_topic->topic_owner as the parameter, we create a new wps_user object and do two things:

1. Create a hyperlink to the profile page (with wps->get_profile_url() and uid as a parameter);
2. Display the avatar with wps_user->get_avatar(48), where 48 is the size of the avatar in pixels.

Finishing off the last topic

Finally we display the topic subject, display name of the author and how long ago it was created (using the symposium_time_ago function coupled with $last_topic->topic_started).

And there we have it, the start of our new forum page template. There are lots of other values returned by get_categories() and get_topics(), check out the WPS Wiki to see the full list and play around with customising your forum.

Next stop, part 2, will be to click on a forum category and display the topics in that category.

For reference… fields returned by get_categories()

This list can also be found on www.wpswiki.com.

• cid – category ID, integer
• title – title of the category, text
• listorder – order for categories to appear defined in admin area, integer
• allow_new – are new topics by users allowed? ‘on’ or ” (can use true/false)
• defaultcat – is this the default category for new topics? ‘on’ or ” (can use true/false)
• cat_parent – parent cid for this category, as a hierarchy, integer
• cat_desc – description of this category, text
• level – serialized list of WordPress roles that should have access to this category (see later tutorial)

For reference… fields returned by get_topics()

This list can also be found on www.wpswiki.com.

• tid – topic ID, integer
• topic_group – 0 for none (ie. main forum), or group ID if a group forum, integer
• topic_category – which category the topic belongs to, integer
• topic_subject – if the initial topic post, the subject of the topic, text
• topic_post – the body of the topic or reply, text
• topic_owner – the user ID of the topic creator, integer
• display_name – WordPress display name of topic_owner
• topic_date – date created, or last replied to, datetime
• topic_parent – if a reply, the ID of the topic, or 0, integer
• topic_views – holds a count of times topic viewed, integer
• topic_started – initial creation date, datetime
• topic_sticky – should topic be sticky? ‘on’ or ” (or use true/false)
• allow_replies – should replies by allowed? ’on’ or ” (or use true/false)
• topic_approved – defaults to ‘on’, or ” if awaiting moderation (or use true/false)
• topic_answer – is this the answer to a topic? ‘on’ if yes, otherwise ” (or use true/false)
• for_info – is this topic just for information? ’on’ if yes, otherwise ” (or use true/false)