[Home] [Documentation] [FAQ] [Alternative versions] [Archives] [Users Group]

BIG SAM
Official Documentation

Version 1.1.x

Copyleft 2000,2004 Georges Zadrozynski & Rémi Lecoupé-Grainville
Homepage : http://bigsam.gezzed.net

This document is under the terms of the GNU Free Documentation License
Big Sam source is under GNU/GPL General Public License

 

      Copyright © 2000,2004 Georges Zadrozynski & Rémi Lecoupé-Grainville
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation.

 


Summary

  1. Introduction
    1. What is Big Sam ?
    2. Big Sam History
    3. Big Sam Philosophy
  2. Using Big Sam
    1. Setting up Big Sam
    2. Using Big Sam as a normal user
    3. Using Big Sam as an administrator
    4. Customize your Big Sam
  3. Technical description
    1. Overview
    2. Standard use
    3. Admin use
  4. Appendixes
    1. Images

 

  1. Introduction

    2.

    1. What is Big Sam ?

      2.

      Well... I hope we found a name explicit enough to explain what this kind of "software" is... As the matter of fact, "Big Sam" is the acronym for "Built-In Gestbook Stand-Alone Module"... which means that this PHP3/PHP4 script is a Guestbook that you just have to place on your public html files directory, and it theoretically should work without any particular manipulations (except maybe one or two chmod, it depends of how your system is configurated.

      So this is it : Big Sam is no more and no less than a Guestbook.

    2. Big Sam History

      3.

      Winter 2000... We were developing each other on our side some miscellaneous websites, and we had no choice but using either existing guestbook on the web (slow, unefficient and not so easy to administrate) or perl CGI scripts (even if we do like perl), fastidious to configure and administrate.
      So we decided to build a PHP guestbook, which would have the particularity to be very easy to use for newbies and very easy to modify for webmasters who'd like an efficient service.
      That's why we developed Big Sam and that's why now we distribute it under a GPL License... And we'd like to sincerely thank the Free Software Foundation, Mr Richard Stallman, and our association ATILLA (and our school, EISTI) for all they've done to make all thispossible.

      So... to come back to the script, we first wanted to call it after the name of "GanG" (GanG ain't no Guestbook), but it seemed not to be very appropriated to us... so we decided to adopt the "Big Sam" name, which, by chance, corresponds exactly to the acronym of "Built-In Gestbook Stand-Alone Module"... well ! ;-)

    3. Big Sam Philosophy

      4.

      The goals were very simple : The guestbook should be written in PHP3/PHP4, should only be packaged in one single file, should be easily modifiable, should work in any directory, should have any name and should hold all the guestbook data all alone. Well, we couldn't say that it really was a challenge, because of the power of the PHP, which, we knew, was able to handle all this without difficulties...
      In fact, the main problem was to coordinate our work : we were both so excited by this project that we worked each other at our home, late at night, and sometimes some part of the code the one wrote coved a part of the other... The most impressive thing is that we developed an efficient version in less than 3 days, and the beta version was released after less than a week. (We're kinda proud of this !)

      Theoretically, Big Sam should work on every "Apache under Unix" architecture, at the condition that a PHP module (v3 or 4) is installed on the Apache (see http://www.apache.org and http://www.php.net for more details). We tried not to forgot poor people who are obligated to work under subversive OS (guess which ones ?) and this version of Big Sam is supposed to work perfectly with Apache under theses OS.

      Added in 1.1.0 : The file where the data are stored has been separated form the script itself. This enables to have a faster acces to the datafile, while storing the data. The data file has the name of the script file, with a ".dat" inserted before the php extension.

  2. Using Big Sam

    3.

    1. Setting up Big Sam

      2.

      Just download the bigsam.x_y_z.php.txt file and rename it as a php file (remove the .txt extension). You can rename the filename the way you want, at the condition that the extension will be .php/.php3 (or another extension according to your server configuration, to be interpreted by the preprocessor). Copy it on your htdocs directory.
      Be sure that your guestbook.php3 can be read by everyone (a+r), and the directory where you place it is writable for others (o+w). The guestbook is now ready to be used.

    2. Using Big Sam as a normal user

      3.

      Just fill the fields, and click on the [send the message] button...
      For subversive OS users who didn't understand, check http://www.microsoft.eu.org where everything is explained in detail.

    3. Using Big Sam as an administrator

      4.

      You can use Big Sam either as a normal user (just by adding entries) or as an Administrator. Being an Administrator enables you to :

      • modify entries (name, mail, date, message)
      • delete entries
      • change your password

      To do this, you just have to type in your URL line :
      http://www.domain.com/guestbook/bigsam.php?admin=password

      The default password is bigsam; but this password can be changed when you're in Administrator mode.
      If you can't remember your password, just look for a line looking like $adminpassword = "bigsam"; in your script : the password appears in clear (but who cares, you're the only one who can read the file !).

      So, when you're in Admin mode, the script displays every entries in text areas which enables you to modify the entries the way you want.
      Near each group of text areas (a group represents an entry) stands a check box. If you want to delete some entries, just uncheck the checkboxes of the ones you want to remove.
      Then click on the [Submit Modifications] button.

      At the top of the page stands a table where you can change the Admin password : you just have to type twice the new password you want, and then just click on the [change password] button... your password will be changed.

      Added in 1.1.0 : You can now send yourself a email each time someone fills the guestbook in. To do so, use the following lines :
      $carbonCopy = 1;
      carbonCopy = 1 enables mail sending to mailRecipient, 0 disables it.
      $mailRecipient = "your.mail@your.isp";
      mailRecipient receives a mail each times an entry is entered (if carbonCopy = 1).
      $mailSubject = "[BIG SAM] New Guestbook Entry";
      mailSubject is the subject of the mail which is sent.

    4. Customize your Big Sam

      5.

      To customize the first lines in your HTML page, just modify the displayheader() function. This function will be called for each page displayed.

  3. Technical description

    1. Overview

      2.

      Each time a user posts a message, a temporary file is created (it includes the new entry). This file is named guestbook_temporary.php3 . The client browser is redirected to this new page.
      This page (look how overpowerful it is.... ;) detects that itself is a temporary page, kill the main guestbook file, and duplicates itself to take the name of the main guestbook file. Then, it redirects the browser to the main guestbook file, which detects that a temporary file exists, (but its last modification date is older than itself). So, it destroys it. (Read this paragraph 4 or 5 times, then get some aspirin).

      Added in 1.1.0 : The php lines formerly inserted in the script itself are now inserted in the separated data file.
      This enables easy updates of BigSam.

    2. Standard use

      3.

      When a user add an entry on the guestbook, the data he entered are typed in the script in 4 arrays. (These arrays are created the first time). They are used after, by both user-mode and admin-mode to display entries, either just in listing them, or displaying them in text area to enable the Adminisrator to modify them.

    3. Admin use

      4.

      When the administrator modifies the database, all previous data are erased, and the scripts rebuild the arrays with the data shown on screen, on text areas, except when the checkbox is unchecked. The default is that there's no way to retrieve erased data.

  4. Appendixes

    5.

    1. Images

      2.

      Feel free to use these images, and tell everybody you use Big Sam !