DOCUMENTATION WebBBS 2.25 by Darryl C. Burgdorf (burgdorf@awsd.com) http://awsd.com/scripts/webbbs/ =========================================== WebBBS is, as the name implies, a Web-based bulletin board. Unlike most other such boards, though, WebBBS stores messages as simple text files and creates HTML pages "on the fly." This means that the message index can be tailored by the user based on date and/or subject (via built-in keyword search capability), and can be viewed as either a chronological or a threaded list. It also means that administration is a breeze! WebBBS supports automatic quoting of message text and e-mail notification of those who want to know immediately when a new message has been posted. It also offers an archive-only option and "cookie" support! =========================================== The files that you need are as follows: webbbs.pl: This is the main program file. You don't actually need to do anything to it; in fact, you don't even have to execute it. config.pl: This is the configuration file. Most everything you need to change or modify is contained here. This is also the file that you will execute. (Things are set up this way so that you can effectively maintain multiple discussion boards just by keeping separate config files for each.) Basic setup is very simple. You need only to create a directory in which the script will store the BBS files, and make sure that it is set world-writable. All the actual data files used by the script will be created for you. The main program can be put wherever you like. (Just be sure that the configuration file "requires" it correctly.) The configuration script can be placed either in the BBS directory itself (as "index.cgi") or in your CGI-BIN directory. Since the configuration file is what you will reference from your Web browser, the former option allows for "better" URLs (for example, something like http://www.foo.com/bbs/index.cgi). However, some systems require that CGI scripts be in the CGI-BIN directory. As noted above, the WebBBS configuration file, and not the WebBBS program itself, should be executed. 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 and that the "require" line points correctly to your main WebBBS script. As well, the following variables need to be defined: $dir: The absolute path (minus a trailing slash) of the directory in which all the WebBBS files are stored. This directory must be set world readable and world writable! $cgiurl: The URL address of the WebBBS configuration script. If your server setup allows it, it is probably most efficient to name this file "index.cgi" (rather than the default config.pl) and put it in the same directory ($dir) as the rest of the WebBBS files. $bodyspec: Any attributes (BACKGROUND, BGCOLOR, TEXT, etc.) which should be assigned to the tag in message posts. $HeadLinesFile: An optional text file containing any HTML code to be inserted within the section of the pages produced by the script. This could include, for example, META tags. $HeaderFile & $FooterFile: Optional 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: Optional text files containing HTML code to be placed immediately following the tag and at the very end of the BBS message pages. 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.) $DefaultType: By design, WebBBS index displays default to a simple chronological display. If you prefer the default to be a threaded listing, set this variable to "By Threads" instead. If you prefer the mixed-order listing of most Web-based bulletin boards, set it to "By Threads, Reversed". If you want only the first message of each thread listed on the index page, set it to "Compressed". $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 week. Valid values are: "Day" "Two Days" "Week" "Two Weeks" "Month" and "Archive". The latter instructs WebBBS to display *all* messages. $boardname: The name of your specific discussion board. $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. (As a side note, if you move files to a new directory from your active board to set up such an archive, be sure to use the UNIX "mv" command rather than the "cp" command. This will insure that the file modification dates are not altered, so that searches by date will work!) If you enable the admin functions (see below), 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. $AllowHTML: If this variable is set to "1" people posting messages will be able to embed HTML tags (hyperlinks, image references, formatting commands, blinking text, etc.) in their messages. If it is set to "0" they will not be able to do so. Be aware that allowing embedded HTML virtually invites abuse of your bulletin board. Setting the variable to "2" will allow any HTML codes to be displayed in the message rather than being either interpreted or stripped. This can be handy, for example, if the subject of your BBS is how to code HTML. SSI commands will *never* be interpreted by the script. If this variable is set to "2" they will be displayed along with any HTML tags; otherwise, they will simply be stripped. $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. $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. $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. IN ORDER FOR "COOKIE" SUPPORT TO WORK, you must first install Matt Wright's "cookie.lib" (available from ). If you're not using "cookie" support, comment out the "require" line in the configuration script. Otherwise, make sure it points to the correct location on your system of Matt's "cookie" library. $UseAdmin: If you set this variable to "1" you'll be able to access the admin function and delete any or all posts in bulk. (See below.) It will also allow you to post to archive ("read-only") boards. If you leave variable unassigned, the admin function will be disabled. (This will *not* prevent you from using the automatic "reaper" function.) IMPORTANT NOTE: If you activate the admin function, be sure to load the admin page immediately and set a password! If you don't, someone else might come along and do it *for* you.... $Max_Days & $Max_Messages: By setting one or both of these variables, you instruct WebBBS to automatically purge message files for you. (This is the "reaper" function mentioned above.) For example, if you set $Max_Days to "7" any messages which have been sitting idle for over a week will be deleted, and if you set $Max_Messages to "200" you will never have more than 200 messages in your index. If you set both variables, older messages will be deleted first, and then more recent messages will be deleted if necessary to bring the total number within your prescribed limits. $ArchiveDir: If instead of being deleted, you want "expired" messages to be moved into another directory (for example, for use in a "read-only" archive board), define this variable with the full path to the directory in question. This will replace the "reaper" function with a "harvester" function, which will remove the old messages from your active board by moving them rather than by deleting them. $AllowUserDeletion: Set this to "1" if you want users to be able to include a password with their messages which will allow them to come back and delete them on their own. Leave it undefined if you want them to be stuck with what they posted. $AllowEmailNotices: Set this to "1" if you want users to be able to request e-mail notifications whenever someone responds to their messages. Leave it undefined if you want to require them to actually visit the BBS again to find out. This ONLY defines whether or not people can request automatic notifications of responses to their own posts, and is distinct from the $email_list variable (below), which defines what, if any, new post "subscription" capability your board will support. Like the other e-mail functions, the automatic notification of responses will be disabled if you do not define the $mailprog variable. $AllowPreview: Set this to "1" if you want your users to be able to "preview" their posts before actually submitting them. $AllowURLs: Set this to "1" if you want users to be able to include a URL link at the bottom of their messages. (This can be handy if you don't allow HTML in posts, and can even be nice if you *do* allow it.) $AllowPics: Set this to "1" if you want users to be able to include a link directly to a graphic image on their own or another server. Depending upon the nature of your BBS and the demographics of your audience, of course, you very well may not want them to be able to post unapproved graphics.... $NaughtyWords: If you want certain words to be "censored" in posts to your BBS, simply list them here (separated by spaces). Any words (or character strings) matching the contents of this variable will be replaced by a string of hash marks in the actual post. For example, if you defined this variable as "this that" and someone attempted to post the message, "This is one thing, that is another," the actual post would appear as "##### is one thing, ##### is another." $mailprog: The absolute path to your system's sendmail program. If your system doesn't have "sendmail" or if you simply don't want the various e-mail notification functions activated, leave this variable unassigned. $maillist_address: The address you wish to use for e-mail related to your BBS. (Note that e-mail notifications will be addressed *from* a "dummy" address, and that the address you've designated here will appear in the body of the message. This is done in an attempt to prevent people from trying to respond to the e-mail notifications instead of posting their responses directly to the 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. $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 "Examples and Extras" page . $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. $AdminEmail: If you want to receive notice of new messages yourself (at the $maillist_address defined above), but don't want to set up a subscription list to allow others to get such notifications, set this variable to "1". =========================================== ADMIN FUNCTIONS The admin index, from which you can easily delete any or all of the messages on your board, is accessed by adding "?admin" to the URL of your message index. For example, if your board index's URL was "http://foo.com/index.cgi" you'd type "http://foo.com/index.cgi?admin". The first time you access this index, you should be sure to use the "change password" function to *set* a password. (For the first time only, you can type anything or nothing in the "old password" box.) Note that *regardless* of whether or not you've enabled the admin delete capability, users will still be able to delete their own posts if they've assigned passwords to them (assuming, of course, that you've allowed them the option). The admin password, if enabled, will also allow individual deletion of *any* post. =========================================== E-MAIL NOTIFICATION LISTS WebBBS is not designed to handle very large e-mail notification lists, and the basic notifications are frankly not handled in the most efficient manner possible. If your notification list starts to get large (several hundred addresses), you will notice a significant lag time in the processing of postings. Before that happens, you should switch from the basic "as messages are posted" notification scheme to the more efficient digest setup. =========================================== USING WEBADVERTS WITH WEBBBS If you're using WebAdverts to display advertising banners on your site, and want to display banners on your BBS pages as well, you'll need to define the "require" line and the first two variables ($adverts_dir and $display_cgi) in the "insert adverts" subroutine at the end of the configuration file to match the same lines in your WebAdverts configuration file. Once that is done, you can include banners anywhere in your header or footer files simply by insert the comment line "" wherever you want a banner to appear. Note that the zone name itself is optional; if you want a banner displayed without regard to zones, or if you're not using zones, you can leave out the specification. =========================================== 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 Forum . -- Darryl C. Burgdorf