PBLang - Documentation Date: 25th September 2003 - version 4.6 ------------------------------------- Before installing this board: Please read the file copyright.txt very carefully! It is important that you understand that I take no responsible for anything that is caused, directly or indirectly, by the use of this program. In other words: You use this program at your own risk!!! Beyond this, I feel it is very important that you do not remove or alter the single line copyright notice which in a way honours my work. I think that's the least I can request from you. It is just not right if you put your name behind the copyright sign, giving the impression that you did the work that I did for you. It is of course ok and no problem if you add a link to your site, or your name or whatever to the footer. Commercial sites I request to donate via the Paypal button at least 20 US$ towards the development of this board. Private persons may feel free to donate, as it seems appropriate. All users are treated equally with regard to support, which is performed through the support board at the location indicated at the end of this file. In certain situations and if time permits, I am even willing to help via chat, or by other appropriate means. *********************************************************************************** *** For updaters: please read the relevant sections below very carefully!!! *** *********************************************************************************** PBLang bases on the PHP source of Powerboard, the development of which has been stopped in the middle of 2002 in favour of a commercial package. Since then, the board has been largely modified and extended. There is not much left over except for the idea to use a flat file system (there is absolutely no database like mySQL involved). It is a forum which allows localization by the use of language files. This documentation is intended for admins who need to install and edit the board to suit their purposes. I discourage strongly to edit the source, unless you know exactly what you are doing! This is mainly because it will be very difficult to benefit of any future updates. If you have a good idea, let me know, I'll incorporate it, or I'll advise you how you can implement it. I would request that you send the results of your own modifications to me, so that I can include them in the full package. Contents: I - Installation or update procedures a - Preparation b - update from any previous version c - update from PBLang d - System requirements e - Changes in File Structure f - other specialities g - language installation II - How to use PBLang a - After installation b - Maintenance Mode c - Deletion of messages d - Guest account e - styles and colours f - Deletion of forums and categories III - The Admin Control Center A - News and Version Comparison B - Forum Settings a - Announcement option b - server supports email by PHP c - automatic emails d - allowing attachments IV - Tools a - GetLatestMessage.php V - Support addresses VI - The PBLang-Team =========================================== I - Installation or update procedures =========================================== (this is probably the most important section for EVERYONE!) I.a - Preparation ------------------ If you are new to PBLang, take a look at the readme-first file! It *is* important. For PBLang to run, you have to make files and directories writeable. For installation, all directories must be writeable to all (chmod 666; you can also set them to chmod 777). Run install.php. It will check if there are any files or folders which are missing or not supplied with the appropriate rights. You need to re-run the install program after fixing the reported problems, because certain parts of the installation couldn't take place. The following directories must be writeable: /db and all subdirectories /attachments if you want to allow attachments /templates/pb/images/ranks ----------------------------------------------------------------- I.b - For those who update from any previous version (PBLang, NewPB or powerboards): ----------------------------------------------------------------- 1. Run install.php, it will check if everything has been set properly and inform you of any problems. 2. Go to the admin control center, set your options and submit them. Even if you do not want to do any changes, save them. This will add new settings variables which are required for a proper functioning of the board. In some sections there will be new options which you should set the first time. Your previous data should be safe. If your previous version is less than 3.0, you must now follow instructions for updating from PBLang (3.0). ------------------------------------------------------- I.c - For those who update from a previous version of PBLang (3.0 up to 4.1) ------------------------------------------------------- 1. Make a backup of all relevant data which sits in the db-directory and all its subdirectories. There is now a backup/restore program available, called backup.php and restore.php. To use it, create these directories: db/backup db/backup/posts db/backup/cats db/backup/members and give them 666 rights. Then run the backup program. This will save all your old data. Make sure to remove the restore.php program, otherwise anyone can execute it and create a horrible scenario on your system. 2. Set the forum into maintenance mode, and make sure nobody is logged in. 2a. Check the folders db/posts db/cats for any illegal files. Illegal files could be e.g. __1 (first numbers missing, should be e.g. 1_1_1) Don't try to fix them, these messages never appeared in the forum and are useless. Remove them from the folder. Files which belong there are index.html and .htaccess, so keep them there. 3. Copy all updated files to the directory where your forum is located. Make sure that you also copy the updated files from subdirectories to their respective locations! There are a number of new images, updated language files etc. 4. Run install.php and delete it afterwards (usually, it deletes itself after successful installation). You will need to add some information during installation process. 5. Make the lang files in the directory templates/pb/language/ writeable, if you plan on changing them. 6. If you are updating from version 3.x, run the update.php file. If you are updating from version 4.0 or 4.1, run the update-1.php file and then the update-2.php file. These two programs you must run also if you update from version 3.x. So, in a nutshell, the steps are as follows - * Update from version 3.x: update.php update-1.php update-2.php *Update from version 4.0 and 4.1: update-1.php update-2.php 7. Log in and check if members are listed properly in the memberlist. If so, delete update.php - it must not be accessible to anyone else but you. Then check if all messages appear intact. if so, remove update-1.php and update-2.php. If you find that the data hasn't been updated properly, please contact me through the support forum or via email. Do not attempt to run the update programs more than once! Do not allow users to access the forum, if the update didn't perform as expected. 8.Go to the admin center and select the forum settings. Save it, even if you haven't done any changes. Now your version should be indicated as 4.5 9. You should be done. See also the changes in filestructure (section I.e)! I.d - System Requirements ---------------------------- PBLang doesn't need much: it requires support for cookies, and it runs only on servers which support PHP. That's all. Javascript is used, but not required - it works also without. I.e - The following changes in file structure have taken place: -------------------------------------------------------- Version 2.5 to version 3.0: templates/pb/admin.php is no longer needed templates/pb/usercp.php is no longer needed templates/pb/images/buttons is no longer needed All doc-files go into the docs-directory Higher than version 3.0: error.php is no longer needed viewcats.php is obsolete db/getdate.php is no longer needed db/menu.php is no longer needed (was never needed) templates/pb/header.php is no longer needed templates/pb/footer.php is no longer needed templates/pb/stats.php is no longer needed templates/pb/msg.php is no longer needed templates/pb/admintop.php is no longer needed templates/pb/ntopic.php is no longer needed templates/pb/editpost.php is no longer needed templates/pb/cat.php is no longer needed templates/pb/btop.php is no longer needed templates/pb/bpiece.php is no longer needed templates/pb/error.php is no longer needed templates/pb/forum.php is no longer needed templates/pb/memp.php is no longer needed templates/pb/login.php is no longer needed templates/pb/memtop.php is no longer needed templates/pb/sbot.php is no longer needed templates/pb/nreply.php is no longer needed templates/pb/pm.php is no longer needed templates/pb/pmp.php is no longer needed templates/pb/pmpshow.php is no longer needed templates/pb/postp.php is no longer needed templates/pb/posttop.php is no longer needed templates/pb/pmpshow.php is no longer needed templates/pb/profile.php is no longer needed templates/pb/regdone.php is no longer needed templates/pb/register.php is no longer needed templates/pb/rev.php is no longer needed templates/pb/revp.php is no longer needed templates/pb/search.php is no longer needed templates/pb/stop.php is no longer needed templates/pb/who.php is no longer needed templates/pb/sendpm.php is no longer needed templates/pb/ucp.php is no longer needed templates/pb/userin.php is no longer needed Attention: styles.php has been moved. It is no longer in the templates/pb-folder. You find it now in the db/settings/styles-folder, where you would expect it. Higher than version 4.1: admstyles.php has been newly created admsettings.php has been newly created (the following are all complete subfolders): templates/pb/images/arset is no longer used templates/pb/images/blackset is no longer used templates/pb/images/blueset is no longer used templates/pb/images/greenset is no longer used templates/pb/images/redset is no longer used templates/pb/images/butt/ar_grey is no longer used templates/pb/images/butt/bluesimple is no longer used templates/pb/images/butt/contrablue is no longer used templates/pb/images/butt/silver is no longer used templates/pb/images/butt/textonly is no longer used all subfolders in templates/pb/images/icon are no longer used templates/pb/images/top/ar_grey is no longer used templates/pb/images/top/XP is no longer used I.f - Other Specialities ------------------------ When you install PBLang, you will notice a button in the top-right corner showing "Paypal - Donate". If you click this button, you will be taken to a page of Paypal, through which you can contribute financially to the further development of PBLang. You are not required to do so, but it would be a nice gesture to honour the hundreds of hours that have gone into developing this software and to encourage the ongoing development process. If you want to invite the members of your board to do so, too, just leave it. If you don't want to, empty the file "donation.php" completely. You could also enter a URL to your own image, however you need to use PHP-code. Do not delete this file, it would cause an errormessage. See the comments in this file as well. I.g - Language Installation -------------------------- If the language of your country is not available in the package, you need to check if it is available for download at the website at http://PBLang.drmartinus.de/ and install it yourself. However, installation is easy: Just copy the files in these packages to the directories in which they are already located in the archive, and you are done. The directories in the archives are subdirectories of the directory templates/pb/ The contents of the images folder in the archive belongs therefore into templates/pb/images and so on. The new language will be available for selection from within the admin center and the user control panel, as well as from the install-program and registration program. ========================================== II - How to use PBLang ========================================== (this section isn't complete and will be filled as required) II.a - After installation ------------------- After installation, you should immediately register yourself. The first member gets admin status automatically. Then go into the admin control panel, and set the forum according to your preferences. These things are most important: Enter a valid email-address for the admin (you), so you can be notified when a new user has been registered, and for other purposes. If - which is sometimes the case - your server doesn't support the PHP mail function, disable the checkbox "mail supported by server". This will make the useful function of email notification useless, which is a pity. Ask your ISP whether he can allow you to use the mail function for this purpose. Some ISPs turn it off because it's misused for mass mailing. After you have become admin, log in and start creating categories. A category is a supersection which contains the actual forums. The forums are the places where the discussions take place. So plan your board accordingly. Have a look at the support forum to know how a board is organized. Once you created the categories, create also forums whithin the categories. Once you have created the forums, people can begin to post messages. II.b - Maintenance Mode ---------------------- If you set the board into maintenance mode, because you are updating it, and log out, you won't be allowed to log in. A simple way to bypass this limitation is to run "login.php" instead of "index.php" when accessing the board. You can only use the board if you are the admin, while it is in maintenance mode. II.c - Deletion of posts ----------------------- Basically, deletion means deletion. I.e. the message that is to be deleted, will be completely gone. So use this feature with care! While replies can be deleted at any position by the author or the admin and moderator, a post with replies cannot be deleted by its author, but only by the admin. This is because the author of a post that initiated responses should not be able to delete his or her message, otherwise, it would be difficult to find out to what the people actually replied. When the admin wants to delete this first message, (s)he must be aware that with this, the entire thread will be deleted. This is sometimes necessary. There is the equal function at the bottom of the thread. Since the deletion takes place physically, and counters will be reset, it may take some time, depending on how many replies are there. II.d - Guest Account ------------------------ If you want any user to be able to post without any identification, you can create a guest account and invite users to use this account. However, keep in mind that this is a way which allows all kinds of misuse - eventually you'll be held responsible for the contents of your website! II.e - Styles and Colors --------------------------- PBLang supports multiple sets of colors and styles. But when you select a predefined set, your existing set will be overwritten. You can avoid that by copying the file "templates/pb/styles.php" to the directory db/settings/styles. There you rename it to something meaningful which reminds you of what it looks like, like "yellow_desert.php". Next time you call up predefined styles, this file will be on the list. Send me your styles.php file, So I can include it in the distribution package! With version 4.5, some improvement was made: Each style can have its own set of buttons. Buttonsets have a particular prefix which is set in the "styles and colors" section of the adminCP. You just enter this prefix into the field, and all the buttons appear in the selected design, provided they exist in the default language of your board. If they don't, default buttons will be selected. If you don't want that, you may have to choose English as the default language of your board. An example prescript is "ar_grey_", which is the style currently used in the support forums. II.f - Deletion of Forums and Categories --------------------------- To delete a forum, you need to enter a forum as admin and then click on the link at the right bottom of the page "Delete forum". This will remove the entire forum, including all topics! So use this function with great care! To delete a category, you first must delete all forums in this category. If you had deleted forums before the release of the version "Phoenix", you'll have to rename the forums again in the admin center to give them another name than "delplz", so that they become visible again. Then you can delete them properly. After all forums are deleted, you select the option "delete category" in the admin center. ========================================= III - The Admin Control Panel ========================================= A - News and Version Comparison ________________________ Here you have the possibility to check if your version is the latest. This page links to two files on my server at http://www.drmartinus.de. Some hosts do not allow scripts to access other sites, in this case it is good not to open this page of the Admin center. In this case I strongly recommend that you subscribe yourself to the Announcement list, where new versions of PBLang are announced. If your host allows scripts to check other websites, you'll get latest info and a version comparison by selecting this page, making it easy for you to find out if a new version is available. There is also a link to the project page, from where you get directly to the support forum, if you need to get help. The version comparison has been improved to also take into account if you use a beta or testing version. B - Forum Settings _______________ III.B.a - Announcement option -------------------------- In PBLang Phoenix, the new option to make an announcement has been introduced. The announcement will be displayed in a box below the header and above the list of forums. It can be configured in the admin center. In the text box which contains the text for the announcement, you can use simple HTML. If the HTML tag contains quotes, use single quotes only, otherwise the text will be distorted. If you leave the box empty, no announcement box appears. III.B.b - Server supports Email by PHP ---------------------------------- Some webservers do not allow email by PHP. This is especially relevant when the server is based on Windows. In this case, to avoid errormessages, it is good to uncheck this option. You know that your server does not support EMail by PHP if you get an error message like "undefined function mail() ....". In order to bypass this problem, a function has been built into 4.55 which allows using a SMTP server. However, this function must be set manually: You must edit admsettings.php: the line (around No. 129) reading echo ""; must be changed to echo ""; Simultaneously you must (!) disable the email support via PHP. Also, edit the file db/settings/sendmail.php with your data. Note that your password must be entered in plain text, but the file sendmail.php can not be accessed by other users, so it should be safe. Go to the admin center and select forum settings, then save the settings, even if you didn't change anything. This will make sure that smtp-mail is enabled. Try it out, this function isn't official yet, let me know if it works. III.B.c - Automatic emails ---------------------- In the forum settings in the admin control center, there is an option to allow automatic emails. This refers to the email that is sent to new users at registration time and welcomes the user. This is overridden by the option "Server supports email by PHP", i.e. when the server does not support email by PHP and this option is turned off, it doesn't matter if automatic emails are enabled or not, it won't have an effect. III.B.d - Allowing Attachments ---------------------- Previously, attachments were either allowed or forbidden. Now, if you allow attachments to be uploaded, you have the possibility to select which file types should be allowed. This can be helpful if you handle certain filetypes which were not included by default. Keep in mind that all sorts of executeable files can cause great damage, particularly when they are executeable by the webserver, like html and php files, java programs etc. So you should not allow those. Files without an extension are generally allowed (as long as you allow attachments to be uploaded). =================================================== IV - Tools =================================================== IV.A - GetLatestMessage.php ***************************** The file GetLatestMessage.php contains a function which is suitable to create a list of latest posts on another website. You'll have to first include the file in a PHP-file like include ('GetLatestMessage.php'); Note: The file itself must be in the directory from where it is called! Then you can call the function GetLatestMessage() as follows: $LastMsg=GetLatestMessage(string URL,string path,int noofmessage); e.g.: $LastMsg=GetLatestMessage('www.myurl.de/forum','/home/htdocs/myacc/html/forum',0); $LastMsg will be an array containing the following values: $LastMsg[URL] -> The URL wihtout "http://" $LastMsg[subj] -> The subject line of the message $LastMsg[auth] -> The author's name A way to use these values would be: echo ''.$LastMsg[subj].' by '.$LastMsg[auth].'; means: 0 is the newest, 1 the second, 2 the third and so on. If you want to create a list of more than one message, you need to check for duplicates, maybe like this: for ($i=1;$i<=10;$i++){ $PrevMsg=$CurrentMsg; $CurrentMsg=GetLatestMessage('www.myurl.de/forum','/home/htdocs/myacc/html/forum',0); if ($PrevMsg!=$CurrentMsg){ [your code to display the message link comes here] } } =================================================== V - Support Addresses =================================================== Support is available at http://www.drmartinus.de/PBL/index.php For German users under http://www.drmartinus.de/forum/index.php at both locations this version of PBLang will be running. Check the page http://pblang.drmartinus.de/ frequently for updates. If you want to be informed about new releases of PBLang, subscribe yourself to the announcement list (which sends out messages only when a new release or an important update was made) by sending an email to APBLang-subscribe@yahoogroups.com ==================================== V - The PBLang Team ==================================== Many have contributed. Not all may be listed here. This is not for any particularly reason. Some members wished not to be included, others didn't turn in their details, and others I simply missed, for which I apologize. If anyone would like to be listed here, please let me know!!! Dr. Martin Senftleben - Coordinator and major programming work PBLang-Supportforum ID: DrMartinus PBLang@drmartinus.de http://www.drmartinus.de/ Stoner - testing, some programming, graphics PBLang-Supportforum ID: stoner Cyborg - Finnish translation (up to version 4) PBLang-Supportforum ID: cyborg Vitaly - Russian translation, beta testing, graphics PBLang-Supportforum ID: vox Vassilis - Greek and Rumanian translation PBLang-Supportforum ID: s2sinner Website: http://www.smartclub.gr/ Jianqi Huang (J) - Simple Chinese translation, graphics (up to Version 4.0) PBLang-Supportforum ID: tintytinyme Website addresses: http://www.vony.com http://www.counterstrikeonline.com College Student (SUNY Geneseo) Symbol - Spanish translation PBLang-Supportforum ID: symbol Website address: http://www.emulespana.com Lazarusek - Polish translations and buttons (up to version 4) PBLang-Supportforum ID: Lazarusek Website address: http://www.lazarusek.w.pl/forum Yetti - Polish translation and buttons from version 4.5 onwards PBLang-Supportforum ID: Yetti Email: Yetti@z.pl Yeechai - Traditional Chinese translation PBLang-Supportforum ID: yeechai Yeechai also does the simple Chines translation from version 4.5 onwards Juraj Hal?ák - Slovak translation PBLang Supportforum ID: Banditos - Latvian translation PBLang Supportforum ID: Nathanaël Lécaudé - French translation PBLang Supportforum ID: natcl (alias: Helter) Website address: http://www.studioimaginaire.com Zodiac - programming, graphics PBLang Supportforum ID: ZoDIaC mucho - programming (mods), webpage design PBLang Supportforum ID: mucho Daedalus - support, programming PBLang Supportforum ID: Daedalus Pokkis - support, programming PBLang Supportforum ID: pokkis and many more who helped in translating and testing the software... Martin Senftleben