This page provides information for people who want to customise their WordPress install by editing their template files.

If you only want to add things to the WordPress sidebar, it would probably be easier for you to use the provided widgets instead. Just activate widgets in your WordPress theme and the WP-United widgets will automatically appear.

However, if you want more control, or want to include phpBB or user blogs elements in your main page, then this document is for you!

(If you’re new to WP-United, feel free to ignore this for now — you do not need this to install or run WP-United successfully….)

WordPress’ Template System

WordPress templates use “Template tags” — little code snippets you can put in your WordPress templates to display information. Template tags are used to display everything from post titles and dates to the content of posts. By altering the template tags in your WordPress templates, you change what appears on your blog pages.

phpBB also uses template tags, in the format {YOUR_TAG}. WordPress tags are PHP function names, and so are in the format . Don’t worry if this looks complicated - it is quite easy. For more information on WordPress template tags, see the WordPress Codex.

WP-United provides a number of WordPress-style template tags for you to use in your WordPress blog.

You can insert template tags anywhere in your WordPress template files. The tags are being added to all the time, and are subject to change, but currently, the following are provided:

Blog Lists and Introductions

These tags are useful if you have ‘user blogs’ turned on.

1. Latest Posts in User Blogs

<?php wpu_latest_blogposts('option1=x&option2=y') ?>

This displays a list of the latest posts — it is intended to be used as a listing in your WordPress sidebar.
It displays results in the format “latest_post_title, in blog_title”, where latest_post_title and blog_title are links. As with all of the template tags, the exact oputput can be easily localised.

It takes the following options:

• before: html that should be included at the beginning of each item in the list
• after: html that should be included at the end of each item in the list
• limit: limits the number of posts returned

For example, the following would return a nice list of, at most, 8 results, as an item in the sidebar of the ‘default’ template:

<li>
 <h2>Latest Blog Posts</h2>
 <ul>
   <?php wpu_latest_blogposts('limit=8&before=<li>&after=</li>')?>
 </ul>
</li>

If you leave the parameters blank, ‘limit’ will default to 20 and ‘before’ and ‘afer’ will default to <li> and </li> respectively.

NOTE: This is also available as a widget.

2. Active User Blogs

<?php wpu_latest_blogs('option1=x&option2=y') ?>

Similar to the above, this creates a chronological list of the most recently updated blogs. It takes the same options as wpu_latest_blogposts

For example, the following would return the last five updated blogs in the ‘default’ template sidebar:

<li>
  <h2>Latest Blog Posts</h2>
  <ul>
     <?php wpu_latest_blogs('limit=5&before=<li>&after=</li>') ?>
  </ul>
</li>

If you leave the parameters blank, ‘limit’ will default to 20 and ‘before’ and ‘afer’ will default to <li> and </li> respectively.

NOTE: This is also available as a widget.

Listings for Blogs Home Page

These tags are really only useful for a blogs ‘home page’. If you just want a simple way to include a nice list of blogs as your WordPress homepage, select the appropriate option in the WP-United Setup Wizard instead.

1. List of User Blogs

<?php wpu_bloglist(); ?>

This displays a nice list of all your users’ blogs. It takes two paramaters: whether to show avatars, and how many blogs to show per page. For example:

• <?php wpu_bloglist(TRUE, 5); ?> shows five blogs per page, with phpBB avatars.
• <?php wpu_bloglist(FALSE, 20); ?> shows twenty blogs per page, with no avatars.

If you leave the parameters blank, avatars will default to TRUE and the number of blogs to show in the list will default to 10.

2. User Blogs Introduction

<?php wpu_intro(); ?>

This displays the introductory text you set in the WP-United Setup Wizard. If you included {GET-STARTED} in the text, it will be transformed into a sentence encouraging your users to login or register to get started, or create/add to their blog if they are logged in. More instructions are given in the WP-United Setup Wizard.

3. Show Full Blogs Homepage

<?php wpu_blogs_home(); ?>

This is a combination of the two tags above — it displays an introduction, followed by a list of blogs. This makes for a great home page! The introductory text and number of blogs listed are set in your WP-United Setup Wizard.

Note: If you want to set up a page as a site homepage that contains a nice introduction and a list of all your users’ blogs, it is easy to do! Just turn on the option in your WP-United Setup Wizard!

Again, the vast majority of people will not need to use these template tags as the Wizard creates the blogs homepage for you. However, they are included here for completeness.

Avatars

These tags deal with displaying the avatars stored in phpBB for various users.

1. Commenter Avatar

<?php avatar_commenter(); ?>

This displays the address of the phpBB avatar of the current commenter. It must be used within a comment loop.

2. Poster Avatar

<?php avatar_poster(); ?>

This displays the address of the phpBB avatar of the author of the current post or page. It must be used within The Loop.

3. Reader Avatar

<?php avatar_reader(); ?>

This displays the address of your phpBB avatar when you are reading the page. It can be used anywhere.

For all of the above, if the user is not logged in or registered, or does not have an avatar, the tags display default avatars showing “No avatar” or “Unregistered”. This could be helpful for making layouts consistent. If you do not want to use these default avatars, include the parameter ‘FALSE’ between the brackets. For example avatar_poster(FALSE); simply shows nothing when no avatar is available.

Example usage — This displays the poster’s phpBB avatar:
<img src="<?php avatar_poster(); ?>" alt="The author’s avatar" />

phpBB User Information & Functions

These return information about the logged in user, or provide functions to enhance the user’s experience.

All of this information can be displayed in your sidebar automatically via the use of widgets.

1. Get Username

<?php wpu_phpbb_username(); ?>

This returns the username of the logged in phpBB user. If they are not logged in, it returns ‘Guest’ (or whatever localised text is specified in your phpBB language file).

2. Get Rank

<?php wpu_phpbb_ranktitle(); ?>

This returns the phpBB rank of the current user.

3. Get Rank Image

<?php wpu_phpbb_rankimage(); ?>

This returns the path to the phpBB image for the current user.

4. Get Rank Block

<?php wpu_phpbb_rankblock(); ?>

This returns the phpBB rank title and image for the current user, in a similar style to phpBB’s viewtopic.php.

5. Get Forum Statistics

<?php wpu_phpbb_stats('before=<li>&after=</li>'); ?>

This returns a list of phpBB statistics: Number of posts, number of topics, number of users, and newest user. You can set the ‘before’ and ‘after’ markup for each list item.

6. List Latest Forum Topics

<?php wpu_latest_phpbb_topics('limit=10&before=<li>&after=</li>'); ?>

This returns a list of latest forum topics, including links to the topic, forum and poster. it takes the same parameters as wpu_latest_blogposts. If you leave them blank, it will default to showing 10 entries.

7. New Forum Posts Link

<?php wpu_newposts_link(); ?>

Use this to retrieve a link to a phpBB new posts search. It would return ‘View Posts Since Your Last Visit (x);, where ‘x’ is the number of posts since your last visit. The text can be localised.

8. Log in / Log out

<?php wp_loginout(); ?>

This is a default WordPress template tag, that behaves differently under WP-United. For example, the default WordPress template uses this tag in the sidebar under ‘Meta’ for the login / logout link. When you are running WP-United and have chosen to integrate logins, this automatically links to phpBB, and shows in the phpBB style — e.g. ‘logout [ user ]’ . This can be localised in your phpBB language files.

9. Register

<?php wp_register(); ?>

This is another default WordPress template tag. If a user is logged in, it shows a link to the WordPress admin panel, If not, it asks them to register. When you are running WP-United and have chosen to integrate logins, this automatically links to phpBB. If the user is logged in, and users can have their own blog, it shows “Get started with your blog” or “Add to your blog” as appropriate. This can be localised in your phpBB language files.

By default, this tag returns the result inside <li> </li> html tags, so it can be shown in a list. If you are not using it in a list, you can provide the tags you want instead, for example:

This displays the link without any surrounding html tags:
<?php wp_register(”, ”); ?>

This displays the link in the heading-2 style:
<?php wp_register(’*lt;h2>’, ‘</h2>’); ?>

Advanced Usage

If you want to write advanced structures in your templates, you may want to get some of the tags above and do something with them, rather than just displaying them outright. For all of the tags, apart from wp_loginout and wp_register, you can do this easily, by prepending the tag name with ‘get_’ . For example, get_avatar_poster(), or get_wpu_blogs_home().

For example, you could do the following. This example displays some text if a user is not logged in:

<?php
$usrName = get_wpu_phpbb_username();
if ( $usrName == 'Guest' ) {
   echo 'You are not logged in!';
}
?>

Problems with comment avatars?

WP-United will usually be able to return the correct avatar for the commenter. However, due to limitations in the way the integration engine runs, it may not work if avatar_commenter is the first thing you put in your comment loop — the wordpress template tags comment_ID() or comment_author_link() should be called beforehand.

If the correct comment avatars don’t show up, then you simply need to provide the user ID of the commenter as the second parameter (remeber, the first is TRUE/FALSE). Just like in the following example:
<?php avatar_commenter(TRUE, $comment->user_id); ?>

Another Plug for the Widgets

If you’ve alreay read this far, then you probably know what you are doing… However, do bear in mind that most of the above template tags — plus more — can be automated using the widgets provided by WP-United. The widgets are automatically loaded by the WP-United Connection.

Need More?

More tags will be provided in the future. The tags listed below are planned:

• Number of user’s phpBB posts
• phpBB user location
• Polls
• Your suggestions here

See some that you want now, or have an idea for more tags? Template tags and widgets are some of the easiest ways you can contribute to WP-United. There are plenty of examples of how to code template tags in the wpu-template-funcs.php file. If you come up with additional tags, please post them in the Forum!