Advanced Features

Information for power users to enhance your existing PunBB installation.

This script extern.php is used to include information about your board from pages outside the forums and to syndicate news about recent discussions via RSS. The script can display a list of recent discussions (sorted by post time or last post time), a list of active users or a collection of general board statistics. The script can be called directly via an URL (for RSS), from a PHP include command or through the use of Server Side Includes (SSI).

The scripts behaviour is controlled via variables supplied in the URL to the script. The different variables are: action (what to output), show (how many topics to display), forum (the ID of the forum to poll for topics) and type (output as HTML or RSS). The only mandatory variable is action.

• action: active (show most recently active topics) (HTML or RSS)
  new (show newest topics) (HTML or RSS)
  online (show users online) (HTML)
  online_full (as above, but includes a full list) (HTML)
  stats (show board statistics) (HTML)
• show: Any integer value between 1 and 50. This variables is ignored for RSS output. The default is 15.
• fid: One or more forum IDs (comma-separated). If ignored, topics from all guest-readable forums will be polled.
• type: RSS. Anything else means HTML output.

• Show the 15 most recently active topics from all forums:
  include('http://host.com/forums/extern.php?action=active');
• Show the 10 newest topics from forums with ID 5, 6 and 7:
  include('http://host.com/forums/extern.php?action=new&show=10&fid=5,6,7');
• Show users online:
  include('http://host.com/forums/extern.php?action=online');
• Show users online with full listing of users:
  include('http://host.com/forums/extern.php?action=online_full');
• Show board statistics:
  include('http://host.com/forums/extern.php?action=stats');

• Show the 5 newest topics from forums with ID 11 and 22:
  <!–#include virtual=“forums/extern.php?action=new&show=5&fid=11,22” –>
• Show board statistics:
  <!–#include virtual=“forums/extern.php?action=stats” –>

And finally some examples using extern.php to output an RSS 0.91 feed.

• Output the 15 most recently active topics:
  http://host.com/extern.php?action=active&type=RSS
• Output the 15 newest topics from forum with ID=2:
  http://host.com/extern.php?action=active&type=RSS&fid=2

Integrating PunBB into your website code is easy if you know a little PHP. By including PunBB's script common.php, you gain access to all PunBB global variables such as $db and $pun_user. However, in order to include this file, you need to define a constant called PUN_ROOT. This constant should be set to the relative path to your PunBB forum directory. For example, if your website front page is located in /home/user/public_html/ and your forums are located in /home/user/public_html/forums/, your PUN_ROOT should be './forums/'. The PHP code to accomplish this could look something like this:

define('PUN_ROOT', './forums/');
require PUN_ROOT.'include/common.php';

Once you've included common.php, you can access and utilize all of PunBB's global variables and functions. Typically, you will be most interested in the $pun_user array. This array holds information about the current user. Another interesting variable is the database object $db. How to use these variables in your own script is out of the scope of this document, but here's a small example showing you how to print a simple message greeting the current user on your website front page:

Hello <php echo pun_htmlspecialchars($pun_user['username']); >!

In addition to defining PUN_ROOT, you can define a number of other constants to alter the behaviour of PunBB when including common.php. The two most interesting of these constants are PUN_TURN_OFF_MAINT and PUN_QUIET_VISIT. If PUN_TURN_OFF_MAINT is defined when including common.php, PunBB will not exit and display the maintenance message if the forums are placed into maintenance mode. You generally don't want this message to appear on your website front page, so defining that constant is a good idea. The other constant, PUN_QUIET_VISIT, prevents PunBB from updating the current user's last visit data in the database so that a visit to the front page doesn't count as a visit in the forums. This is also desirable behaviour in most cases. It doesn't matter what value you set these constants to, but setting them to a value of 1 is probably a good idea. Example:</p>

define('PUN_TURN_OFF_MAINT', 1);
define('PUN_QUIET_VISIT', 1);

Please note that these constants must be defined before common.php is included.

Admin plugins are modules for the PunBB admin interface that can be installed by simply dropping the plugin script in the plugins/ directory. See the example plugin for information on how to write your own plugin. Here are a few notes of interest for aspiring plugin authors:

• If you want to display a message via the message() function, you must do so before calling generate_admin_menu($plugin).
• Plugins are loaded by admin_loader.php and must not be terminated (e.g. by calling exit()). After the plugin script has finished, the loader script displays the footer, so don't worry about that. Please note that terminating a plugin by calling message() or redirect() is fine though.
• The action attribute of any and all <form> tags and the target URL for the redirect() function must be set to the value of $_SERVER['REQUEST_URI']. This URL can however be extended to include extra variables (like the addition of &foo=bar in the example plugin).
• If your plugin is for administrators only, the filename must have the prefix “AP_”. If it is for both administrators and moderators, use the prefix “AMP_”. The example plugin has the prefix “AMP_” and is therefore available for both admins and moderators in the navigation menu.
• Use _ instead of spaces in the file name.
• Since plugin scripts are included from the PunBB script admin_loader.php, you have access to all PunBB functions and global variables (e.g. $db, $pun_config, $pun_user etc).
• Do your best to keep the look and feel of your plugins' user interface similar to the rest of the admin scripts. Feel free to borrow markup and code from the admin scripts to use in your plugins.
• Plugins must be released under the GNU General Public License or a GPL compatible license. Copy the GPL preamble at the top of this file into your plugin script and alter the copyright notice to refrect the author of the plugin (i.e. you).