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, This code MUST NOT be sold, hired,
or given/made available to others. Changing output Australian copyright is
recognised/supported in over 130 countries... The scripts, code, and associated files remain
the property of Ron F Woolley. 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. Support help/information is available at: THESE FILES can only
be obtained via the above web addresses, 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.
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:... Simple to set-up, complex changes
possible • VizBook redisplays the new
entries form WITH the users input if input errors occur. • 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. SSI IMBEDDED SCRIPT CALLS UPGRADES NOTE: 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. PICTURE UPLOAD MODERATED 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 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 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. "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
MENU For INTERMEDIATE
installation experience - Help / Advice information is
available. ***** GMT TIME ZONE reference *US, BRITISH AND INTERNATIONAL DATE reporting
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
There are four path/URL types that can be
used at various times with in a program or script. 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 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'; #### URL of the VIZBOOK.CGI script
-------------------------------------# #### URL of the VIZADMIN.CGI script
------------------------------------# #### URL of the Visitors Book HTML page
--------------------------------# #### URL of preferred Home or Return page
------------------------------# # Picture Size; change this with extreme
caution; Layouts will change) -# # Admin Drop-Menu Maximum list
size; leave as is!! see readme.htm ---# *HOST SERVER MAIL PROGRAM - "SENDMAIL" CONFIGURATION FILES - 2 relative PATHS CGI-BIN SUB DIRECTORY -
"vbook" *HTML PAGE DOCS DIRECTORY - PATH *HTML IMAGE DOCS DIRECTORY - PATH *HTML IMAGE DOCS DIRECTORY - URL *HTML IMAGE DOCS DIRECTORY - URL 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 *ALLOW TAGS *SAVED E-MAIL
LISTS Path - setup changed from earlier versions *EMAIL LIST
FIELD SEPARATOR *EMAIL LIST FILE NAME EXTENSION 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 NOTE ADMIN PASSWORD *FULL VIZBOOK.CGI URL *FULL VIZADMIN.CGI URL *FULL VISITORS BOOK URL 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 PICTURE SIZE DROP MENU GUI CRASH!! OTHER VARIABLES |
THE ADMIN PAGES IN BRIEF
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).
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: OTHER STUFF! NAMING
BITMAPS - suggested
easy formats • Names that are all numbers ie
27651.gif or .jpg 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 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. 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 <font face="$pref_fnt" size="$sze_3" color="$misc_clr">...</font> $listis $pics_dir <img src="$pics_dir/admn2.gif" ... >. Admin images are described in the NAMING BITMAPS section. $return_url $tb_tbleclr, $tb_cellclr <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 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 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 #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 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. FILES EDITED VIA
ADMIN 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 badwrd.txt ban1.txt, ban2.txt, ban3.txt meta.txt sban.txt vizhead.pl, vizfoot.txt Manual Editing
only - no button access INSTALLING! *THE PATH TO 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! 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) 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 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:
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 A Page Link to the vizadmin.cgi
administration script - the only way to access Admin! 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::
enjoy... and good luck with your site! |
|||||||||||