SHOW AND SELL INSTALLATION AND CONFIGURATION V1.07

Show And Sell is a Free CGI Perl 5 script which allows you to set up and log the display of clickable advertisements on your web site. Features Include: A simple and quick installation process A user friendly form based configuration system including password protection Server Side Include (SSI) and Non-SSI Versions Ability to add a slogan (SSI Only) and destination web site for each advertisement Full control over the slogan font, it's size and it's colour (SSI Only) Support for GIF (including animated GIF) and JPG files Optional logging of all displays and clicks of advertisements Statistics showing the number of times each advert has been displayed or clicked Generates HTML code for displaying adverts Multi-User support designed for Internet Service Providers and Web Hosting companies The following is the procedure which you will need to complete to install and configure the script. No programming skills are required during the installation process and most of the configuration is controlled from user friendly forms. You will however need a basic knowledge of how to install CGI scripts on your web server and a knowledge of the directory structure on your site. If you are interested in multi-user support then please read the multiple.html file included with this script.

INDEX

Requirements Preparation Installation Upgrading Configuration Usage Support The Future History

REQUIREMENTS

There are a number of things that you must have or need to know before you can begin to install and configure this script: The web server which you intend to install it on must be running on Unix. The script may work on a NT based web server but I am not guaranteeing it. You must have a cgi-bin directory to which you can read and write scripts and applications. Perl 5 must be installed and configured on you web server. If you plan to use the SSI version then your web server must allow the use of SSI's and you must know how to implement the use of them. You should have a working knowledge of how to copy files to and from your web server and know how to change the permissions on files. You should understand the relationship between a directory on your web server and its corresponding URL e.g. Home Directory = /client/home/yoursite/docs/ Corresponding URL = http://www.yoursite.com/ Sub Directory = /client/home/yoursite/docs/example/ Corresponding URL = http://www.yoursite.com/example/ CGI Directory = /client/home/yoursite/cgi-bin/ Corresponding URL = http://www.yoursite.com/cgi-bin/ If you are unsure about any of the above then please ask your system administrator. The support section of my web site will eventually have documents relating to the above.

PREPARATION

Before you can begin to install this script you will need prepare a few things: Determine the URL to your cgi-bin directory e.g. /cgi-bin/ or /scripts/ Determine the full path to your Perl 5 compiler e.g. /usr/local/bin/perl Create a directory on your server to contain all the advertisement graphics and configuration files e.g. /client/home/yoursite/docs/showsell/ You will need to chmod this directory to 777. Ask your system administrator if you are unsure how to change the modifications on files. Collect together the GIF and JPG images to be used as the advertisements. Make sure that the filenames are are in the format filename.extension and that they are all valid GIF or JPG images e.g. advert1.gif advert2.jpg advert3.gif etc. Make sure that you have all the necessary files needed for the installation. They should all be in the ZIP file which you downloaded from my web site. Once you have completed the preparation you can now continue with the installation.

INSTALLATION

The installation process is not very difficult since most of the configuration is done in the form based configuration screens built into the script. Here are the steps you will need to follow to complete the installation. The first step is to copy the 'showsell.pl' file to a temporary directory and open it in a text editor. You will need to modify three lines in this file. Change the first line of the script to point to the path of your Perl compiler (Prep. Step 2). Make sure to include the '#!' characters at the start of the line e.g. #! /usr/local/bin/perl Scroll down the script until you reach a section entitled 'User Variable Section'. It should only be a page or so down and around line 50. Change the '$script' variable to point to your cgi-bin directory (Prep. Step 1) and append 'showsell.pl' e.g. /cgi-bin/showsell.pl Change the '$data_dir' variable to point to your advertisement data directory (Prep. Step 3) e.g. /client/home/yoursite/docs/showsell/ Copy the 'showsell.pl' file to your cgi-bin directory (Prep. Step 2) and chmod it to 755. Copy the 'pbmmain.pl', 'pbmscreen.pl' and 'pbmdata.pl' files to your cgi-bin directory (Prep. Step 2) and chmod them to 777. Copy all your GIF and JPG advertisement images to your advertisement data directory (Prep. Step 3). Once you have completed the installation you can now continue with the configuration.

UPGRADING

If you are upgrading the script to a newer version then you will need to do the following: Copy and paste the 'User Variable Section' from the previous version of 'showsell.pl' to the new version. Copy and paste the first line, defining the location of your Perl compiler, from the previous version of 'showsell.pl' to the new version. Copy the new version of 'showsell.pl' to your cgi-bin directory. Copy the new versions of 'pbmmain.pl', 'pbmscreen.pl' and 'pbmdata.pl' to your cgi-bin directory. Verify that all your chmod settings are correct. Once you have completed the upgrading you can now continue with the configuration and modify any newly added settings, if there are any.

CONFIGURATION

The configuration of the Show And Sell script is all done using the form based configuration system built into the script. Once you have completed the installation correctly you can start the configuration. The configuration menus are all password protected and can be called by supplying the following parameters to the script: http://www.yoursite.com/cgi-bin/showsell.pl?screen=login You will need to substitute the URL of your server and cgi-bin directory in the example above. Once you have done this you should be presented with a login screen and if not then there is a problem with your installation. When you first run the configuration screens the default password will be 'pbm' and you will be given the option to change this in the main configuration screen. Once you have entered your password you will be brought to the main configuration screen. You will see a set of options which you can adjust. Any data you enter in these fields will not be used. Advert Base URL Enter the URL which represents the advertisement data directory you created e.g. http://www.yoursite.com/advert/ Advert Border Select the width of the border you want around the advertisements Slogan Font Choose the font you want to use for the slogan Slogan Font Color Choose the font color you want to use for the slogan Slogan Font Size Choose the font size you want to use for the slogan Enable Logging Choose whether you want the display and click of advertisements logged Once you have amended these main options then press the 'Update' button to save your changes. Look in your advertisement data directory to check that a 'showsell.cfg' file has been created. If it has not then there is a problem with your installation. From this screen you also have the option to manage your advertisements, generate HTML code, test the advertisements and change your password. Go ahead and change your password from the default one. If you forget your password then delete the 'showsell.pwd' file in your advertisement data directory. This will reset the password to 'pbm'. Don't bother generating the HTML code or testing your advertisements yet as we still have to add them. Press the 'Manage' button to continue with the configuration. You will be brought to the advertisement maintenance screen where you can modify and add adverts. At first you will not have any advertisements but, if you followed Step 8 of the installation, you should have a list of adverts which you can add. Select one of them and press the 'Add' button. You should now see the advertisement filename in the list of advertisements to modify. Press the 'Modify' button to modify the parameters for this advert. You will be brought to the advertisement details screen where you can now set the URL where you will be brought to when you click the advert and the slogan that will appear with the advert. If you leave the slogan field blank then no text will appear below this advert. The slogan will only be used when using the SSI version. Once you have changed these press the 'Update' button to save your changes. You should see the changes reflected in the preview displayed on this screen. You can click on this preview to test the URL of the advertisement. The statistics for the current advert are also shown on this screen. You also have the option of deleting an advert in this screen. Don't bother deleting anything at the moment and press 'Return' to return to the advertisement maintenance form. Go ahead and add some more advertisements in and then return to the main screen and test it out. Once you have added and configured all your advertisements you are ready to start using the script.

USAGE

Once you have completed the installation you can now start including the the advertisements in your web pages. Advertisements can be included into your web pages using either SSI's or standard HTML. If you press the 'Generate' button on the main configuration screen you will be brought to the Code Generation screen. Here you will see the HTML code that you need to copy and paste into your web pages to display advertisements. There are two version, one for SSI's and one for non-SSI's, so copy the appropriate piece of code. Go ahead and start testing your modified web pages. If you have logging enabled then every display and click of the advertisement is recorded in the log file 'showsell.log'. The log file is written to your advertisement data directory. The date, time, host name of the viewer/clicker and advertisement filename are recorded in the log file. The log is analysed and statistics for each advert are shown in the configuration system.

SUPPORT

If you have problems with the installation, configuration or usage of the script then support is available. Our online support area is currently being developed and should be up within a week or so and until then you can email me with your problems. Send all mail regarding support issues to purelybymagic@yahoo.co.uk. When sending an email support request please include the following: A description of the problem you are having and a copy of any output produced by the script The name and version of the application you are installing The operating system and server type, if known, on which you are installing the script The name and version of the browser you are using to test the script with The 'User Variable' section of 'showsell.pl' The 'showsell.dat' file The 'showsell.cfg' file Those who produce this information will get preferential treatment and will be dealt with first.

THE FUTURE

I have certain planned modifications for this script. They include the following: 'Target' parameter for each advertisement Control over when adverts are shown and when they expire If you have any improvements you would like to see added then please mail them to purelybymagic@yahoo.co.uk.

HISTORY

V1.07 Non-SSI version now redirects to image rather than sending it. V1.06 Expiration header added to Non-SSI version. This fixes the problem of the visitor getting the same image on the site. V1.05 Multi-User support now added allowing Internet Service Providers and Web Hosting companies to install one version of the script for all their clients. V1.04 Now deletes visitor's record from tracking file in non-SSI version. V1.03 Code generation screen added to the configuration system. Also removed need to upload the 'showsell.pwd' default password file. V1.02 Non-SSI Version now implemented. The same configuration screens are used for both the SSI and Non-SSI Versions. V1.01 Added the display of advertisement statistics. You can now view statistics for all adverts from the advertisement maintenance screen.

THATS ALL FOLKS!!!