A l l    a b o u t   t e m p l a t e    t a g s
-----------------------------------------------


This is a document for people who want to customise their WordPress install by editing their template files. If you're new to WP-United, put this file to one side for now....

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.

-----------------------
-----------------------
Intro
-----------------------
-----------------------


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

Template tags are 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 <?php your_tag(); ?> . Don't worry if this looks complicated - it is quite easy. For more information on WordPress template tags, see here: http://codex.wordpress.org/Template_Tags

-----------------------
-----------------------
WP-United Template Tags
-----------------------
-----------------------

You can insert template tags anywhere in your WordPress template files. The tags are abeing added to all the time, but currently, we provide the following:


Blog lists and introductions
----------------------------

<?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. (the output can be 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, 10 results, as an item in the sidebar of the 'default' template:
<li>
	<h2>Latest Blog Posts</h2>
	<ul>
		<?php wpu_latest_blogposts('limit=10&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.
----

<?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:

The below tags are really only useful for a blogs 'home page'. If you just want to include a nice list of blogs as your WordPress homepage, select the appropriate option in the WP-United Setup Wizard.

-----

<?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.


-----

<?php wpu_intro(); ?>

This displays the introductory text you set in the WP-United Setup Wizard. If you included {GET-STARTED} in the text you provided in the Setup Wizard, 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.

------

<?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 tuen on the option in your WP-United Setup Wizard!




Avatars
-------

<?php avatar_commenter(); ?>  
This displays the address of the phpBB avatar of the current commenter. It must be used within a comment loop.

-----

<?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.

-----

<?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
----------------------------------

<?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).

-------

<?php wpu_phpbb_ranktitle(); ?>

This returns the phpBB rank of the current user

-------

<?php wpu_phpbb_rankimage(); ?>

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

-------

<?php wpu_phpbb_rankblock(); ?>

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


-------

<?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.


-------

<?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.

-------

<?php wpu_newposts_link(); ?>

Use this to retrieve a link to a phpBB new posts search. For example 'View Posts Since Your Last Visit (x);, where 'x' is the number of posts since your last visit.

-------


<?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 ]"

-------

<?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.

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:
wp_register('', ''); 

This displays the link in the heading-2 style:
wp_register('<h2>', '</h2>'); 

------

For either of these tags, you can change the text that is displayed the same way you would do in phpBB -- by editing your language file.


-----------------------
-----------------------
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 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 to the following. This example displays some text if a user is not logged in:

$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). Like in the following example:
<?php avatar_commenter(TRUE, $comment->user_id); ?>  


Check out the widgets
----------------------

If you activate widgets in your theme, several WP-United widgets will automatically appear. These provide easy access to many of the above functions, and a few composite functions.


Coming soon!
------------


A lot more template tags will be provided in the future, depending on how well these are received. The plans are currently to provide:

- Number of user's phpBB posts
- phpBB user location
- phpBB rank titles and images
- phpBB board statistics
- Polls
- Your suggestions here

-------------------


--------------------------------------------------------------------------------------------------------------------
Last updated: 25 March 2007 by John Wells
You can copy, alter or redistribute this document freely, but you must leave the below copyright and information intact.

(c) 2007 John Wells / WP-United.com


SUPPORT WP-UNITED
-----------------

Want to help improve the software? There are lots of ways you could help:
- Bug swatting -- Report any bugs you find on the forums. Anything, from typos to server crashes... let us have it!
- More Exposure -- Link back to www.wp-united.com, or post about WP-United on your blog. Want an interview? I'm available!
- Cash -- of the cold and hard variety. Every little bit helps. I don't have much...
- Translation -- translate this file and the language strings used in the mod. I'll put your name in lights (well, pixels) if you do.
- Cash --  Oh wait...