Location: PHPKode > projects > YW-GuestBook > YW Guestbook 1.45/YW Guestbook/readme.txt
=====================================================================
                             YW Guestbook
                              readme.txt


    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
=====================================================================


 Content:
 -------------------------------------------------------------------
   1) System requirements
   
   2) Installation
        (a) Quick installation
        (b) Detailed installation & troubleshooting
        (c) Skin installation
        (d) Language pack installation
        (e) Reinstallation
        (f) Deinstallation
   
   3) Integration
 
   4) Script parameters

   5) Contact
   
   6) Special Thanks 

=====================================================================
 1) System requirements
=====================================================================
  
  The YW Guestbook needs a minimum of 550KB free webspace,
  a webserver with PHP4 or PHP5 support and access to a MySQL 
  database.

=====================================================================
 2) Installation
=====================================================================

  a) Quick installation
     --------------------------------------------------------------
       1. upload the ywgb directory
       2. open install.php
       3. start installation
       4. open admin.php
       5. set character encoding
       6. integration into your website - see 3)


  b) Detailed installation & troubleshooting
     --------------------------------------------------------------
         On most servers .php is the default extension for PHP 
         files, but it's possible that your hoster uses another
         extension (e.g. .php4 or .php5) - please ask your server
         administrator. If .php is not allowed you must rename the 
         extension of the following files:
           
           install.php
           index.php
           admin.php
           screen.php
           ht_badwords.php
         
         BUT don't change the extension of functions.php !


      1. Upload the the complete ywgb directory with a 
         FTP client to a target directory on your webserver. 
         This directory will be your guestbook directory
         E.g. if you upload index.php to
         
            http://www.xy.com/gb/index.php

         then your guestbook directory is www.xy.com/gb/
         
         Use the AUTO mode for the file upload if available
         otherwise you must use the BINARY mode for all image 
         files and the ASCII mode for the .html, .php, .css,
         .map and .inc files.  
         
      2. Make sure that the files and the directories have the
         right permissions:

           Guestbook        dir 777
           index.php            755 
           admin.php            755 
      	   install.php          755 
      	   functions.php        755 
      	   screen.php           755 
      	   ht_badwords.php      777 
           admin.css            755 

           libs             dir 755
            - all files         755

           lang             dir 755 
            - all files         755

           skins            dir 755 
  
           flags            dir 755 
  
           upload           dir 777 
  
           upload/preview   dir 777 


      3. Start the installation by opening install.php in your
         guestbook directory.

         If you can't see a installation form, but a

           - Internal Server Error (500)
           - weird text messages starting with <?php
           - or a browser "Save file as" dialog

         you should try change the permissions of the guestbook
         directory to 755 and you should check if install.php has
         the right PHP file extension.
         
         Enter your MySQL access datas into the installation form
         (ask your Internet Service Provider if you don't know 
         what to enter) and click on 'Start installation'

      4. If you see an error message telling you that the file
         ht_lock.php couldn't be created, you must follow the
         instructions to create this file on your computer. 
         Afterwards upload ht_lock.php into your guestbook 
         directory to complete the installation.

      5. Go to the administration of the guestbook by opening
         admin.php in your guestbook directory. If you always
         get logged out if you click on a link try to use the 
         workaround described in question 11 of the FAQ.
         
         You should now set the right character encoding for 
         your language (Setup->General Setup->Encoding). 
         The YW Guestbook supports all single byte encodings 
         which are supersets of ASCII and the utf-8 (Unicode) 
         multibyte encoding.

         On most servers iso-8859-1 is the default encoding.
         Here are possible encodings you can enter:

           utf-8        = All languages (Unicode)
           us-ascii     = American (not recommended)
           iso-8859-1   = Western European (Latin 1)
           iso-8859-2   = Central European (Latin 2)
           iso-8859-3   = South European (Latin 3)
           iso-8859-4   = North European (Latin 4)
           iso-8859-5   = Cyrillic
           iso-8859-6   = Arabic
           iso-8859-7   = Greek
           iso-8859-8   = Hebrew
           iso-8859-9   = Turkish (Latin 5)
           iso-8859-10  = Nordic (Latin 6)
           iso-8859-11  = Thai
           iso-8859-13  = Baltic Rim (Latin 7)
           iso-8859-14  = Celtic (Latin 8)
           iso-8859-16  = South-Eastern European (Latin 10)
	   koi8-r       = Russian Cyrillic
           koi8-u	= Ukrainian Cyrillic

         If you don't find an encoding for your language you
         should use utf-8, especially for Korean, Chinese and 
         Japanese or if you want to have a multilingual 
         guestbook. But please note that utf-8 needs more 
         database space than a single byte encoding!
         
      6. Test your guestbook by opening index.php in your 
         guestbook directory.

         If the guestbook is too slow or if you get a "Page
         cannot be displayed" error you must deactivate the
         hostname resolving: open the files index.php, 
         admin.php and screen.php with an editor and change 
         the line

           define ("HOSTNAMERESOLVING","1");

         on the top of the files to

           define ("HOSTNAMERESOLVING","0");

         Save the changes and upload all modified scripts
         into your guestbook directory. If you now get a "Parse
         error" when you open index.php or admin.php you must
         make the above changes again, but use the scripts from 
         the installation package AND another editor !!

      7. The installation is complete you can add a guestbook 
         link (referencing index.php in your guestbook 
         directory) to the main menu of your website. Read 3)
         or the "Guestbook inclusion for Dummies" how-to on 
         the YW Guestbook website if you want to know more
         about the integration of the guestbook into your
         website design.
         It's a good idea to make a browser bookmark to 
         admin.php in your guestbook directory.


  c) Skin installation
     --------------------------------------------------------------
      1. Use a FTP client to copy the skin directory you have                   
         downloaded into the skins folder of the guestbook.
      2. Open the administration and select the new skin directory
         in the 'Use skin' drop-down-box under the setup page.
         If click on 'Save setup' the new skin is activated.
      3. You can delete the directory of the old skin now if you
         want to save webspace.

  d) Language pack installation
     --------------------------------------------------------------
      You simply have to use your FTP client to overwrite the 
      folder 'lang' in the guestbook directory with the folder
      you have downloaded.

  e) Reinstallation
     --------------------------------------------------------------
      ! Caution: By the reinstallation all saved datas                                  
        of the guestbook get lost !

      1. Delete the file ht_lock.php in your guestbook directory.
      2. Start the installation by opening install.php in your
         browser.

  f) Deinstallation
     --------------------------------------------------------------
      1. Download the deinstallation script
      2. Copy the script into your guestbook directory.
      3. Start the script by opening deinstall.php in your
         browser.
      4. Delete the guestbook directory from your webserver.

=====================================================================
 3) Integration
=====================================================================

  Beside the referencing of the script via a Frame, IFrame or a 
  extra page there is the possibility to integrate the guestbook 
  into an existing site design. There 2 possible ways to do this:

  a) Integration via noFrames.php
     ---------------------------------------------------------------
      For this possibility the skin file noFrames.php, which is 
      responsible for the frameless representation of the 
      guestbook, must be extended by the basic structure of the 
      website.

      Enclose everything in this file that stands between the 
      <body> and </body>-Tag by a table cell:

        <table>
        <tr>
          <td>
          ...content of the body element...
          </td>
        </tr>
        </table>

      Afterwards add the basic structure around this table, 
      so that the guestbook is located where you want it to
      appear. But you must take care that all stylesheets and
      included files are still integrated properly, otherwise
      the representation of the guestbook will be wrong. 
      All used Links and image references, which were added to
      noFrames.php, must either be absolute or relative to the
      guestbook directory.


  b) Integration via the PHP include() statement
     ---------------------------------------------------------------        
      This is the more flexible possibility and is used, when the 
      website uses a PHP-script that realizes the basic structure,
      whereas the script determines the current content to display
      by the value of a passed parameter.

      Let´s take a look at an example:

      In the main directory of the server is the file main.php, 
      which constructs a page depending on the parameter 'page'.
      The guestbook is installed in the directory /scripts/ywgb/
      and main.php shall use the command

        include("scripts/ywgb/index.php")

      to intengrate and display the guestbook, if the value of page
      is 9. So that the guestbook can run under these conditions
      3 constants at the the start of the file index.php have to be
      modified: MAINSCRIPT, SCRIPTPATH and PFIX.

      The constant MAINSCRIPT must contain the name of script that
      is responsible for build-up of the basic website structure
      (not inevitably the script, that includes index.php !). In
      our case it's main.php
      => define ("MAINSCRIPT","main.php");
 
      The relatice path from the MAINSCRIPT to the script index.php 
      of the guestbook, must be entered in the constant SCRIPTPATH. 
      So the path scripts/ywgb/ in the example
      => define ("SCRIPTPATH","scripts/ywgb/");

      The last constant PFIX defines a prefix for all guestbook
      parameters and only has to be modified, if the guestbook and
      MAINSCRIPT use the same parameter names. Since the page 
      parameter for main.php is also used for the guestbook script,
      we would have to use a prefix (e.g. vgb)
      => define ("PFIX","vgb");

      Don't forget to change the encoding (see installation 
      instructions) of the guestbook to your website encoding !

      The script is ready now for the integration via include.
      Since Version 1.2 all official skins remove the HTML header
      automatically when they are included.

      If you want to use different languages for the same guestbook
      you can determine the language and Skin for the guestbook 
      before each include statement (see next chapter):

         $arg['lang'] = "DE"; // use German language files
         $arg['skindir'] = "Standard_German"; // use German Skin
         include("ywgb/index.php"); // include German GB

      Don't use URLs to include the index.php of the guestbook, 
      that won't work !

=====================================================================
 4) Script parameters
=====================================================================

  The file index.php can be called with parameters, which can be
  used to determine a Skin, a language or the mode the guestbook
  will be represented, so that for example the same guestbook can
  be provided with different Skins or languages on your website.

  A call of index.php with parameters has the following form
 
     index.php?param1=x&param2=y...&paramx=z

  whereas param1,...,paramX are one of the following parameters
  and x,...,z the according values for the parameters.

  a) skindir
     ---------------------------------------------------------------
      Forces the script to use the skin, which is given as the
      value of the parameter. The value must be the name of the
      Skin directory (case sensitve !) and if the directory doesn´t
      exists the scipt uses the Skin that was selected by the admin

      Example:   index.php?skindir=Standard_German


  b) lang
     ---------------------------------------------------------------
      Determines the languages files in the lang directory the
      script shall use. The value of the parameter will be appended
      to the names langindex and langcountry. The call of

        index.php?lang=ES
      
      make sure that the script searchs for the language files
      langindexES.inc and langcountryES.inc and uses them to
      generate text outputs. Of course you must add these files
      to the lang folder (download the language pack rename the 
      files). For a completely translated guestbook you should 
      combine the call with a Skin in the desired language:

        index.php?lang=ES?skindir=Standard_Spanish 
      

  c) framemode
     ---------------------------------------------------------------
      If the value of this parameter equal 1 the Framemode will
      of the guestbook will be activated and if the value is 0
      the Non-Framemode.


  If you have defined a parameter prefix (see PFIX under 3) all
  parameter names must have the leading prefix !


=====================================================================
 5) Contact
=====================================================================

  To contact the author you can email hide@address.com

  You can report there, if you
   - have problems with the installation
   - have discovered bugs
   - want to offer your selfmade skins
   - want to do a localisation
   - have criticism, praise or suggestions
  

=====================================================================
 6) Special Thanks
=====================================================================

   I want to thank the following people for their contribution
   to the YW Guestbook project:

Aaron
Nitroware

   ...and all who helped me to find bugs

=====================================================================
                      (c) 2005 YahoOWebs
                          www.yahoowebs.tk
===================================================================== 
Return current item: YW-GuestBook