Welcome to the www.dtp-aus.com VizBook program scripts - version 2.0a.

The program scripts VIZBOOK.CGI, VIZADMIN.CGI, MAKEDIR.CGI, TESTBIN.CGI, and PICLOAD.CGI  were written  (c) by Ron F Woolley, Melbourne Australia. Copyright 1999, 2000. These scripts and associated Perl files CAN NOT BE ALTERED for personal site use OR commercial site use except as instructed here in and in the original program files,
NOR can whole or portions of code be copied, AND
all of the header notices in the scripts MUST REMAIN intact as is, AND,
using the scripts without first reading the README file(s), is prohibited.
IF YOU DO NOT AGREE, destroy all files NOW!

This code MUST NOT be sold, hired, or given/made available to others. Changing output
English words to another language is permitted except for program name and copyright notices!

Australian copyright is recognised/supported in over 130 countries...
per the Berne Convention and other treaties ( including USA! ) registration not required!

The scripts, code, and associated files remain the property of Ron F Woolley.
NO PROFIT what so ever is to be gained from users of these scripts for the use of these scripts, EXCEPT that a reasonable minimal charge for installation may be allowed if installing, as a site developer, for a user on the users site that is not on the developers site. This program must NOT be used for multiple VizBook users on one site OR offered as a remote service.
Ron Woolley, the author, MUST be notified via the addresses/URLs below if any gain is to be made from the installation of these scripts.

You MUST RETAIN the small identifying text line at the base of each page. IF YOU DISAGREE, you must immediately destroy all files.

NOTE: If you use these files, you do so entirely at your own risk, and take on full responsibility for the consequences of using the described files. You must first agree that Ron Woolley / HostingNet, the ONLY permitted suppliers of this or accompanying files are exempt from any responsibility for all or any resulting problems, losses or costs caused by your using these or any associated files. IF YOU DISAGREE, you must immediately destroy all files.

These program scripts are free to use, but if you use them, a donation of  A$25.00 would be appreciated and help in continuing support for VizBook and the creation of other scripts for users of the internet.
Secure On-Line payments can be made for support donations or installations

Support help/information is available at:
   http://www.dtp-aus.com/cgiscript/scrpthlp.htm
Program Page/Files from:
   http://www.dtp-aus.com/cgiscript/vizbook.shtml

THESE FILES can only be obtained via the above web addresses,
and MUST NOT BE PASSED ON TO OTHERS in any form by any means what so ever.
This does not contradict any other statements above.

TO KEEP IT FREE, WE NEED your support on link and resource listing sites!


Low cost installations can be completed by the author; see program page for details link.
This program must be compiled by Perl versions 5+, on Unix servers with Sendmail

** Version 2.0a, May 2000 **
check every few months for upgrades

congif variablesadmin pagesnaming bitmapsheader
footerother edit fileswebmasters pagecoloursinstalling

GETTING STARTED

Many people on the internet consider themselves "intermediate" level experienced CGI installers just because they have done it before. Over several years we have experienced contact by such people and find that once a program requires the use of cgi sub directories and paths, fundamentals about their sites and FTP from simple programs are "assumed", not learned, resulting in installation problems and invariably further assumptions that "the program has bugs and cannot be installed"!!! For this reason (and the sometimes encountered arrogant ego block to advice) we do not support your installation but supply a "scripts help page" at the above URL. We have since received plenty of appreciative comments regarding its blunt helpful information. This detailed help page will however in most circumstances be sufficient. If you think it needs more for this new version 2.0, let us know.

Previously stated that v1.57 would be the last major upgrade before versions 3+, it was decided to support the popularity of VizBook with an interim v2. NOTE: separate readme for utility programs

v2.0a created only days after v2.0 release contains a few minor changes to:...
  "vizbook.cgi", "picload.cgi", "addform2.pl", "editform.pl", "def_vars.pl", plus additions to both readme pages. Simply overwrite those files if program obtained in first few days.

Simple to set-up, complex changes possible
VizBook saves entries to a flatfile database AND creates the main page (last entries) as a "live" html document. This allows the inclusion of meta tags etc for search engine indexing. Any other page of entries viewed is "generated" by the program on call (imbedded links). So to this end note that the "vizbook" htmldocs directories (default setup - "vizbook" and "pics") must allow program "writing" to those directories for writing updates to the book and uploading images via picload.cgi. Many servers allow this by default (just create the directory like any other), and other servers require the permissions to be changed (often to chmod 775 or 777) - VizBook admin may report "cannot access html file" or "error accessing directory" when the page is first generated via admin (the latter can be a paths problem) - or an access error when uploading pictures.

• VizBook redisplays the new entries form WITH the users input if input errors occur.
• VizBook allows "PRIVATE" entries - only mailed to the webmaster; admin option.
• VizBook allows the visitor to decide if they will allow access to their e-mail address.
• VizBook does not include listed e-mail addresses in the list page; pop-up window access only - hiding from address harvesting spam robots! ...no hobbeldygook text like some programs.
• v2+ includes improved database exporting options  - saved to "vbook" sub dir.
• v2+ includes improved Mail List exporting options for Christmas or Thanksgiving etc promos - fully compatible with ListMerge, ennyForms, and E-Lists  - saved to "maillists" sub dir.
• v2+ allows editing of all record input - previously just the "Comment".
• v2+ allows you to select which inputs are "Required" input - only "Comment" is mandatory.
• v2+ allows nervous? submitters to "Review" their input before submitting.
• v2+ includes proper SMTP formatted date/time in visible header but relative to your locality.
• v2+ includes a "repeat" entry block.

• Via the second admin page you can edit a "meta.txt" file to which you can add any search engine meta tags etc relevant to your list - plus additional styles scripts and javascript.
• Via the first admin page you can add any "onload" events to the generated <body ......> tag.
• The new "user picture upload" utility will include any html header and/or footer html code you wish to add to the upload page - see readme2.html.

SSI IMBEDDED SCRIPT CALLS
NOTE that SSI does NOT WORK with program generated pages. Therefore SSI could only work on the "live" main page and not when viewing other pages once the list grows beyond the default "number of entries to view".

UPGRADES NOTE:
Most auxilliary files have been renamed - (names similar and previous html data can be transfered if the notes in the new files are followed).
The database file (now "rcrds.db") will work OK if renamed BUT NOTE you will have to edit earlier entries manually via FTP due to a new ID info file included for this and future upgrades.

All relevant files are supplied in one compressed .zip file that includes the recommended directory structure. It is assumed that the .zip file has been uncompressed into the home directory of a copy of your site on your local computer, expanded to the directory structure included in the .zip file, prepared THEN FTP uploaded (DO NOT upload and expand the .zip on the server!)

The .zip file includes makedir.cgi, a script that attempts to create and set permissions for all the necessary support files - thus helping with a speedy accurate installation of VizBook. Prepare and run makedir.cgi before installing the other files if you know what permissions are required (change in makedir.cgi first) - see readme2.html.

You MUST alter all reference to "yourdomain.name" in the "vizbkset.pl" 'require' file plus the utility webmasters page, and change some of the configuration variables, as described in this Readme text. A program like WordPad is ideal for this using a simple "Search and Replace" option (and saved as text only!). As of v2.0 not all config variables are explained, as only the path variables and the site name and referrers variables need to be changed before installation. The required checks/changes by you before up loading are marked with an asterisk ( * ). The rest can be changed via the admin pages once the program is installed.

There are many config file name variables. These should retained. The suggested directory and file structure should also be retained (and set up by the utility "makedir.cgi" IF it is used).

There are a few variables below that are NOT admin changed - preset config decisions.
• IE: One is to allow or disallow html tags in the comments texts - the default is to "disallow" as a true guestbook should not be used as a "free links page" (and we are yet to see such a page that does not look like a kiddies sand pit!).
• Another is the default size of user pictures - if switched on via admin. VizBook has been designed around a tidy small image size of 60X60 pixels and any change to dimensions will affect the layout and of course page loading (many "newbies" think that big is good design - it is NOT and unnecessary).

PICTURE UPLOAD
As of v2.0 you can enable direct upload of user pictures via their PC. This is an option and to disable it simply remove the URL to the "picload.cgi" file via admin and delete/not install that program (auto response e-mail will adjust the included image instructions). The alternative is to send the picture to you (the webmaster) via e-mail after which you check it and FTP upload to the pics htmldocs directory. The user pictures option can be switched off via admin - also see readme2.html.

MODERATED
As
of v2.0 you can create a moderated list, switched on/off via admin. Switched on all entries will be saved to a holding db and will be listed in the second admin page - where you can edit/activate/reject those new entries (and recreate the book if activated). IF you or the user has uploaded a picture (only correct file name per entry accepted), then it will also appear in a new images list ONLY AFTER entry activation and refreshing of the second admin page - if "moderated" is NOT active then images will appear in a list automaticly.

There are many other variables that can be changed to alter the list appearance and form input options - no longer listed on this page, but the defaults should be OK to use until you have the scripts installed. Then the generated Admin pages (2) will allow you to easily change these variables in any way you wish - most are self explanatory; some are detailed below.

INCLUDED or REQUIRED FILES
The Perl language allows the inclusion of extra files containing libraries of commonly accessed sub routines or common lists of script variables etc. The scripts vizbook.cgi and vizadmin.cgi "require" 11 such files at various stages. gmtset.pl is a simple one and includes a control variable used by the date/time routines, and vizbkset.pl contains the set-up variables.

All files in the cgi sub directories can have their permissions set to chmod 666 on most servers.

Two "include" files, "vizhead.pl" and "addhead.pl", are actually containers for the header section of the book list and new entry page (what appears below the internally generated body tag). These can be edited/replaced by hard coded html without the $?? variable names BUT take note of the included comments. The $?? variable names within the default code enable the dynamics of the admin variables in setting colours etc. NOT retaining those variable names reduces the purpose of the first admin page in readily changing the appearence of the book at any time - see "Header" and "Footer" below.

GMT time zone - changed via admin
Most dtp-aus.com programs include the GMT time zone reference variable in a separate file (gmtset.pl). Rarely used by programmers, this uses a perl function returning the GMT time zone reference set up by default when server operating systems are installed.

If I need to change this common variable - ie daylight savings time changes or I move interstate - then I only have to change one value via one programs admin, to adjust the time reporting of ALL programs to that of MY local time zone, compared to the servers, which nowadays is often at a remote location (dtp-aus.com is 15 hours behind our local time).

However the main advantage of this method allows the relocation of the domain hosts server lofts (does happen) OR even a change of hosts, and the time reporting should not change - in all programs!!

USER UPLOADED PICTURES - also see readme2.html.
v2.0 introduces an option allowing the user to upload a picture direct from their PC. This is accomplished via the "picload.cgi" program which rquires the Perl module CGI.pm to be installed on the server (most hosts include it their standard library of modules). If pictures are enabled the users auto reponse letter informs them of a password and the required file name of their picture file, plus imbeds a link URL to the picture loading program. By deleting the URL to picload.cgi shown in the first admin page this option is not enabled, while sending the image via e-mail will be.

"Pictures" can be disabled altogether via admin.

If your server does not include CGI.pm then simply do not install "picload.cgi" and delete the URL to that program via admin - see more info below.

Version Image
The second admin page should display an image accessed from dtp-aus.com. This image is to indicate to you the latest version available (saves hassles with e-mail contact) . This image is just that, an image, and NO info is received from the admin page (and such a log would quickly become ginormous and of little value to me!).... it is guaranteed to be just a simple info service for your benifit which will eventually be added to all programs.

Please NOTE:
If you install and use this script, please contact us at vzbookreport@dtp-aus.com with server type details and how the script installed and worked etc, for our report base.
( a vote at cgi.resourceindex.com - via red form on the VizBook program page - or any other cgi links site would also be appreciated to help "spread the word" )
  Thank you.

MENU


For INTERMEDIATE installation experience - Help / Advice information is available.
CONFIGURATION VARIABLES in DETAIL

*****
NOTE: While the number of config variables is somewhat large and intimidating, only the sub-headings listed here with an asterisk ( * ) need to be set BEFORE you upload files on to the site.
*****

GMT TIME ZONE reference
This value in 'gmtset.pl' can be changed via admin.
GrenwichMeanTime time zone values can be positive or negative. Remember, it is your GMTime zone that has to be entered, NOT the difference between your local time and the servers. Windows users will be able to find the offset in hours via their Windows Clock set up!

*US, BRITISH AND INTERNATIONAL DATE reporting
Vizbook.cgi displays entry times and vizadmin.cgi both searches for, and includes references in the e-mail list and database output options, the date and time. You can use either the US mm/dd/yyyy format, the BRITISH dd/mm/yyyy format, or the INTERNATIONAL yyyy/mm/dd format. In the configuration file, 'vizbkset.pl', you will find a variable named
$dtUS.
• Leaving this variable value as null, ie '
$dtUS = ""' will cause the scripts to use "dd/mm/yyyy".
• Setting this variable to '
$dtUS = "1"' will force 'mm/dd/yyyy'.
• Setting this variable to '
$dtUS = "2"' will force 'yyyy/mm/dd' (international).
This variable MUST be set before you upload "vizbkset.pl".

*CHECKING FOR CORRECT REFERRERS - This will block even you!!
This option in the 'vizbkset.pl' file allows you create an "array" of Domain names and IP numbers that the scripts will respond positively to. By including the acceptable calls to your pages and/or your IP#, ie 'www.yourdomain.com' and 'yourdomain.com' you effectively stop improper use of or access to your scripts.

This is not 100% foolproof, but in most cases it will be able to detect a Visitors Book page copied from your site that is being used by remote servers to "spam" your list, or attempts to access the scripts from a browsers address command line (ie only use links ON your sites pages OR the webmasters page ). The array is named "@referers" and you simply (MUST) enter your preferences in place of the examples BEFORE up loading "vizbkset.pl". NOTE: The brackets, quotes and commas enclosing each item must be included else an error will occur, ie:

This means that copies of links on your home PC or via your browser
will also not be accepted,
only links on pages ON your site!! - see access link

('www.yourdomain.com','yourdomain.com','000.000.000.000',).

Leave out the IP# if you do not have a true domain name with a static IP#. "www.ahost.net/mysite/" etc will also work for second level site calls etc. If your scripts are called from the cgi-bin of a domain that is housing your site and your specific scripts are in that domains cgi-bin, you will have to include the cgi-bin also ie: "ahost.net/cgi-bin/".

At this point I will bring your attention to the semi colons, single and double quotes ( ;"' ) appearing in and at the end of each line in the config files. These MUST remain else an error will occur.

PATHS TO FILES ACCESSED BY THE SCRIPTS
The defaults used in the 'vizbkset.pl' file assume you will place the script files in your "true" cgi-bin and add a sub-directory to it called "vbook". This is the most secure method. If you have to use other directory names, then you will need to change some paths accordingly; "cgi-yourdomain" is not uncommon where you have to include the cgi-bin name.

There are four path/URL types that can be used at various times with in a program or script.
• A full URL is the same as the path you enter in your browsers address box when typing in a site/page url that you wish to go to: ie '
http://www.wooz.com/harry.htm'.
• A relative URL is one "relative" to the current documment (note CGI programs exist and run in their cgi-bin so other relative URLs looked for by the program must be relative to the program).
ie "jimbo.htm" means that the file being called should be in the same directory as the calling file.
"inone/jimbo.htm" refers is a file URL - should be in a directory named 'inone' which is a sub directory within the current directory,
and "../jimbo.htm" means that the file should be in a directory one above the current directory,
and "../../jimbo.htm" is in a directory two above etc.
and "
../dirname/jimbo.htm" is above and then in a directory (dirname), etc.
• An absolute PATH must be known if used for your site. Generally hosts supply this information.
• A relative PATH is a path description to a source, relative to the directory of the program calling it and those paths will look similar to relative URLs. VizBook PATH defaults are "relative" and by far the easiest to use.

For some servers, a simple relative path called by a script is unacceptable (BUT RARELY), so an absolute path relative to the sites root directory (mostly NOT your root html directory) must be called. There are also variations to this description but "/web/yourdomain/yourdirectory/jimbo.htm" (example only) is an absolute root path description that works on many servers. Another root path is
"
/home/yourdomain/www/yourdirectory/jimbo.htm".
If you have trouble with the default simple relative paths included in the 'vizbkset.pl' file (but not as soon as trouble occurs!), try the absolute root reference ie "/
web/yourdomain/cg-bin/vbook/addform.r" or whatever.
If this is still a problem, look in any installed scripts on your server for a reference, or contact your hosting support staff. If makedir.cgi is allowed to create directories and files using the defaults, and it succeeds, then relative paths should be OK.

Perhaps the greatest path and even program URL confusion is created on sites where the servers CGIWRAP has to be included in URLs to CGI programs. But even in that circumstance simple relative paths to cgi sub dirs still work (sub directories of the directory the program file is in - like the VizBook default set-up).

NOTE: Double check ALL permission's (end of this page) before changing the default paths, unless you know in advance what the paths should be. Too often it is permissions and accidently uploaded Binary files instead of ASCII text files that cause problems - and playing with paths just makes the problem worse to trace - DO NOT ASSUME... individually double check everything!

$mailprog = '/usr/sbin/sendmail';
$cnfg_pth = "sets/vizbkset.pl";   # PATH back to self; ALSO beneath header! changed v2.0
$gmt_pth = "sets/gmtset.pl";   # PATH; ALSO beneath header! changed v2.0
$BinSub_pth = "vbook/";     # NOTE trailing slash "/"; files Dir; NEW v2.0
$htm_path = "../vizbook/vizbook.htm"; # DOCS PATH relative to program cgi OR absolute
$admn_picspath = "../vizbook/pics";  # DOCS PATH relative to program cgi OR absolute
$admn_picsdir = "../vizbook/pics";  # DOCS URL relative to program cgi OR full
$pics_dir = "http://yourdomain.name/vizbook/pics";  # DOCS URL to VizBook images directory
$modfiles = "vbkonhold";    # PATH relative to program cgi OR absolute; NEW v2.0
$allow_tgs = 0;       # HTML tags allowed in message/comment; CAUTION!
$elist_dir = "maillists";    # PATH relative to program cgi OR absolute
$sep = ",";        # NEW v2.0; Mail-List field separator
$elst_exten = ".elf";     # NEW v2.0; Mail-List file name-extension
$theword = "myBook98";      # Admin ACCESS password; NEW v2.0

#### URL of the VIZBOOK.CGI script -------------------------------------#
$vizbkScrpt = "http://yourdomain.name/cgi-bin/vizbook.cgi";

#### URL of the VIZADMIN.CGI script ------------------------------------#
$vizAdminScrpt = "http://yourdomain.name/cgi-bin/vizadmin.cgi";

#### URL of the Visitors Book HTML page --------------------------------#
$htm_url = "http://yourdomain.name/vizbook/vizbook.htm";

#### URL of preferred Home or Return page ------------------------------#
$return_url = "http://yourdomain.name/index.html";

# Picture Size; change this with extreme caution; Layouts will change) -#
%picSz = (width=>"60",height=>"60");

# Admin Drop-Menu Maximum list size;    leave as is!! see readme.htm ---#
$dlMax = '100000';

*HOST SERVER MAIL PROGRAM - "SENDMAIL"
Similar to the Perl program path, this path has to be known for VizBook to send "thank you" and webmaster notifications. If you do not know what it is or cannot find reference to in other installed scripts, ask your Host service-support staff. The default is
$mailprog = "/usr/sbin/sendmail", common on many Unix servers, "/usr/lib/sendmail" another. (test these via "testbin.cgi" - see readme2.htm)

CONFIGURATION FILES - 2 relative PATHS
To update the config files gmtset.pl and vizbkset.pl, the
$gmt_url and $cnfg_url variables need to be known by the scripts. Change these only if you are not using the default paths and/or file names. The defaults are "relative" to the script. NOTE IF changed then two identical paths MUST be changed also in the scripts just below the header.

CGI-BIN SUB DIRECTORY - "vbook"
$Binsub_pth is the path to the sub dir containing most auxilliary files. The default path is relative and MUST END with a forward slash whether relative or absolute.

*HTML PAGE DOCS DIRECTORY - PATH
$htm-path is a default relative path to the default "vizbook" sub directory of the sites root wher the actual list will reside. ALSO take note of FULL VISITORS BOOK URL below.

*HTML IMAGE DOCS DIRECTORY - PATH
$admn_picspath is a default relative path to the "pics" directory containing all images used by VizBook.

*HTML IMAGE DOCS DIRECTORY - URL
$admn_picsdir is a default relative URL to the "pics" directory containing all images used by VizBook.

*HTML IMAGE DOCS DIRECTORY - URL
$pic_sdir is a default FULL URL to the "pics" directory containing all images used by VizBook.
NOTE: both the above may have to be full URLs IF your site cgi-bin is NOT in the site root directory.

If you allow the inclusion of visitors pictures, the script will search for images with special name formats, so to place them in amongst other general images could cause problems. Likewise, the inclusion of admin images, header/footer images, dividers and background images could be lost amongst many other site images - so please read "NAMING BITMAPS" for information on helpful naming conventions that will conform to VizBooks image searching for the admin lists; and make life much easier - below

MODERATED "ON-HOLD" RECORDS
$modfiles is the default relative path to the cgi sub directory where "moderated" records are saved waiting for admin editing, activation, or rejection/deletion.

*ALLOW TAGS
$allow_tgs ....the abilty to allow html tags in the comments texts. We have never seen a guestbook that is not completely messed up by this option, or the mostly idiots that submit to them! But as a few people have requested it I have included it in the config file. A value of zero ( 0 ) strips attempts to add tags to the comments text, and a value of one ( 1 ) allows tags - use this option with caution; once in the comment text only manual editing can remove them. Change this in the config file if so desired; and beware of entries just using your site to create/boost links to others.

*SAVED E-MAIL LISTS Path - setup changed from earlier versions
The variable $elist_dir, contains the default relative path to where the e-mail list file will be saved (via admin) in readiness for safe down loading via your FTP program, OR web mailing via a program like "ListMerge".

*EMAIL LIST FIELD SEPARATOR
$sep The e-mail list saving option allows the inclusion of address and name and date in various formats, compatible with "ListMerge" mailing options or uploading and mail merging via PC mailing programs. If other than just the address is selected the program needs to know what the separator between address/name/date is required. The default is a comma separator.

*EMAIL LIST FILE NAME EXTENSION
$elst_exten is the default file name extension for any address list saved via admin. If your site generates mail lists by other means then this extension can be changed to suit.

Note: $sep and $elst_exten must also match/be changed to suit IF "E-Lists", "ListMerge", or "ennyForms" set-up are also used on your site (all programs are now compatible and can save the same 5 mail list formats)

*ACCESS PASSWORD NOTE: New v2.0
$theword is the access password needed to access the admin pages ONLY form a link on a page ON YOUR SITE... not a command line or copied page on another or even your PC!!

NOTE ADMIN PASSWORD
VizBook admin can now be accessed only via an access password. However, as soon as you first run the vizadmin.cgi script you should go to the Records and Photos admin page via webmaster.htm and ALSO install an Administrators Password. At first the default will of course be nothing and you must enter your new word twice to be sure. Later you can change the password when ever you wish. The password file will contain encrypted data and MUST NOT BE EDITED MANUALLY.


*FULL VIZBOOK.CGI URL
The variable
$vizbkScrpt contains the hyperlink FULL URL to the vizbook.cgi script. This script primarily creates the real html page, or updates it when visitors add an entry.

*FULL VIZADMIN.CGI URL
The variable
$vizAdminScrpt contains the hyperlink FULL URL to the vizadmin.cgi script. It is this script that enables all editing of the defaults and record file etc.

*FULL VISITORS BOOK URL
The variable
$htm_url contains the hyperlink FULL URL to the actual Visitors Book html page that visitors view or add entries to. If uploading the sample vizbook.htm file, make sure it is readable and writeable (most servers these days set this automaticly for/in an html docs directory).

Special Note - Existing Guest Books: If you already have a visitors book that will be replaced by VizBook, you will also have another directory and html file with links to them from other pages. Simply change this value to one that reflects the path and file name of the existing set up.

*RETURN PAGE FULL URL
The variable $return_url, is the default URL Visitors Book uses as a hyperlink to your preferred return page for visitors exiting the list. You can include your own hyperlink link text or buttons etc for navigating to the rest of your site by creating your own HEADER and FOOTER. See below.
FRAMES NOTE: The default vizhead.pl file contains this variable WITHIN the html code. If the book is to appear in a frame then the hyperlink in this line below could be replaced with some text OR add a "target=" attribute as follows....
  Return to <a href="$return_url">the Main Page</a></font></th>
  Return to <a href="$return_url" target="????">the Main Page</a></font></th>
where ???? equals the frame name or "_self".

PICTURE SIZE
%picSz contains the default image size allowed for visitors images (uploaded or via e-mail). It is strongly suggested this is not changed - big is ugly, slow to download, and the layout optimised for the default. IF YOU DO, ONLY change the two numeric values leaving the other characters in tact!

DROP MENU GUI CRASH!!
$dlMax should be left as is and forgotten in most situations. But should the several drop menu lists in admin cause GUI resources overload because of a large number of records entries, this value can be reduced to perhaps display only the last 200 or so entries by replacing with that value. IF it ever occurs it should only be on PCs with very little memory and/or very old operating systems.

OTHER VARIABLES
Because most of the above variables use "set and forget" variables or will dramaticly affect the list if repeatedly changed, most need pre-setting before installation. The rest below these in the config file can be changed via the admin pages.

MENU


THE ADMIN PAGES IN BRIEF

First Admin Page
Top of first admin page gives an indication of list appearence and options.
The Book • Records and Photos •  
Click Here to Re-Create the HTML page...
"PICTURE-UPLOAD by user ENABLED"
Background Image
Items / Page:
Moderated:
--------------------------------------------------------
ICQ# as Image:
Use Divider: Image Name: W: H:
--------------------------------------------------------
Allow Private:
Allow Search:
Use URL:
Use Company:

Use City:
Use ICQ#:
List E-Mail:
List Misc Box:

List DropDown:
Font Name: Size:

Enable Photos:
Use Top Banner:
Use Mid. Banner:
Use Bot. Banner:

Notify Webmaster:
Thankyou E-Mail:
"_blank" in URL:
"I" "we" E-Mail
--------------------------------------------------------
Msg Max:
Table Width:
Cellpadding:
Cellspacing:
--------------------------------------------------------
Background Colour
Text Colour
Link Colour
Visited Link Colour

Name Panel Colour
Msg Panel Colour
Top Table Colour
Top Cell Colour

Misc. Colour
New-Entry Panel
Search Panel
Search Panel TXT
--------------------------------------------------------
Use Misc Box:
Box Caption:
box width:
--------------------------------------------------------
Use DropDown Menu:
Menu Caption:
"Other" box width:
List Items:
Add New Item:
--------------------------------------------------------
Select "REQUIRED" input...
--------------------------------------------------------
margins:
onload events:
--------------------------------------------------------
'picload.cgi' Full URL: empty DISABLE
--------------------------------------------------------
Webmaster E-Mail:
Name of Site:
Name of List:
Admin Password:
Links to the book list and second admin page.
RECREATE BOOK after saved changes.
NOTICE that picture uploads via "picload.cgi" is enabled in e-mail.
Select background image for all pages.
Number of items displayed on each book page.
Enable "Moderated" input - you must check and activate.

Shoe ICQ number as image.
Image between entries: Use, image name, image size - or default line.

Enable PRIVATE messages.
Enable SEARCH link and display button bar
Enable URL input box.
Enable COMPANY input box.

Enable CITY, STATE, COUNTRY input boxes.
Enable ICQ# input box.
Display users E-Mail address on list page.
Display users miscelanious input.

Display users Drop Menu selection.
Font Face AND Font Size used on pages.

Picture allowed, and texts / e-mail includes instructions.
Include Top Banner html code in lists.
Include Middle Banner html in lists.
Include Bottom Banner html in lists.

Webmaster to receive e-mail of all new entries.
User receives auto e-mail response (confirms correct address)
Include "target=_blank" attribute in URL entry link.
E-Mail personalised OR business etc.

Maximum number of characters allowed in "Comments" entries.
Book List table width - pixels OR percent.
Cellpadding size for entry tables.
Cellspacing size for entry tables.

All pages background colour (should set even if under image).
Text Colour used on all list pages.
Hyperlink colour used on all list pages.
Visited Hyperlink colour used on all pages.

Cell colour of cells containing users info.
Cell colour of cell containing users message.
Table colour of default list header.
Center cell colour of default list header.

A miscelaneous text colour; default = header list name text - header table.
Colour can be used behind the whole "New Entry" page table.
Colour of the search button panel and search page form.
Colour of text appearing in the search button panel and search form.

Use miscelanious input on New Entry page.
Caption of miscelanious box label.
Width in characters of miscelanious input box.

Use drop menu list on New Entry page.
Caption for the drop menu list.
Width of "Other" text box next to drop menu - 0 = disable.
List of current drop menu list items.
Enter new drop menu list item for adding to list.

All "Used" input items are listed for "Required Input" activation.

Add browser top/side margin widths to <body...> tag.
Add javascript "onload events" to <body...> tag.

Full URL to the "picload.cgi" program - empty box disables option.

Webmasters e-mail address for new entry and pic upload notification.
A Name for your site.
The name of the list - default header and e-mail notices.
Editing password. When first installed - no password

Options marked "Use" mean use the option as configured. "List" means display users input for that object on the book list pages ("List" disabled and "Use" enabled allows you to receive input but not display on list pages). So, some options can be set up but readily switched on or off, AND input hidden from visitors and only received by you.

Colours can be Hex Triplet (#??????) or x11 colour names (ie "skyblue", "red").

You can now select any list table width in percentage of browser window or fixed width in pixels.

The default font face input is "arial" for Wintel browsers, "geneva" for Macintosh browsers, and "helvetica" which is a good bet for other browsers (all sans serrif fonts).

Second Admin Page
Refresh All Lists
Add Images to Records
Edit, Activate, Reject
Edit existing Entries
Edit REJECTION list
Edit Auto Response Text
Create Export Data Base
Create Export Mail list
Create Admin Editing Password
Change GMT time zone value
Clisk after editing changes via those options using a separate window.
After a new entry (or activated "on-hold" entry), any new images uploaded will appear.
For Moderated Lists - new "on-hold" entries will be listed and can be accessed.
All entries can be edited (all input) via this list.
E-Mail addresses (auto response) or ISP#s (user) can be added to a rejection list.
Edit texts added to the auto response notice - program adds other texts via options.
A data base file with header can be created from all entries - saved in vbook sub dir.
Create Mail List. Compatible with other dtp-aus.com programs or PC mail merging.
New installations require creation of an encrypted password (cannot edit manually).
Set GMT time zone for your locality - see above for explanation.

A list of new picture files uploaded to the "pics" directory will appear on the second page when FTP uploaded by you, OR uploaded by the user via "picload.cgi". NOTE: New images will NOT appear until a "Moderated" entry is activated IF that option is enabled AND a new picture matching a record exists. New images can be viewed / checked by the "View Image" button before installing in to the correct record data.

The "New Entry Activation" list will only appear IF the "Moderated" option is enabled AND entries waiting for activation exist.

Record editing, on-hold entry editing/activation, and all auxilliary files accessed by the buttons at the bottom of the page are edited via a second window (which has to be closed to view the admin page again).

Some files accessed for editing via the bottom buttons can only be changed BETWEEN obvious "comment" tags. In those cases the other Perl code bits MUST NOT be altered.

Auxilliary file editing can be performed directly OR by copying to your PC, editing, and then pasting back in between the comment tags in the editing window. The vizhead.pl and addhead.pl default files contain some imbedded variables that must be included if you want to keep the first admin page options active for easy ready changes to the lists appearence. IF NOT you can of course just add your own html replacing all the deafault variables too.

The export Data Base file will be saved to the "vbook" cgi sub directory. The export Mail List will be saved to the "mailists" cgi sub directory - allowing the use of your own mail lists directory if one already exists (change config path value).

The "banner" files can contain any html code NOT JUST banner ads! - ie the bottom of the "vizhead.pl" file could contain the top of double nested Table html code, and the bottom "ban3.txt" file could contain the bottom double Table nested html code - creating a neat border around the whole list!!

To create your own complete page for the book lists table, vizhead.pl and vizfoot.txt (or even the bottom banner file) could contain all html surrounding the list. To do this create your page as usual making allowence for the complete generated list table (it sits in one whole table). Cut the final html code at relevant places and paste the main part in to vizhead.pl, and the rest in to vizfoot.txt. Make sure all image and hyperlinks use FULL URLs (not relative because other "generated" list pages other than the main are relevant to the cgi-bin). Set the book table width to 100% for the allowed space/position in your code. Start with a basic design to get the hang of it first and it will be found to be quite easy - even side buttons etc can be used. A book font size of "1" can be quite effective and neat too.

All Pages:
You must keep the program name and version output on all pages as programmed. It has been made small and as un-offensive as possible appearing at the very bottom of all pages below all of your own html - small price for quality free-to-use programs. If you do not want to keep it, then destroy all copies you have of the program and use someone else's program - as also stated where downloaded.

MENU


OTHER STUFF!

NAMING BITMAPS - suggested easy formats
The vizadmin.cgi script searches for 3 formats of bitmap file names.

• Names that are all numbers ie 27651.gif or .jpg
• Names that are NOT all numbers, BUT ALSO
DO NOT have the characters "admn" in the name.
• Names that DO have the characters "admn" in the name.

Every entry record is given a unique random ID number, and this number must be the name of any portrait pictures the entry submitter sends back or uploads for inclusion with their list entry - if pictures are switched on.

Therefore do not upload any background images or divider bar images that have ONLY numbers in the name. For the Header and/or Footer html you create, if an image is to be included in the code and you place it in the "pics" directory then start the name with "admn", ie admn.gif, admin1.jpg, admnbtn6.gif etc etc, and vizadmin.cgi will ignore these for the image list drop down menu for backgrounds and dividers. I have included a couple of samples, one of which is used in the default Header for click-linking to the new entries page.

For the background images it is simple to include "bg" in the name, ie bgblue.gif, bg14.gif, bgyelw.jpg, bglogo.jpg etc etc, and include "bar" in the names of divider bar images you want to use, ie bar1.gif, bar2.jpg etc etc. By doing this before you upload the images, you will still know which is for what months later.

All supplied divider bar images are 6 pixels high and require a width of 515 pixels. If you produce your own, then it will make things easy to remember if the height is the same for all... my "foo" divider is popular so is included - W303 X H13.

When you first run vizadmin.cgi you should see the samples in the list and understand how simple it really is. MENU

SETING UP YOUR HEADER
The Header "require" file is named "vizhead.pl". The top and bottom lines of text must remain as is. In between them is the area where you can include any html code you wish to add. The default header should look good enough to remain at least until you have designed and up loaded your own AND have tested the program. In fact many sites are happy to keep the default.

NOTE: The top and bottom lines of that file must MUST REMAIN in that file, as is.

There are two ways to implement your new header.
One: is to just replace the current code with your own BETWEEN THE COMMENT LINES.
Two: is, after saving your new code, replace some tag attributes or attribute values with the following. This will allow the program to include
dynamic changes you make via the admin page.

If you create your own header or alter the default file, please take a few minutes to familiarise your self with the Perl variables used throughout the example header html code. You should then be able to correctly implement them in your own html code. If you visually copy rather than copy and paste these variable names, note that they MUST be copied exactly and kept in all lower case text.

( $misc_clr You can choose a "miscellaneous" or extra colour in the Header and Footer files. You must choose a colour via admin, otherwise text set to use it will appear black. )

$pref_fnt, $sze_3, $misc_clr
If you want to use the default font name, or default "miscellaneous" font color, or the default font size in any of your header text, then include $pref_fnt, $misc_clr, $sze_3, in your header html ie:

<font face="$pref_fnt" size="$sze_3" color="$misc_clr">...</font>

$listis
The text for this variable are changed via admin, and is a good candidate for using the "miscellaneous" color also described above; and used in the default header.

$pics_dir
Any links to admin images in the "pics" directory should be entered with a forward slash before the image name, ie:

<img src="$pics_dir/admn2.gif" ... >.

Admin images are described in the NAMING BITMAPS section.

$return_url
Use this variable if you want the script to embed a hyperlink to the page you want visitors to return to from the list. If you create your own Header, then there could be a series of hard coded links to various areas in your site.

$tb_tbleclr, $tb_cellclr
When you first see the default layout of the list, notice that the Header table is one overall colour with a cell for the heading text in another. It is these two variables, described above, that control the colours.

<a href="$vizbkScrpt?adviz=y">

The default header contains two hyperlinks that call the additions page. One is connected to a text hyperlink and the other to an image hyperlink. This variable, including the "?adviz=y", tells the script to display the input form. If creating your own header make sure you copy the hyperlink samples correctly. If using frames you must add the relevant [target="???"] attribute.

• If you must use a WYSIWYG editor to create header / footer code for later pasting into the supplied files, then AFTER the design is finished USE A SIMPLE TEXT EDITOR to replace font names etc with the variable names as decribed above. This will retain the ability to readily change appearance at any time via the admin options - see next.

NOTE: These variables perform an important role for VizBook. Because of the flexibility built in to VizBook allowing dynamic changes to be made to the list appearance at any time, Headers using fixed and not variable text and/or table cell colours will often conflict with the admin changes making text unreadable etc; try to incorporate the variables wherever possible in your own Header for maximum ease and flexibility.

For an idea, look at the page in "vizbook" after your first test entry (your guest book html page) and compare the header section with the default header file. You will see where the special variable names have been replaced by the admin defaults!

So, as long as you place your new header code in this file correctly, it will appear in the html page as you designed it OR it will just appear with included admin option changes in some tags. MENU

SETTING UP YOUR FOOTER
Previous versions of VizBook allowed the inclusion of the default font face, colour, etc like the header file. However it was decided to remove those options from v2.0. If you would like it as before please send us feedback.

The Footer file is named "vizfoot.txt". Many sites have a common list of hyperlinks for site navigation at the foot of every page, and it is in this file you would insert that common code. The VizBook sample on dtp-aus.com includes one such common footer.

So, as long as you place your new footer code in this file correctly, it will appear in the html page as you designed it. MENU

THE WEBMASTERS PAGE
The supplied webmasters page includes a hyperlink accessing the vizadmin.cgi Admin script. All dtp-aus.com scripts include a sample webmasters page with an access password form. If you do not have one, this one can be adapted for personal use by adding other important links, local and remote. With such a page in a password secure directory you need hardly ever see your site pages!

NOTE: you cannot / should not access the programs via a remote link or a browser command line - only a link ON your site pages (there is an inbuilt admin access password form if just a link is used).

Preferably place this page in a secure directory and DO NOT link to it from any other page; else a search robot will find it! Then make it your default opening page for your browser. If you use other scripts you can cut and paste this form into another page that also contains all the access forms and admin links etc for the other scripts; or visa versa. The form "action" needs to be changed to your script URL. MENU

THE 216 SAFE COLOURS BITMAP
A copy of my 216 safe colours bitmap image is included. This file is for personal use only and cannot be passed on to others or made availabl in any form what so ever! From this image you can get the Hexadecimal RGB values, or an idea for variations of, for any colour attributes you want to try for the VizBook layout. VizBook v2.0 now allows both hextriplet and x11 colour names.

#HEXTRIPLETS: Netscape will interpret broken table background and cell color attributes as black, ie bgcolor="34FF", or "#" to Netscape is the same as hex values of "000000". IExplorer correctly detects an error and completely ignores the attribute. So, if this happens and your browser is IExplorer, you will just note that a colour is missing, but others using Netscape will see big ugly blocks of black! MENU

UPDATING FROM ANOTHER List
If you want to add a large number of old entries it is time consuming; a link some where to the "old book" would be better (perhaps in the vizhead.pl or vizfoot.txt files).

However, if you are replacing an old guest book with VizBook and would like to add some favourite old entries, it can be done in two ways. Either use VizBook to enter them one by one, but it will have to be done before new visitor entries are submitted, plus the dates will be wrong, OR use the supplied template and manually enter the data to a template in your own time, then add (paste) the file contents to the start (top) of the records file via FTP when you are ready.

The template is two rows of a series of de-limiters with the input names shown in the first row. Duplicate the second row as you finish each record and repeat. As long as you have the old pages saved somewhere, it should not be too difficult to cut and paste the probably few pieces of data required from each entry. The sample template is called template.txt and is supplied in the .zip file.

NOTE: Delete the first template reference row before you edit the "rcrds.db" file via FTP (in ascii format), copy the template data, then paste it at the beginning of the records list. Make a backup copy of the original records first and scan the new list to make sure each record breaks correctly and wraps to the next one.

MENU


FILES EDITED VIA ADMIN
BUTTONS ON SECOND PAGE

In brief, this explains the purpose of and therefore how these files come together to make the list - and even which you could use to surround the list table with your own page design. Edit these files directly OR copy, edit on your PC, and paste back.... then save.

When you first get have program up and running, with all images appearing / listed in the first admin page, and you successfully "create" the new but empty book page, use the new entries option to test all options of entry additions and "Private" entries etc (all tests are easily deleted later). Don't play with colours/design until the installation is proved.

addhead.pl
The top of the New Entries page - default black and grey. The file contains the head table divided by some perl logic coding. Do not be intimidated. Look at and read this text file a minute or so and the areas to paste your own code or manually change the default colours is easy to recognise.

badwrd.txt
Unfortunately a fact of life on the web.... so many so called adults with single figure IQs and an incomplete puberty phase; and/or lacking any self esteem! Add others should they appear in your lists and save.

ban1.txt, ban2.txt, ban3.txt
So named but NOT only for banner ad html code. The first appears at the top of the list page, the second appears in the middle of the list once a few entries are added, the third appears at the bottom of the list above any "vizfoot.txt" html. (ban3.txt and vizhead.pl could be combined to include boxed outline tables around the actual list!)

meta.txt
Allready containing some default tags and javascript that MUST REMAIN, you can change the search engine meta tags and others if required (remember that VizBook generates the base book page as a "live" html document - meaning you can submit the page URL to search engines)
NOTE: The <body ..... > tag is generated by the program and KEEP the <head> tag pair as is.

sban.txt
The "Search" popup window (or full page if the browser does not allow javascript) will appear with the same bacground etc as the list. Should you wish to add some html to the top of the page then include it in this file and it will appear automaticly.

vizhead.pl, vizfoot.txt
See above via menu topic link.

Manual Editing only - no button access
ulheader.txt, ulfooter.txt
See comments in "reame2.html" second help page.

MENU


INSTALLING!

*THE PATH TO PERL
At the top of each script (and must remain as the first line) is a default path to the Perl program on your host server. This does vary slightly between servers . If you have problems running the scripts, check with your host support staff about the correct path described in this line. The default entry is "#!/usr/bin/perl" and another common variation is "#!/usr/local/bin/perl".

There are many different implimentations of CGIWRAP amongst servers. On the better hosts it is transparent, on others you have to use specific "cgiwrap" URLs. One result of this is that one call to Perl may run a simple program OK, but once paths to cgi sub directories are involved as they are with VizBook, things go all screwy!
IE: We have installed programs on servers initially with #!/usr/bin/perl (most common default) yet could not run all options unless #!/usr/bin/perl5 was used.... yes you really do have to get know your server!!

NOTE: In Perl scripts the hash sign "#" character comments out the code on a line after this character. But here it has a special meaning to Perl and must remain.

NOTE: recently a site created repeated problems for another program difficult to trace - program ran OK but no environment string (input) got to the program from certain forms!!. The site and programs could be accessed with AND without the www prefix in the URLs; form attribute, links and config URLs. But we discovered that, probably because of cgiwrap, by ensuring ALL URLs where ever contained the "www" everything ran perfectly.

The "testbin.cgi" program can be of some help in obtaining this information (and finding/testing the path to "Sendmail").

UP LOADING FILES (Posting)
CGI-BIN permissions are set by the server and no attempt should be made to change them. Should you have to use another directory (NOT RECOMMENDED for security), AND your server allows the execution of Perl CGI scripts in other directories, then that directory should be set with read and execute permissions - chmod 755 (r+x). Also, The scripts should be set to chmod 755 (r+x).

NOTE: If you have a CGI-BIN or equivalent, I suggest you use it and the default subdirectory configuration. It is probably the most secure directory connected to your home directory, and browser and other access to it is (should be) refused.

FILES AND PERMISSIONS
The supplied free set up utility makedir.cgi and vizbook.cgi will attempt to create and set permissions for most of the files needed. Should your Host server refuse to give scripts the right to create new files, then you will have to create them your self via FTP or Telnet. Each of these files must be given read and write permissions (chmod 666, 766). The directory that they are placed in will also have to have read and write permissions. Either read and write chmod 766 (rwxrw-rw-) or possibly chmod 777 (rwxrwxrwx) will work - try the first before the latter.

NOTE some servers have been encountered that set cgi sub dirs by manual creation, default permissions of 775 AND allow read / write without change!! You can only try - makes it easier.

The actual list directory ("vizbook" AND "pics" -html docs directories) should not be a problem and either the server will set usable permissions OR you have to manually change to 775 or 777. This does vary between servers and only you can know what these should be! (file or directory access error).

By far the biggest problems faced when installing scripts are firstly the file transport encoding used and secondly the permissions settings set for both files and new directories. Bitmap images must be sent to the server using the FTP "Binary" protocol. Text files, ie html pages, CGI SCRIPTS and require files, MUST be sent via FTP in "ASCII" format. Failure to do this will result in the server failing to recognise and execute the scripts, returning a server error page.

Not using the default recommended setup is another way many find that their experience with simple programs is not really very much experience at all. Paths, cgi sub directories, and writing to htmldocs directories can baffle many; and NO programmer can tell you exactly what your site requires - the set up of server OS varies so much.... just be humble enough to learn (ie other programs installed, Host manuals, etc).

Although often referred to as programs, Perl CGI scripts must be compiled before they do anything. As an example, files with the .EXE extension on programs that are installed on Wintel machines are pre-compiled binary executable programs that auto start when called. Perl scripts on the other hand are compiled in memory by "Perl" before they can be executed. The script (text) must be in ASCII text format for the interpreter to be able to read it.

I REPEAT: Up load scripts as "ASCII" files, images as "Binary".

So, assuming the default directory structure is used, you will up load into:

Directory:
cgi-bin (server)
vizbook.cgi, vizadmin.cgi, picload.cgi (chmod 755)
cgi-bin/sets (chmod 766 or 777)
vizbkset.pl, gmtset.pl (chmod 666, 766 or 777)
cgi-bin/vbook (chmod 766 or 777)
all files therein (chmod 666, 766 or 777)
cgi-bin/vbkonhold (chmod 766 or 777)
onhold.db (chmod 666, 766 or 777)
cgi-bin/maillists (chmod 766 or 777)
an html docs page directory - vizbook - (server, 775, 777) the "book" is created here!
index.html (server)
an html docs page directory - vizbook/pics (server, 775, 777)
index.html + all supplied images (server)
an html docs page directory - **preferably secure
webmster.html (server) **do not link to this file!

Create the htmldocs directories "vizbook" and "pics" manually as usual via FTP and leave alone until admin etc is all working OK. Concern yourself with paths to these directories before attempting permissions changes. ie if all images and image lists are OK in admin then it may be a permissions problem if errors occur when first creating the book page, and when uploading an image via picload.cgi - chmod 777 is not good for an htmldocs directory!

vizadmin.cgi will create your vizbook.htm file when you
first select the 'create html' option on the admin pages.

A Page Link to the vizadmin.cgi administration script - the only way to access Admin!
Either via a hyperlink which will open an "access password" form....
   
<a href="http://yourdomain.name/cgi-bin/vizadmin.cgi">VizBook Administration</a>
OR see webmasters access page

If you must use another directory for the two config ??.pl files (not recommended), you must also change the path to those files at the top of the code in vizbook.cgi, vizadmin.cgi, and piload.cgi if used. ie::
#--- Alter these two paths only, if needed! --------------#
   require "sets/ vizbkset.pl";
   require "sets/gmtset.pl";
#--- Do Not make any changes below this line. ------------#

    enjoy... and good luck with your site!