PerlB

Following is the original WebBBS documentation. It may not be entirely accurate as it applies to PerlB. Please post about anything you think needs revision on the support board.

PerlB (WebBBS) Documentation

  1. FILES NEEDED
  2. VARIABLES
  3. RUNNING FORUMS IN LANGUAGES OTHER THAN ENGLISH
  4. CHANGING DBM (DATABASE) MODULES
  5. DISPLAYING “QUICK INFO” ABOUT YOUR FORUM(S) ON OTHER PAGES
  6. E-MAIL NOTIFICATION LISTS
  7. WEBBBS SECURITY
  8. USING WEBADVERTS WITH WEBBBS
  9. USING SSI TAGS IN HEADER AND FOOTER FILES

FILES NEEDED

The files that you need are as follows:

webbbs_basic.pl, webbbs_form.pl, webbbs_index.pl, webbbs_misc.pl, webbbs_post.pl, webbbs_profile.pl, webbbs_read.pl and webbbs_rebuild.pl: These are the “pieces” of the main program file. You don’t actually need to do anything with them; the appropriate segments will be called by the configuration script depending upon what specific action the script is supposed to perform.

webbbs_settings.pl: The “master” configuration file. In this file, you define the bulk of your configuration settings.

webbbs_config.pl: This is the specific configuration file for a particular board. In this file, you define those configuration variables unique to the particular board in question. This is also the file that you will execute. (You can easily maintain multiple discussion boards just by keeping separate config files for each. You do *not* need multiple copies of the main script files.)

webbbs_text.pl: A simple file containing the text of messages included on various pages by the program. They’re separated to make alteration or translation a bit easier.

“smilies” folder: This folder just contains some simple “smily” graphics that you can use, if you like, with WebBBS.

Basic setup is very simple. You need only to create a directory in which the script will store the message and other data files, and make sure that it is set world-writable. The script files can be put wherever you like (or wherever your system administrators require them to be).

The configuration file should, of course, be set executable. Make sure that the first line of the script matches the location of your system’s Perl interpreter. As well, a number of variables need to be defined. Note that *only* the variables in the configuration script and in the first section of the “settings” script need to be changed from their default values. If you’re not sure you know what you’re doing, don’t even bother looking at any other of the configuration settings until you have your file paths and e-mail variables defined correctly, and have verified that the script is indeed functioning!


VARIABLES

ESSENTIAL VARIABLES

(A) The essential variables are as follows:

In the config script itself, first make sure that the “require” line is defined with the correct path to your webbbs_settings.pl file. Then define the following variables:

$dir: The absolute path (minus a trailing slash) of the directory in which all the WebBBS data files are to be stored. This directory must be set world-writable, or else WebBBS won’t be able to use it! Your data directory, by the way, should *not* be located within your CGI-BIN directory. Even if your server allows it — which many don’t — locating a world-writable directory and world- writable files within your CGI-BIN is an unacceptable (and unnecessary) security risk.

$cgiurl: The URL address of the WebBBS configuration script itself. (In other words, it should contain the URL to be referenced to run the script!)

$boardname: The name of your specific discussion board. THIS VARIABLE MUST BE DEFINED FOR COOKIES AND CERTAIN OTHER SCRIPT FUNCTIONS TO WORK PROPERLY! If you don’t want the board name to print, set $printboardname as 0. Do *not* simply leave $boardname undefined.

$shortboardname: You can optionally define here a shorter version of your forum’s name, to be used in the subject lines of any e-mail notices sent out announcing new posts. (If this variable is not defined, your forum’s full name will be used.)

Under the third heading (“Define variables you want changed from webbbs_settings.pl”), simply re-define any of the variables from the “settings” script which, for whatever reason, should be different for this particular board. (If you’re only *running* one forum, obviously, this is a moot point. But if you’re running multiple boards, while many settings will be consistent from one to another, other settings, such as the forum name, will be different in each case.)

Once you’re done with the webbbs_config.pl script, you’ll need to define the following variables in webbbs_settings.pl:

$scripts_dir: This is the directory in which all of the script files reside. (They don’t *have* to all be in a single directory, but it’s certainly simpler if they are.) As you did when you defined the data directory, be sure to define this variable with a *path*, and not with a URL. Note that this directory, unlike the data directory defined in your config script, does *not* have to be world-writable.

$webbbs_basic, $webbbs_form, $webbbs_index, $webbbs_misc, $webbbs_post, $webbbs_profile, $webbbs_read, $webbbs_rebuild and $webbbs_text: These variables define the specific locations of the various “pieces” of the WebBBS script. If they all reside in the directory defined in $scripts_dir, and have not been renamed, then you do *not* need to alter the default definitions.

$mailprog: This variable defines what, if any, mail program is to be utilized by the script. It can be defined in one of three ways. The prefered definition is the absolute path to the “sendmail” program, at least if you’re on a server that *has* it. (NT servers do *not*.) Note that this is *not* the same as the “mail” program, and has absolutely nothing to do with Matt Wright’s “formmail” or any other CGI script. If your system doesn’t have “sendmail,” you can instead define the variable as “SMTP” to instruct WebAdverts to access your server’s mail server directly. Finally, if it’s available to you, you can utilize Libnet’s “Net::SMTP” Perl module by defining the $mailprog variable as “libnet”. If you simply don’t want the various e-mail notification functions activated, leave this variable unassigned.

$WEB_SERVER & $SMTP_SERVER: If you’re using a direct SMTP interface, you can define either or both of these variables with the relevant server names. If you leave them undefined, the script will attempt to determine for itself what the names should be. If you’re using sendmail, of course, these variables are irrelevant.

$admin_name: The name of your board’s administrator. It will appear at the bottom of script-generated pages with an e-mail link (using $maillist_address, below).

$maillist_address: The address you wish to use for e-mail related to your BBS. The “@” character in your address must be “escaped” with a backslash (e.g., “scripts\@awsd.com ”). Note that this variable should be assigned even if you don’t enable the various e-mail notification functions, since the maillist address is also shown on some of the BBS’s admin pages to let people know how to contact you if they have any problems.

$notification_address: If you send out e-mail notices, they will be addressed “From:” the $maillist_address above, and “To:” the address defined here. If you don’t want to receive copies of all the notices, define this with a dummy value. If you *do* want to receive copies, define it with a real address (such as your administrative address already defined above). Please note that by “dummy value” I do *not* mean that you should send the notices to someone else’s domain! Set up an address within your own domain which automatically deletes incoming mail!

$ReplyToAddress: If you leave this variable undefined, the “Reply-To:” field in e-mail notifications will be the same as the “From:” field (i.e., it will contain the address defined in $maillist_address). If you prefer that direct responses to the mailings be sent to a different address — for example, to an auto-responder which will mail back a “Please don’t respond via e-mail, but respond on the forum!” message — define the appropriate address here.

$email_list: If you don’t want to set up any sort of e-mail list to notify interested parties of new posts, simply leave this variable unassigned. If you have a relatively low-volume board, and want to allow people to get e-mail copies of any messages immediately as they are posted, set it to “1″. If you want to set up a digest-style notification list, set it to “2″. Note that the digest mailings are *not* handled by the WebBBS script itself; if you want to send out that sort of notification, you’ll also need to set up the separate WebBBS Digest script available from the WebBBS download page.

$private_list: If you want e-mail notices to be sent out, but *don’t* want just anyone visiting your board to be able to subscribe, set this variable to 1. (Setting this variable to 1 but leaving $email_list set to 0 is an easy way to ensure that the administrator gets copies of each post, even if no one else does.)

$HeaderOnly: If you set this variable to “1″, any e-mail notifications will contain only the header information, and not the main body of the post. This is handy if you want to be able to let people know when new messages are posted, but still want them to have to come to the BBS itself to *read* thos messages. Note that this setting will not effect the manner in which digests are sent out; if you’re using the digest option, the e-mail notices will *always* contain the full text of the messages posted.

If you’re utilizing the direct SMTP interface rather than the “sendmail” program, uncomment the “use Socket” line in the config file. (In other words, remove the initial hash mark symbol.) Otherwise, just leave it alone.

If you’re using the “Net:SMTP” module, uncomment both the “use Net:SMTP” line and the “use Socket” line.


OPTIONAL VARIABLES

B) The optional configuration variables are as follows:

As noted above, the rest of the variables do *not* have to be altered from their default values. If you’re not quite sure what you’re doing, don’t change any of them until you actually have the script running, and are ready to begin “fine-tuning” it.

$SearchFriendlyURLs: If this variable is set to 0, the script will generate URLs using standard QUERY_STRING attachments; thus, your forum’s messages will *not* be indexed by search engines. This is to be preferred in most situations, especially if your forum isn’t set to keep messages for a long period. If the variable is set to 1, the script will utilize “search engine friendly” URLs, which *can* be indexed by search engines.

$DBMType: This variable determines how the DBM (database) file used for storage of index information will be accessed. Most users can leave it set to 0. If the script can’t open the database file, though — and especially if you receive “Inappropriate file type or format” errors — try setting it to 1. This will replace the basic tie() command with a version of the command specific to the DB_File module, which produces the above error message. If all else fails, set $DBMType to 2, and instead of tie() commands, the more generic (but less efficient) dbmopen() commands will be used.

The following four variables allow you to add “spell checking” functionality to your forum. This is done by interfacing WebBBS with the SpellChecker.net system. If you choose to use this system, you’ll need to register. (The registration is *not* free.) You’ll also need to download and install a few extra files; those files are of course available from and documented on the SpellChecker.net Web site, at http://spellchecker.net . Any questions about the files and their setup should be directed to the folk at SpellChecker.net.

$SpellCheckerID: Define this variable with the ID number you receive from SpellChecker.net.

$SpellCheckerPath: This variable should be defined with the path to your “sproxy.cgi” CGI script obtained from SpellChecker.net. Note that this “path” isn’t a true path, as are the paths elsewhere in the WebBBS configuration, but rather, is the path portion of the file’s URL. In other words, if the URL of the file is “http://foo.com/cgi-bin/sproxy.cgi,” you need to define this variable as “/cgi-bin/sproxy.cgi.” It’s a bit confusing, yes, but I have no control over it. ;)

$SpellCheckerJS: This variable should be defined with the URL (*not* the path!) of the “spch.js” JavaScript file obtained from SpellChecker.net.

$SpellCheckerLang: Define here the default language to be used in the spell checking. (For most WebBBS users, that will of course be “en” for English.)

The next few variables concern “user profiles,” which you can, if you like, allow your forum’s visitors to create. These profiles will be more-or-less permanent features of your forum. A particular user’s profile will be accessible from any messages he posts, and will allow him to tell other visitors a bit more about himself than is evident from his messages. A user can update his profile whenever he likes. The administrator can also edit or delete profiles easily, as all profiles are accessible from the administrative script’s “poster stats” menu option.

$UserProfileDir: If you want to allow your visitors to create user profiles, define here the path (not the URL) of the directory in which the profile files should be stored. This directory does not need to be — and in fact should not be — accessible to Web browsers.

$ProfileColumns: This variable simply defines the number of columns to be used when displaying the list of available profiles on the forum.

$UserProfilePicsDir: If you allow your visitors to upload graphic images to your server to be included with their profiles, define here the path of the directory in which the images should be stored. This directory, of course, should be accessible to Web browsers! If you do *NOT* want to allow users to upload files to your server, simply leave this variable undefined. You do *not* have to allow file upload in order to allow your users to create profiles

$UserProfilePicsURL: If you allow your visitors to upload graphic images to your server to be included with their profiles, define here the URL corresponding to the directory defined in $UserProfilePicsDir.

$MaxGraphicSize: If you’re allowing file uploads, define here the maximum size (in kilobytes) of the graphic files that can be uploaded.

$ListAllProfiles: If this variable is left set to 0, then the only profiles which will be included in the list seen by visitors are profiles for people who’ve actually posted at least one message on the forum. (This can be useful, especially if you have several different forums sharing a single profiles directory.) If you prefer to have *all* profiles included in the list, even if no messages have been posted under the user name, then set this variable to 1.

$ListEmptyProfiles: If this variable is set to 1, then all profiles allowed by the $ListAllProfiles setting will be included in the “View User Profiles” list. This will of course include some profiles which contain nothing but a user name and (perhaps) an e-mail address. If you want the list to be a bit more useful, you can set this variable to 0. If you do, then “empty” profiles – those which contain nothing but a name and e-mail address — will *not* be included in the list. This can be especially helpful on forums where profiles and e-mail addresses are required, since the percentage of “empty” profiles will typically be rather high. (Note that profiles are still accessible from individual messages; this variable only determines whether or not they are listed in the “View User Profiles” list.)

If you wish to allow users to upload images with their messages, you need to define the following two variables. Note that it is *strongly* recommended that you not do so! Even visitors without Web sites of their own can upload pictures to any of a number of public servers set up for the purpose. Allowing your visitors to upload an effectively unlimited number of graphic images to your server as they post messages could result in problems as your disk space and bandwidth usage increase accordingly.

$UserPicsDir and $UserPicsURL: These variables are similar to the $UserProfilePicsDir and $UserProfilePicsURL variables described above, except that they define where pictures uploaded with messages, rather than pictures uploaded with profiles, are to be stored.

The next group of variables define how your forum will look and act; this is where most of the customization of your forum’s “personality” will be done.

$MetaFile: The path to a text file containing any HTML code (META tags, etc.) to be inserted within the section of the pages produced by the script.

$HeaderFile & $FooterFile: The paths to text files containing HTML code to be placed immediately following the tag and at the very end of the BBS index page. These are included to allow you an easy way to give your WebBBS index page the same “look” as the rest of your site’s pages. This header and footer are used only on the main message index page.

$MessageHeaderFile & $MessageFooterFile: The paths to text files, similar to the above, containing code to be placed at the top and bottom of the BBS message pages when the forum is *NOT* viewed with frames. You can use the same header and footer on these pages as you use on the index page, or use different ones, or use none at all. This header and footer are used on all individual message pages, configuration pages, and administrative pages. (In other words, they’re used on everything *except* the main message index page.)

$FramedHeaderFile & $FramedFooterFile: These variables serve the same purpose as the $HeaderFile and $FooterFile variables, except that the header and footer defined here will be used on the index page when the forum is viewed using frames. If you’re using horizontal frames, there will usually be no need to define these variables, since the header and footer files used on unframed pages will most likely work just as well on a page seen in the upper frame. However, if you’re using vertical frames, you might want to structure your header and footer differently depending upon whether they’re seen on an unframed page or in the left-hand frame.

$FramedMessageHeaderFile & $FramedMessageFooterFile: These variables serve the same purpose as the $MessageHeaderFile and $MessageFooterFile variables, except that the files defined here will be used on secondary pages when the forum is viewed with frames. There are two separate pairs of variables, so that you can (for example) have your message pages display the same header as your index page when frames are not in use, to allow consistency of appearance, and yet *not* have that same header information repeated in both frames when frames actually are in use.

$SSIDebug: WebBBS will attempt to interpret any SSI tags contained in your header and footer files. If you set $SSIDebug to 1, WebBBS will print “SSI TAG NOT SUPPORTED” in place of any SSI tag (or anything it *thinks* is an SSI tag) that it can’t interpret. This will allow you to easily spot any problems in your header or footer files. For normal operation of your forum, however, you can leave this variable set to 0, to suppress such messages.

$bodyspec: Any attributes (BACKGROUND, BGCOLOR, TEXT, etc.) which should be assigned to the tag in message posts. Do *not* include in this variable a full tag; include only the contents *of* the body tag.

$fontspec: Any attributes (FACE, etc.) which should be assigned to a page-wide tag. Table cells will also be defined with the same tag, so that the page presents a uniform appearance even in Netscape Navigator, in spite of the fact that that browser is too stupid to realize that global specifications *should* apply inside tables as well as outside of them.

$navbarspec: The attributes (BORDER, BGCOLOR, etc.) to be used in the table containing the “navigation bar” at the tops and bottoms of your pages.

$navbarfontspec: Font specifications specific to the nav bar.

$navbaropen and $navbarclose: In these variables, you define any characters or code (such as brackets) which you want to have “surrounding” the entries in the navigation bar at the top and bottom of the WebBBS pages.

$tablespec: The attributes (BORDER, BGCOLOR, etc.) to be used in the tables used by the script for the “post form” boxes.

$tablefontspec: Font specifications specific to the above tables.

$PrepostMessage: If you want any special instructions or other information to appear above the “post new message” form, simply define it here.

$PreEmailMessage: If you’re utilizing the “blind e-mail” feature (described below), any text defined here will appear above the “send e-mail” form.

$ListBullets: By default, WebBBS (as of version 4.20) creates its index listings with “unbulleted” lists, using the and HTML tags. If you prefer “bulleted” lists, set this variable to 1, and the script will instead use the and tags.

@SubjectPrefixes: An optional list of “mandatory” subject prefixes. If you’ve defined anything here, those posting on your forum will have to pick one of your options, which will precede whatever they enter as the subject of their message. For example, if you want an easy way to tell business-related from personal messages on your forum, you might use “@SubjectPrefixes=(‘Business:’,'Personal:’);” so that all message subjects end up beginning with either “Business:” or “Personal:”.

$MessageOpenCode and $MessageCloseCode: These variables should be defined with any HTML code you want to appear before and after the text of messages. They can be used, for example, to place message text within tags, or to highlight the text with a different font and/or color than is used on the rest of your site. $MessageCloseCode should, of course, contain “closing” tags for whatever $MessageOpenCode opened.

$NewOpenCode and $NewCloseCode: These variables should be defined with any HTML code that you want to have appear before and after “new” messages in the index listings. By default, a red “NEW:” will show up preceding the message subject in the index listing. You might want to change it to call a graphic image, for example.

$AdminOpenCode and $AdminCloseCode: Very similar to the above, these variables should be defined with any HTML code that you want to have appear before and after admin posts in the index listing.

$UseLocking: Under most circumstances, this variable should be defined as 1. Set it to 0 only if, for whatever reason, your server doesn’t support the flock() command. (If this variable is set to 0, a semaphore-based file locking will be used instead of flock(); while it works reasonably well in most situations, it isn’t nearly as efficient.)

$RefreshTime: The number of seconds that the various “admin” screens (“Your message has been posted,” etc.) will wait before sending a visitor back to the main index. If you’re displaying banners on the pages, you’ll probably want to set this fairly high; otherwise, set it low so that your visitors don’t have long waits. If you define this variable to 0, the pages will *not* auto-refresh at all.

$UseFrames: This can either be set to “horizontal” (or “horiz” or “h”) if you want an upper frame for the message index and a lower frame for message texts, set to “vertical” (or “vert” or “v”) if you want side- by-side frames, or left undefined if you don’t want to use frames at all. (Even if your forum is framed by default, a “remove frames” option will always be available for those visitors who prefer not to use them.)

$AllowFramesChoice: This variable is used to determine what sort of frames (horizontal or vertical) your visitors will use if they opt for frames on a forum which is normally (by default) unframed. (If $UseFrames is set, this variable will automatically be set to the same value.) If you leave both this variable and $UseFrames undefined, no option will exist for visitors to utilize frames when viewing your forum. However, there is absolutely no reason to so restrict your visitors. Frames allow for easier navigation, and also help to reduce your site’s bandwidth and server resource consumption. Even if you don’t want to use frames on your forum by default, you really should at least allow those visitors who like them, to use them.

$BBSFrame: If you’re using WebBBS with frames within another frameset, you’ll want to define this with the name of the frameset in which WebBBS is being displayed. (The default definition of “_parent” might also suffice, depending upon your setup.)

$WelcomePage: If you’re using WebBBS with frames, you can define this variable with the URL of a page you want to appear initially in the WebBBS “message” window (which otherwise will initially be blank).

$Moderated: If you set this variable to 1, any new posts will be put “on hold” until approved by the administrator, rather than being posted publicly immediately. Note that in order to run a moderated board, you *must* have the administrative script, as without it, you’d have no way of approving the posts!

$SearchURL: Generally speaking, this variable should be left undefined, as the search facilities built into WebBBS are quite sufficient for most any purpose. However, if you’ve got a site-wide search facility which includes the message content of your forum(s), and you prefer that all searches be conducted through it, you can define this variable with its location. Anyone clicking on the “Search” option on a WebBBS page will then be taken to *that* search form, rather than the one generated by WebBBS itself.

$TopNPosters: If this is defined (with a number), visitors to your bulletin board will be able to access a list showing who’s posted the most messages.

$Navbar_Links: You may use this hash variable to define the names and URLs of “extra” links you’d like to have appear in the main index page navigation bar. These could be links to FAQs or policies pages, a link to an archive board, a link back to your main page, or anything else you find relevant. You can specify a TARGET destination for the link by appending it to the URL, separated by a “pipe” (|) character. If you do *not* specify a TARGET, the link will open in the window used for display of messages. The example below would put two new links on the navbar: a link to a “welcome” page, which would be loaded (by default) in the message window, and a link to a “help” page, which would be loaded in the full browser window.

%Navbar_Links = (
'Welcome','welcome.html',
'Help','help.html|_top'
);

$SepPostFormIndex and $SepPostFormRead: These variables determine whether “post message” forms will appear on the main index page and/or the individual message pages, respectively. Values of 0 instruct the script to include the forms as part of the pages; values of 1 instruct it to have those forms appear on pages by themselves. If you’re using frames, these variables are automatically set by the script to 1, to ensure that the post forms appear in full windows and can thus be more easily used.

$DefaultType: By design, WebBBS index displays default to a simple chronological display. If you prefer a different style, define it here. If you’ve enabled alphabetical sorting (as explained below), then the available options for $DefaultType are “Alphabetically” and “Alphabetically, Reversed”. Otherwise, the available options are “Chronologically”, “Chronologically, Reversed”, “By Threads”, “By Threads, Reversed”, “By Threads, Mixed”, “By Threads, UBB”, “Compressed”, “Compressed, Reversed”, “Compressed, Mixed”, “Compressed, UBB”, “Guestbook-Style”, “Guestbook-Style, Reversed”, “Guestbook-Style, Alphabetically”, “Guestbook-Style, Alphabetically, Reversed”, “Guestbook-Style, Compressed”, “Guestbook-Style, Compressed, Reversed”, “Guestbook-Style, Compressed, Mixed”, “Guestbook-Style, Compressed, UBB”, “Guestbook-Style, Threaded”, “Guestbook-Style, Threaded, Reversed”, “Guestbook-Style, Threaded, Mixed”, and “Guestbook-Style, Threaded, UBB”.

$DefaultTime: This variable sets the default for the age of messages shown in the index list. If left unspecified, the index will display messages posted within the past two weeks. It can be defined with whatever value you like, such as “2 Day(s)”, “3 Week(s)” or even “10 Year(s)”. Note that the format of the definition must match that seen on your forum index page.

$printboardname: If this variable is set to 1, the board name defined above will be included at the top of the script-generated pages. If the variable is set to 0, it won’t be. This allows you to avoid duplication if you’re using a graphic image in your header, for example, as a title.

$DateConfig: A string defining the format in which you want dates to appear on the board. The following codes are available:

%mo% = month (numeric)
%MO% = month name (as defined in webbbs_text.pl)
%dy% = day of month (numeric)
%DY% = weekday (as defined in webbbs_text.pl)
%yr% = year (two-digit) %YR% = year (four-digit)
%am% = either “a.m.” or “p.m.”
%sc% = seconds (two-digit)
%mn% = minutes (two-digit) %hr% = hour (12-hour clock)
%HR% = hour (24-hour clock)

So, for example, “%mo%/%dy%/%yr% %HR%:%mn%” would display dates as “7/22/00 15:30″; but “%DY%, %dy% %MO% %YR%, at %hr%:%mn% %am%” would display as “Wednesday, 22 July 2000, at 3:30 p.m.”

$IndexEntryLines: This variable defines the format in which the index should be displayed. Defining it as 1 gives each entry a single line, while defining it as 2 gives each entry two lines. (The latter is the better bet if you’re using a longer date format and/or displaying extra information such as IP addresses or view counts.) You can also define the variable as “news” in which case the index will be displayed in a tabular format similar to that utilized by many Usenet newsreaders.

$InputColumns & $InputRows: These variables define the size of the text input box for messages. The default size is 80 columns by 15 rows. The smallest allowable size is 25 columns by 5 rows.

$HourOffset: If you are in one time zone and your Web host is in another, you can use this variable to adjust the times shown for posts on your BBS. For example, if your server is located in the Eastern time zone, but you’re in the Pacific time zone, set it to “-3″.

$ArchiveOnly: If this variable is set to “0″ the board will function normally. However, if it is set to “1″ the message posting form will not appear either on the index page or on individual message pages. This allows you to set up a “read-only” archive board. With the administrative script (see below), of course, the administrator will be able to post even to a “read-only” board. This allows you to set up “announcement” boards to which you and only you can post. (See also $AllowNewThreads and $AllowResponses, below.)

$SingleLineBreaks: WebBBS automatically recognizes a double line break or an indentation (either a tab or multiple spaces) as the start of a new paragraph. If this variable is set to “0″ any single line breaks will be ignored. If it is set to “1″ any single line breaks will be converted to tags. The former option is usually preferable if most posts consist of straight text. If, however, those posting on your board frequently post itemized lists, you may want to use the second option, to allow more accurate formatting.

$AutoQuote: If this variable is set to “1″ the new text of a message will automatically be quoted in the message response input box. If it is set to “0″ the box will be empty.

$AutoQuoteChar: This defines the character you want used at the beginning of “quoted” lines.

$AutoHotlink: If you set this variable to 1, the script will attempt to “automatically” hotlink any URLs or e-mail addresses included in the body of a message. (As of WebBBS version 4.20, auto-hotlinking and the allowing of HTML code in messages are no longer mutually incompatible features. The two can now co-exist harmoniously.)

%SmileyCode: This variable defines a list of “codes” which will be automatically converted when they appear in the subject or body of a message. It can be used, for example, to replace certain ASCII “smilies” with graphic images. (Hence, the variable’s name.) The example below instructs the script to replace a variety of ASCII “faces” with appropriate graphics. Note that the backslash (\) must be “escaped”; in other words, if you want to use it, use two in a row instead of just one. (If you don’t, the script will not run.)

%SmileyCode = (
‘:)’,'<IMG src=”smile.gif” BORDER=0 ALT=”:)”>’,
‘:(‘,’<IMG src=”frown.gif” BORDER=0 ALT=”:(“>’,
‘:O’,'<IMG src=”oh.gif” BORDER=0 ALT=”:O”>’,
‘:D’,'<IMG src=”biggrin.gif” BORDER=0 ALT=”:D”>’,
‘;)’,'<IMG src=”wink.gif” BORDER=0 ALT=”;)”>>’,
’8)’,'<IMG src=”glasses.gif” BORDER=0 ALT=”8)”>’,
‘:b’,'<IMG src=”tongue.gif” BORDER=0 ALT=”:b”>’,
‘:\\’,'<IMG src=”ohwell.gif” BORDER=0 ALT=”:\\”>’,
‘>:(‘,’<IMG src=”angry.gif” BORDER=0 ALT=”>:(“>’,
‘:|’,'<IMG src=”indifferent.gif” BORDER=0 ALT=”:|”>’
);

%FormatCode: This variable is essentially identical to the above variable, except that (a) only text in the body of a message will be converted, and (b) the matching for this variable, unlike the matching for %SmileyCode, is case-insensitive. This variable is intended to be used to allow certain basic formatting functions to made available to your forum’s users, even if you don’t want to let them utilize HTML code directly. (The reasons for the two differences in the way the variables are handled are [a] the fact that you probably don’t want your visitors leaving formatting tags in their message subjects unclosed, and thus fouling up your index listings, and [b] the fact that while you probably don’t want “:d” and “:D” being treated by the script as the same thing, you most likely *do* want “[code]" and "[CODE]" treated the same.) The example below provides your visitors with the same formatting options available on the WebScripts support forums.

%FormatCode = (
'[b]','<STRONG>',
'[/b]','</STRONG>',
'[i]','<EM>',
'[/i]','</EM>',
'[list]','<UL>',
'[*]','<LI>',
'[/list]','</UL>',
'[quote]','<BLOCKQUOTE>',
'[/quote]','</BLOCKQUOTE>',
'[code]','<PRE>',
'[/code]','</PRE>',
'[center]','<CENTER>',
'[/center]','</CENTER>',
'[big]','<BIG>',
'[/big]','</BIG>',
'[small]','<SMALL>',
'[/small]','</SMALL>',
'[red]','<FONT COLOR="ff0000">',
'[/red]','</FONT>'
);

$NM_Telltale: An optional bit of text or HTML code to be appended to the subject of any message which does not contain any original body text. ("NM" is a standard Usenet/Internet abbreviation meaning "no message.")

$Link_Telltale: An optional bit of text or HTML code to be appended to the subject of any message containing a link URL. (On forums where many visitors use the "optional link URL" slot just to advertise their own Web sites, you'll probably want to leave this variable undefined.)

$Pic_Telltale: An optional bit of text or HTML code to be appended to the subject of any message which includes an image URL. (On forums where many visitors use the "optional image URL" slot just to include a banner or other advertisement of their own Web site, you'd obviously probably not want to define this variable. But on forums where the presence of pictures in a message is of actual significance, the "telltales" can be quite handy, allowing readers to quickly find the messages which include such pictures.

$ThreadSpacer: An optional bit of text or HTML code to be inserted between threads in the index listing. (It can be as simple as a tag.)

$GuestbookOpen and $GuestbookClose: Define here any HTML code which should be included before and after each message on the guestbook pages. These variables can be used, for example, to enclose each message in a table.

$DisplayEmail: If you leave this defined as 1, posters' e-mail addresses will be shown on the message display pages (if an e-mail address was provided, of course), and it will be possible for those reading messages to send private e-mails to the authors. If you undefine this variable, e-mail addresses will *not* be displayed. If you have many users who want to take advantage of the script's e-mail notification features, but *don't* want their e-mail addresses seen by others, this can be handy.

$BlindEmail: If you want to allow your visitors to e-mail each other, but also want to maintain the privacy of your visitors' e-mail addresses, set this variable to 1. Instead of displaying the e-mail addresses of posters, the script will display simple "send e-mail" links, and will act as a form-to-mail script to process the e-mail messages. This will allow visitors to e-mail the posters of messages without actually seeing their e-mail addresses. (Note that if $DisplayEmail is set to 0, this variable will do nothing, as no e-mail address or link will be displayed with messages or profiles.)

$ResolveIPs: If this variable is set to 1, posters' IP addresses will be resolved to domain names. If it is left undefined, they will not be resolved.

$DisplayIPs: If this variable is set to 1, posters' IP addresses or domain names, as determined by the setting of $ResolveIPs, will be displayed (when the index listing or message files are viewed) along with their names and e-mail addresses. (Note that they will be recorded in the message files for the administrator's reference, regardless of whether or not they're actually displayed to visitors.)

$DisplayViews: If this variable is set to 1, the script will keep track of and display in the index the number of times each message has been read. (With version 4.20, the database of view counts has been separated from the main index database, so keeping the view counting "turned on" should no longer significantly effect a busy forum's efficiency.) If it is set to 0, view counts will not be maintained. If it is set to 2, view counts *will* be maintained, but will not be displayed. (The latter setting might be handy, for example, if you want view counts to be available to the administrator, but not to just anyone who visits the forum.)

$UseCookies: If this variable is set to "0" (or commented out) the use of "cookies" will not be implemented. If it is set to "1" it will be. "Cookies" allow the board to recognize return visitors, keep track of messages posted since their previous visit, maintain their personal index display preferences, and automatically insert their names and e-mail addresses into the post forms.

$IsolateCookies: By default, if you have multiple forums, they will utilize "shared" cookies, so that once a visitor has entered his name and e-mail address on one, he won't have to enter them again on another. If you prefer that your forums not share the information, just set this variable to 1.

$SessionTime: Define here the time (in minutes) that a visitor must be absent from the forum before a "new visit" is considered to have begun. If this variable is undefined, or is defined with any value lower than five minutes or greater than 120, the script will use its default value of 30 minutes.

The remaining variables are primarily concerned with determining what your visitors are allowed to do on the forum.

$MaxMessageSize: This is the maximum size (in kilobytes) of messages which can be posted. The primary purpose of this variable is to prevent users from posting entire book chapters or the full text of long CGI scripts....

$MaxInputLength: This variable defines the maximum length of message subjects and author names.


RUNNING FORUMS IN LANGUAGES OTHER THAN ENGLISH

You can easily run a forum in a foreign language simply by translating the text strings in the webbbs_text.pl file. (A number of alternate versions of that file are already available on the WebScripts site.)

In addition to the text strings, you’ll also find a variable called %extrachars. By default, WebBBS will allow search terms to include any alphanumeric characters (A-Z and 0-9), as well as dashes, underscores, apostrophes and periods. If there are other characters you’d like to allow in search terms, such as “foreign” characters or particular symbols, you can define them in this variable, along with any relevant HTML “encoding” that may be used to display them

The following example illustrates how they should be defined:

%extrachars = (
‘&Aring;’,'Å’,
‘&aring;’,'å’,
‘+’,'+’
);

CHANGING DBM (DATABASE) MODULES

WebBBS uses DBM databases. There are a variety of DBM “modules” available, at least one of which should be available on any server on which Perl has been installed. As you’d expect, though, not all modules are created equal.

WebBBS will automatically utilize the best DBM module available on your server. Normally, this will be sufficient. However, if you notice your forum running very slowly, and/or notice that your database file(s) are incredibly large (hundreds of meg or more in size), you may want to contact your system administrators and see about having a better module installed. The Berkeley DB_File module, by the way, should be your first choice; it’s the most efficient of all the available choices. In fact, it’s so much better a choice than the other options, that the WebBBS admin script’s main index page will actually tell you if it’s not available, and recommend that you install it.


DISPLAYING “QUICK INFO” ABOUT YOUR FORUM(S) ON OTHER PAGES

You can display “quick info” — the date of the newest message and, if cookies are being utilized, the number of new messages — on other pages by calling the WebBBS script from an SSI tag.

On most systems, a tag such as the following should work:

<!–#exec cgi=”/webbbs/config.pl”–>

Some systems, though, don’t set the DOCUMENT_URI environment variable that WebBBS uses to tell whether it was called from an SSI tag. Most of those systems, though, also don’t recognize the fact that SSI tags aren’t supposed to be able to include QUERY_STRING data, so if you find the above tag trying to load the entire WebBBS index page, you’ll most likely find that the following tag will work instead:

<!–#exec cgi=”/webbbs/config.pl?quickinfo”–>

You can also create static links, if you like, directly to the most recently-posted message on each of your forums. Simply link to “config.pl?review=0″ instead of directly to “config.pl”; when followed, the link will take you or your visitor directly to the forum’s newest message.


E-MAIL NOTIFICATION LISTS

Although WebBBS can handle fairly large e-mail notification lists, you’ll probably find as your board gets busier that your subscribers don’t like getting lots and lots of individual message notifications. If you’re running a board with heavy traffic, you should probably switch from the basic “as messages are posted” notification scheme to the more efficient digest setup. (As noted above, the digest mailings are *not* sent out by WebBBS itself; they are handled through the separate digest script, available from the WebScripts site, which can easily be set via cron to run automatically at regularly-scheduled intervals.)


WEBBBS SECURITY

Though WebBBS does not yet directly incorporate password protection, it works quite well with server-based protection. All you need to do is locate your configuration file in a password-protected directory. And if your security system sets the “REMOTE_USER” environment variable, as most do, you can even set WebBBS to require that users post under their login IDs, thus preventing them from posting under someone else’s name.

Even if you’re not password-protecting your BBS, you should still either password-protect your data directory, or locate it outside of your Web space. There’s no need for the directory itself to be accessible to the public, and you’re probably better off if it isn’t. (NOTE that the directory *does* need to be set world-writable, as stated above; what I mean here is that it doesn’t need to be physically located within your Web space. The script needs to be able to read its contents, but your visitors don’t!)

If you want to set up a board which anyone can read but to which only a few designated people may post, you can easily do so by setting up two configuration files for the same data directory. One would be publicly accessible, but defined as “read only”; the other would allow posting, but be accessible only to those with appropriate IDs and passwords.


USING WEBADVERTS WITH WEBBBS

The easiest way to display banners — whether you’re using WebAdverts or any other banner display program — is to include the same sort of banner calls in your header or footer files as you’d include on any normal HTML page. However, if you really want to, you *can* instruct WebBBS to call WebAdverts directly for banner displays.

To do so, you will need to define the “require” line in the “insertadvert” subroutine at the end of the WebBBS configuration file to point to your ads.pl (WebAdverts display configuration) script.

Once that is done, you can include banners anywhere in your header or footer files simply by inserting the comment line “ ” wherever you want a banner to appear.


USING SSI TAGS IN HEADER AND FOOTER FILES

The header and footer files utilized by WebBBS can include SSI tags; the script is able to correctly parse most commonly-used tags.

Specifically, the following SSI tags can be used:

“ECHO DATE_LOCAL” and “ECHO DATE_GMT” tags can be used in your header and footer files to display the date and time. However, at this time, WebBBS does *not* support those tags’ configuration options, so all times will be displayed in the default format. “ECHO ” tags can be used to display any standard environment variables.

“EXEC CGI” tags are supported, and should work properly to display the output of any CGI scripts, no matter what language those scripts are written in; however, “EXEC CMD” tags are *not* supported.

(WebBBS utilizes the “LWP::Simple” module for running of other CGI scripts, by the way. This should present no problems, as that module is part of the standard distribution of Perl, and should be available to you.)

“INCLUDE FILE” and “INCLUDE VIRTUAL” tags should both work properly, to insert the contents of the referenced files into your headers or footers. However, if such tags reference “.pl” or “.cgi” files, the tags will be treated as “EXEC” tags rather than as “INCLUDE” tags, as they are by far too many servers, anyway.

Finally, “PRINTENV” tags can be used, if you feel the need to print out a list of all environment variables.

This documentation assumes that you have at least a general familiarity with setting up Perl scripts. If you need more specific assistance, check with your system administrators, consult the WebScripts FAQs (frequently-asked questions) file , or ask on the WebScripts Forums .


Home   Demo   Documentation   Download Installation   Support