Special features: Quickinfo

Tetra WebBBS Documentation

Motivation

Ever since the old WebBBS versions offered a special summary output if ?quickinfo was appended to the URL of webbbs_config.pl. This function was intended to be used by SSI. Unfortunately it's output was rather basic and neither flexible nor very useful.

In Tetra-WebBBS 5.31 quickinfo calls have been refactored to a flexible tool to display a forum's recent posts (or a random post) in various ways.
One may use this new feature to create portals, create sort of Google-like banners or use for cross-forum listing of posts. Detailed description and examples below.

Note:
For backwards compatibility the old way of appending a simple ?quickinfo still works.
In order to benefit from the new features you must use the syntax explained below!

Basic configuration

Before using quickinfo calls, make sure they are enabled: Either in webbbs_settings.pl or in section(3) of the entry script, which you want to use for calling quickinfo, you must set $AllowQuickinfo to "1".

Basic quickinfo calls

The basic quickinfo call looks like this:
http://www.yourdomain.com/cgi-bin/bbs53x/webbbs_config.pl?quickinfo=<number>;type=<type>;

quickinfo=<number> specifies which posts to display.
If you set <number> to any positive integer number the call will display the given number of most recent messages of the forum served by webbbs_config.pl.
If you set <number> to "rand" the call will display exactly ONE random post from the forum served by webbbs_config.pl
For a very special purpose you may set <number> to "0". This is to display only the *new posts* telltale, see below for details.

type=<type> specifies the output type.
If you set <type> to "html" the call will print plain HTML. Usefull for either SSI calls or Iframes.
If you set <type> to "js" the call will print JavaScript code to display the requested information.

Now you may perform a first test. Adjust the following URL to your site's specifics and point your browser to it.
http://www.yourdomain.com/cgi-bin/bbs53x/webbbs_config.pl?quickinfo=1;type=html;
You'll be prompted with a very simple, yet unformatted information on the most recent post, very similiar to it's listing on the message index of that forum.
View the source code of the page presented by that call. You'll see the DIV tags and their class attribute which allows for formatting by CSS!

Optional elements of quickinfo calls

http://www.yourdomain.com/cgi-bin/bbs53x/webbbs_config.pl?quickinfo=<number>;type=<type>;newflag=1;teaser=1;category=1;newtelltale=1;

newflag specifies to display optional telltales
If set to '1' an additional DIV of either class 'qnew' or class 'qnone' is added to the quickinfo call's output.
NOTE: This DIV tag is EMPTY, you must format by CSS to make it visible! Applying a padding and a background image is a way to turn it into a little telltale indicating whether or not there are new message on the forum.
(a) <div class='qnew'> tag is displayed if new messages exist
(b) <div class='qnone'> tag is displayed if NO messages exist

teaser specifies to display a teaser
If set to '1' a teaser is added to the quickinfo call's output.
It's working very much the same as the teaser on the message index does. There are a couple of variables in the script to adjust the teaser. See the 'Advanced configuration' section a little down this page for more information.

category specifies the category of posts to display
Categories available:
'1' => topics only (limited thread starting posts)
'2' => responses only (thread starting posts excluded)
'3' => all posts (thread starting posts and responses)

newtelltale specifies to display an addtional time-based (new-) telltale
If set to '1' the 'newtelltale' shows next to each post listed in a quickinfo display. It's similar to the NEW telltale on message index pages and it indicates the status of each post listed whereas the 'newflag' mentioned before is a flag for the forum, not an individual message.

Formatting by CSS

All quickinfo calls return structured, but unformatted HTML. This way anybody is free to apply whatsoever formatting using CSS.
Different parts of the quickinfo call's output are wrapped in DIV tags each:

(a) <div class='qnew'></div >
Empty wrapper indicating new messages are available on the forum.

(b) <div class='qnone'></div >
Empty wrapper indicating NO new messages are available on the forum.

(a) <div class='teaser'>......</div >
DIV wrapping the teaser of each message shown in quickinfo output.

Example:
If you want to create a simple HTML testpage and implement a quickinfo call either by SSI or JavaScript, make sure to use the default CSS file coming with the scripts for the testpage. The following line should be pasted into the <head></head> section of the page:

<link rel="stylesheet" href="/webbbs/css/webbbs.css" type="text/css">

Of course you may want to tweak the corresponding CSS for your site's needs. Just copy and paste from somewhere at the end of webbbs.css to site.css or any other CSS file you use for your site.

Configuration variables to be set in the scripts

There are a couple of special variables driving quickinfo calls. They should be added either to webbbs_settings.pl or section(3) of the entry script. For details please look up the details by following the links:

Enable/Diable quickinfo calls:
$AllowQuickinfo

Add additional HTML to quickinfo call's output:
$qinfo_opencode
$qinfo_closecode

Tweak the default output:
$qinfo_linktarget
$qinfo_subject_length
$qinfo_subject_only
$qinfo_nolinks

Enable and tweak teasers on quickinfo calls:
$qinfo_teaserlength
$qinfo_teaserimage

Example calls for various purpose

Here are a few examples for quickinfo calls to Tetra-WebBBS. They may serve you as a starting point to figure out what might be useful for your site. Please note that the examples below must be corrected to point to *your* webbbs_config.pl file on *your* server/domain.
The examples provided produce different output each. Check the docs above for details.

(a) Some simple direct quickinfo calls for HTML output.
You may use these calls as the source for an IFRAME for example.
Showing the most recent message:
http://www.yourdomain.com/cgi-bin/bbs53x/webbbs_config.pl?quickinfo=1;type=html;
Same thing, but showing a random message:
http://www.yourdomain.com/cgi-bin/bbs53x/webbbs_config.pl?quickinfo=rand;type=html;

(b) Some examples to be used for SSI on any SSI-parsed static HTML page.
NOTE: don't forget to include the webbbs.css file in the head section of the page - see above for details!
Display the most recent message AND a telltale for new messages

<!--#include virtual="/URI/to/webbbs_config.pl?quickinfo=1;type=html;newflag=1" -->

After having defined $qinfo_teaserlength the following will show a teaser:

<!--#include virtual="/URI/to/webbbs_config.pl?quickinfo=1;type=html;newflag=1;teaser=1" -->

(c) Quickinfo calls using JavaScript.
The following example is just like the SSI example, only we're using some JavaScript to display the quickinfo call's output.
On any page of your site just make sure you've added the appropriate CSS (for example as is suggested above using the webbbs.css file).
To show the most recent post and a telltale:

<script src='/URI/to/webbbs_config.pl?quickinfo=1;type=js;newflag=1' type='text/javascript'></script>

Same thing but showing the teaser as well. (Don't forget to define $qinfo_teaserlength !)

<script src='/URI/to/webbbs_config.pl?quickinfo=1;type=js;newflag=1;teaser=1' type='text/javascript'></script>

(d) Quickinfo calls embeded in PHP pages.
The following is an example just like the two above, only we're embedding the calls into some PHP file.
Display the most recent message AND a telltale for new messages

$output = shell_exec("/full/path/to/webbbs_config.pl 'quickinfo=1;type=html;newflag=1' ");
echo "$output";
?>

Same thing but showing the teaser as well. (Don't forget to define $qinfo_teaserlength !)

$output = shell_exec("/full/path/to/webbbs_config.pl 'quickinfo=1;type=html;newflag=1;teaser=1' ");
echo "$output";
?>

Note:
Getting this to work you MUST specify the environmental variable $ENV{'SCRIPT_NAME'} in your config.pl file which is called in the PHP code above. Example:

$ENV{'SCRIPT_NAME'} = '/URI/to/webbbs_config.pl';

If you don't know what is meant by this, then simply take the bold part of this example for the "/URI/to/webbbs_config.pl':
http://www.yourdomain.com/URI/to/webbbs_config.pl.

Classified Cars! Classified Cars!

Peters Daily Blog

WebBBS Documentation Index