Previous | Next Main Index:   Frames | No Frames
Document:   Frames | No Frames
 
 

Configure WS Banner Setup File

 
WS Banner's setup file, /Web_store/Databases/ws_banner.setup, contains variables specific to ws_banner.cgi.
 
Variables used by all scripts are located in /Web_store/ws_global.setup.
  
$default_setup_file = 'ws_banner.setup';
If you change the filename of ws_banner.setup, change the value of $default_setup_file located in the DEFINE VARIABLES section at the top of ws_banner.cgi to reflect the file's new name.
 
$default_setup_file is the setup file used if the URL pointing to ws_banner.cgi does not contain a name=value pair for setup= in the query string:   ws_banner.cgi?setup=ws_banner
 
 
ws_banner.cgi displays banner advertisements in a random of predetermined sequence for each request of the script. ws_banner.cgi is a support script designed for WebStore Frames.
 
ws_banner.cgi must be defined in a <frame src> tag of a frame document parsed by ws400CS.cgi:
 
<frame name="banner" src="http://www.YourDomain.xxx/Web_store/ws_banner.cgi?cart_id=">
 
Variables
 
$timeout
$max_cycles
$browser_errors
$background | $bgcolor - $alink_color
$bottom_space | $top_space
$left_space | $right_space
%images
 
Configuration Errors
 
Value for cart_id= not Present in URL
Not Enough Images for Display
Image File does not Exist
Image File is not Readable
Banner Key File Error - Read
Banner Key File Error - Write
 
Query String
 
name= Definitions:
cart_id= | random=Y | refresh=xxx
 
HTML documents:
?refresh=xxx&cart_id=
?random=Y&refresh=xxx&cart_id=
 
Element two of banner images stored in %images:
$main_script_url.'?random=Y&refresh=5'
$script_url.'/ws400CS.cgi?category=CategoryFrontpage&store=outlet&cart_id='
 
 
Top of Page
 
 
Variables
 
  
$timeout = '';
$timeout is the amount of time each banner listed in %images is used before switching to the next banner (in numeric sequence) listed in %images.
 
When $timeout contains a non-zero numeric value, WS Banner stores the image's index array number (from %images) for the last banner image displayed in the file banner_timeout.file in the /User_carts sub-directory.
 
The age of banner_timeout.file is queried to determine when to switch to the next sequential image.
 
A web browser accessing this script will receive the image whose index number is currently listed in banner_timeout.file. The next browser access will receive this image as well if the time-out file's age has not exceeded the age limit set in $timeout. Once the first image has been used for the length of time set in $timeout, WS Banner will store the next image's index number in banner_timeout.file, overwrite banner_timeout.file (resetting the file's age), and switch to the image whose index number is now stored in banner_timeout.file, and so on.
 
When $timeout is set to a non-zero numeric value, it overrides query string data for refresh and random and forces single, sequential banner display.
 
Setting $timeout = ''; disables timed banner switching. Each call of this script will load banners according to the query string data received.
 
Example Settings:
    $timeout = '.167'  - 10 seconds
    $timeout = '.25'   - 15 seconds
    $timeout = '.5'    - 30 seconds
    $timeout = '.75'   - 45 seconds
    $timeout = '15'    - 15 minutes
    $timeout = '30'    - 30 minutes
    $timeout = '45'    - 45 minutes
    $timeout = '60'    -  1 hour
    $timeout = '120'   -  2 hours
    $timeout = '360'   -  6 hours
    $timeout = '720'   - 12 hours
    $timeout = '1080'  - 18 hours
    $timeout = '1440'  - 24 hours (1 day)
    $timeout = '2880'  - 48 hours (2 days)
 
Index
  
$max_cycles = '2';
$max_cycles is the number of times each web browser is allowed to cycle through the images listed in %images when using &refresh=xxx in the query string of URLs accessing this script.
 
Refreshes of the banner HTML document generated by this script are accomplished using the <META Refresh> tag in the <HEAD> of the document.
 
Setting $max_cycles = ''; disables <META Refresh> cycle protection.
<META Refresh> calls to this script will print banners indefinitely to the web browser at the refresh rate set by &refresh=xxx in the query string. If &refresh=xxx is not present in the query string, a single banner document will be printed with no <META Refresh> tag in the <HEAD> of the document.
 
 
Index
  
$browser_errors = '1';
If $browser_errors = 1, print error messages to the web browser for the following error conditions:
    Image File not Found
    Image File not Readable
    Banner Key File Error - Read   (banner_timeout.file)
    Banner Key File Error - Write  (banner_timeout.file)
Setting $browser_errors = ''; disables printing viewable error messages to the web browser. Error messages are printed as hidden comments in the web browser's Document Source.
 
 
Index
  
# $background  = '';
# $bgcolor     = '#FFFFFF';  # White
# $text_color  = '#000000';  # Black
# $link_color  = '#0000FF';  # Blue
# $vlink_color = '#0000A0';  # Dark Blue
# $alink_color = '#FF0000';  # Red
Values for background, bgcolor, text, link, visited link, and active link are set using $background, $bgcolor, $text_color, $link_color, $vlink_color, $alink_color respectively.
 
These variables are set globally in ws_global.setup for use by all scripts in the WebStore application.
 
To configure specific colors for WS Banner, remove the # (pound sign) from column 1 and set to the desired value. Any combination of these variables may be uncommented (pound sign removed).
 
$background is the filename of a background image stored in the /Web_store/Graphics sub-directory. The script precedes $backgound with $graphics_url:
    $graphics_url/$background
 
Index
  
$bottom_space = '0';
$bottom_space is the height of a table row printed after the image for bottom of page spacing.
 
Setting $bottom_space = '0' disables printing the bottom space table row.
 
 
Index
  
$top_space = '12';
$top_space is the height of a table row printed before the image for top of page spacing.
 
Setting $top_space = '0' disables printing the top space table row.
 
 
Index
  
$left_space = '0';
$left_space is the width of a table column printed left of the image to compensate for a left scrollbar in the main window.
 
Setting $left_space = '0' disables printing the left space table column.
 
 
Index
  
$right_space = '11';
$right_space is the width of a table column printed right of the image to compensate for a right scrollbar in the main window.
 
Setting $right_space = '0' disables printing the right space table column.
 
 
Index
  
%images = (

# Keys     Elements
  '01' => ['banner_01.gif',
           'ALT="Random Banners - 5 second refresh rate" WIDTH=400 HEIGHT=45 BORDER=1',

           $main_script_url.'?random=Y&refresh=5',
           q!TARGET="_self"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Random Banners - 5 second refresh rate'; return true"!
          ],


  '02' => ['banner_02.gif',
           'ALT="Sequential Banners - 5 second refresh rate" WIDTH=312 HEIGHT=40 BORDER=1',

           $main_script_url.'?refresh=5',
           q!TARGET="_self"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Sequential Banners - 5 second refresh rate'; return true"!
          ],


  '03' => ['banner_03.gif',
           'ALT="Random Banners - 1 minute refresh rate" WIDTH=400 HEIGHT=40 BORDER=1',

           $main_script_url.'?random=Y&refresh=60',
           q!TARGET="_self"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Random Banners - 1 minute refresh rate'; return true"!
          ],


  '04' => ['banner_04.gif',
           'ALT="Sequential Banners - 1 minute refresh rate" WIDTH=400 HEIGHT=40 BORDER=1',

           $main_script_url.'?refresh=60',
           q!TARGET="_self"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Sequential Banners - 1 minute refresh rate'; return true"!
          ],


  '05' => ['banner_05.gif',
           'ALT="Solid Herringbone Shirt - Database Item" WIDTH=400 HEIGHT=40 BORDER=1',

           $script_url.'/ws400CS.cgi?category=6&store=outlet&cart_id=',
           q!TARGET="main"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Solid Herringbone Shirt - Database Item'; return true"!
          ],


  '06' => ['banner_06.gif',
           'ALT="Crew-Neck Sweater - Database Item" WIDTH=400 HEIGHT=40 BORDER=1',

           $script_url.'/ws400CS.cgi?category=9&store=outlet&cart_id=',
           q!TARGET="main"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Crew-Neck Sweater - Database Item'; return true"!
          ],


  '07' => ['banner_07.gif',
           'ALT="Outer Wear - Category Front Page" WIDTH=400 HEIGHT=40 BORDER=1',

            $script_url.'/ws400CS.cgi?category=Outerwear.html&store=outlet&cart_id=',
            q!TARGET="main"
              onMouseOut="window.status=''; return true"
              onMouseOver="window.status='Outer Wear - Category Front Page'; return true"!
          ],


  '08' => ['banner_08.gif',
           'ALT="Shirts - Category Front Page" WIDTH=400 HEIGHT=40 BORDER=1',

           $script_url.'/ws400CS.cgi?category=Shirts.html&store=outlet&cart_id=',
           q!TARGET="main"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Shirts - Category Front Page'; return true"!
          ],


  '09' => ['banner_09.gif',
           'ALT="Sweaters - Category Front Page" WIDTH=400 HEIGHT=40 BORDER=1',

           $script_url.'/ws400CS.cgi?category=Sweaters.html&store=outlet&cart_id=',
           q!TARGET="main"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Sweaters - Category Front Page'; return true"!
          ],


  '10' => ['banner_10.gif',
           'ALT="Store Front Page" WIDTH=400 HEIGHT=40 BORDER=1',

           $script_url.'/ws400CS.cgi?frontpage=Y&store=outlet&cart_id=',
           q!TARGET="main"
             onMouseOut="window.status=''; return true"
             onMouseOver="window.status='Store Front Page'; return true"!
          ],

); # DO NOT REMOVE - terminates %images
%images is a hash of arrays listing all banner images for display.
 
Each image may consist of up to four elements:
zero    Image filename - REQUIRED
one    Image file attributes
two    URL wrapped around image file in an <A HREF> tag. <A HREF=""> and </A> are generated by this script when element two is present for an image.
three    URL's attributes (onMouseOver, onMouseOut, TARGET=, etc.)
<A HREF="Element two" Element three><IMG SRC="Element zero" Element one></A>
 
Elements one, two, and three are OPTIONAL. If the URL (element two) is omitted, element three is disregarded.
 
To avoid backslashing double and single quotes contained in the text of the elements of %images, you may change any element's delimiter from single or double quotes to other non-alphanumeric, non-whitespace characters according to the following chart:
    Normal   Generic  *Interpolates
    ------   -------   ------------

      '        q//         No
      "       qq//         Yes
* Interpolate:  The insertion of text derived from a Perl variable.
 
The delimiter for element three of all images in %images has been changed from ' (single quotes) to ! (exclamation points) to avoid backslashing the single quotes and double quotes contained in the text of these elements.
 
 
Index
 
 
Configuration Errors
 
 
 
Value for cart_id= not Present in URL
Value for cart_id= must be passed to ws_banner.cgi from the WebStore script
 
The client's cart file (cart_id=xxx) must be included in the query string of URLs accessing ws_banner.cgi from HTML documents which must be parsed by ws400CS.cgi.
 
 
Index
 
 
Not Enough Images for Display
Minimum of two banner images must be defined in %images
 
 
Index
 
 
Image File does not Exist:  $images{03}[0]
/Path/To/Web_store/Graphics/Banners/banner_03.gif
 
The banner image $images{03}[0] does not exist in the /Banners sub-directory.
 
 
Index
 
 
Image File is not Readable:  %images{04}[0]
/Path/To/Web_store/Graphics/Banners/banner_04.gif
 
 
Index
 
 
Banner Key File Error - Read
Could not read from /Path/To/Web_store/User_carts/banner_timeout.file
  
    banner_timeout.file File Permissions:
    666 - File is owned by your domain's UserID
    666 - File is script-generated, owned by 'nobody'
 
Index
 
 
Banner Key File Error - Write
Could not write to /Path/To/Web_store/User_carts/banner_timeout.file
  
    banner_timeout.file File Permissions:
    666 - File is owned by your domain's UserID
    666 - File is script-generated, owned by 'nobody'
 
Index
 
 
Query String
 
 
The query string is the information which follows the ? in URLs referencing the WS Banner script. Query string data are groups of name=value pairs separated by the & (ampersand) character:
    http://www.YourDomain.xxx/Web_store/ws_banner.cgi?refresh=60&cart_id=
  
cart_id=
The WebStore script outputs the store's HTML documents line by line and substitutes occurrences of cart_id= found in these files with:
    cart_id=xxxxxxxxxxxxx&store=outlet.setup

    xxxxxxxxxxxxx = the shopping cart assigned to the client
    outlet.setup  = the store's setup file
The value of cart_id= must be passed to ws_banner.cgi in order to TARGET the main frame containing the WebStore application using <A HREF> anchors wrapped around banner images:
    <A HREF="ws400CS.cgi?cart_id=xxx" TARGET="main"><IMG SRC="Banner Image"></A>
ws_banner.cgi internally renames cart_id= to banner_id= for use in <meta Refresh> tags.
 
If ws_banner.cgi does not receive a value for cart_id, it will generate a Value for cart_id= not Present in URL configuration error message in the banner frame.
 
 
Index
  
random=Y
random=Y causes ws_banner.cgi to choose a banner image from %images randomly.
 
The absence of random=Y causes WS Banner to return banners sequentially.
 
random=Y is ignored when $timeout is set to a non-zero numeric value.
 
 
Index
  
refresh=xxx
refresh=xxx causes ws_banner.cgi to print a <meta Refresh> tag in the <HEAD> of the banner HTML document. The banner document will be refreshed according to the value of xxx (in seconds).
 
The absence of refresh=xxx causes WS Banner to load one banner according to the settings of $timeout and the status of random= in the query string received.
 
refresh=xxx is ignored when $timeout is set to a non-zero numeric value.
 
 
Index
  
?refresh=xxx&cart_id=
The absence of random=Y causes WS Banner to return banners sequentially to the web browser at the refresh rate (in seconds) defined by xxx.
&cart_id= must be used to ensure the client's cart file is passed to parsed HTML pages.
  
?random=Y&refresh=xxx&cart_id=
Random banner images will be loaded at the refresh rate (in seconds) defined by xxx.
&cart_id= must be used to ensure the client's cart file is passed to parsed HTML pages.
 
URL examples:
frame documents:
<FRAME NAME="banner" SRC="http://www.YourDomain.xxx/ws_banner.cgi?refresh=xxx&cart_id="
             SCROLLING="auto" MARGINWIDTH=1 MARGINHEIGHT=1>

HTML documents:
<A HREF="http://www.YourDomain.xxx/ws_banner.cgi?refresh=xxx&cart_id=" TARGET="banner">
<A HREF="http://www.YourDomain.xxx/ws_banner.cgi?random=Y&refresh=xxx&cart_id=" TARGET="banner">
 
Index
 
 
$main_script_url.'?random=Y&refresh=5'
Perl interpolates (inserts) the value of $main_script_url into this URL.
The . (period) adds ?random=Y&refresh=5 to this URL.
 
The use of single quote delimiters prevents Perl from interpolating '?random=Y&refresh=5'. & (ampersands) and ? (question mark) do not require backslashing.
 
Banner images are chosen randomly and refreshed at 5 second intervals.
 
WS Banner adds   /ws_banner.cgi   to the value of $main_script_url defined in ws_global.setup, making the interpolated value of $main_script_url in this element equal to http://www.YourDomain.xxx/Web_store/ws_banner.cgi.
 
Alternative configuration: 
"$main_script_url\?random=Y\&refresh=5"
The use of the double quote delimiter causes Perl to interpolate (insert) the value of $main_script_url into this URL.
 
& (ampersand) and ? (question mark) must be backslashed.
 
 
Index
 
 
$script_url.'/ws400CS.cgi?category=CategoryFrontpage&store=outlet&cart_id='
Perl interpolates (inserts) the value of $script_url into this URL.
The . (period) adds /ws400CS.cgi?category=CategoryFrontpage&store=outlet&cart_id= to this URL.
 
The use of single quote delimiters prevents Perl from interpolating '/ws400CS.cgi?category=CategoryFrontpage&store=outlet&cart_id='. & (ampersands) and ? (question mark) do not require backslashing.
 
$script_url is internal to WS Banner, derived from the value of $main_script_url defined in ws_global.setup. $script_url equals http://www.YourDomain.xxx/Web_store.
 
Element four of this banner image stored in %images must exist and must contain the TARGET="main" attribute to properly direct the printing of the CategoryFrontpage document in the frame running the WebStore application.
 
If you do not include the TARGET="main" attribute in element four of this image, the CategoryFrontpage document will be printed in the banner frame.
 
Alternative configuration: 
'http://www.YourDomain.xxx/Web_store/ws400CS.cgi?category=CategoryFrontpage&store=outlet&cart_id='
The use of the single quote delimiter causes Perl not to perform interpolation on this element. & (ampersands) and ? (question mark) do not require backslashing.
 
  
1; # DO NOT REMOVE IN ws_banner.setup

# End of file
 
Index | Top of Page