Solutions : Ecommerce : Banner Rotator System

This page describes instructions for installation and use of Banner Rotator System referred to within this document as "BRS".

It is recommended that you follow these instructions closely for initial installation. Following successful test of the initial installation, the configuration may be modified to suit the specific configuration requirements.

Description

BRS dynamically rotates images and their respective hyperlinks within pages containing BRS Special Markup Tags. Pages containing these tags may be static pages or templates used by any of the JHZ-CS dynamic page generator products; including, Category List, Subcategory List, Manufacture List, Item Detail, Item Compare, Text Search, Manufacture Directory, RTPG and Shopping Cart. BRS uses the BRS Data Fileto determine information about the eligible banner images, text and hyperlinks. Each Banner Rotator Data File Entry contains a "Weight" value between 1 and 99 that is used to determine how often it is to be displayed relative to the other entries; the higher the value the more often the banner defined by that entry is displayed.

Static Pages

Links to static pages containing BRS Special Markup Tags must be modified to point to the BRS passing the fully qualified path and file name to the page in order for the BRS post-processing function to be performed and the alternating banners to be displayed and tracked. See examples below.

Templates

Pages dynamically generated using templates by the JHZ-CS page generation products are automatically post-processed by BRS.

PACKING (PARTS) LIST

Installation

Following successful installation and test, modify the existing banner definitions or add new banner definitions in the BRS Data File "/data/brs/brs.dat", then add BRS Special Markup to the desired static pages and modify links to those pages to point to BRS with the path to the page as input. It is recommended that you experiment working with the BRS Test Page to become familar with working with BRS.

Modify Configuration Variables

Using a text editor, open the "brs.cgi" file to make the following changes:

A. As described previously, determine the location of PERL on your web server (consult your server administrator or reference as needed). Modify first line of code to point to PERL.

Example:

#!/usr/bin/perl

B. Locate the following

############################################################
#
#	CONFIGURATION SECTION
#

require "/home/cust/yourdomainname/www/cgi-bin/pr/pr.pl";


#-----------------------------------------------------------
$report_include	= $cgibin_root."pr/brs/report.pl";
$test_include	= $cgibin_root."pr/brs/test.pl";
$sample_include	= $cgibin_root."pr/brs/smpl.pl";
$help_include	= $cgibin_root."pr/brs/help.pl";


#-----------------------------------------------------------
#$debug				= 1;

#
#	END CONFIGURATION SECTION
#
############################################################

1. Modify the values between quotes in the "require" statement to correctly point to the absolute location of the "pr.pl" module.
2. The "$report_include", "$test_include", "$sample_include" and "$help_include" variable assignments are dependent upon the "$cgibin_root" variable contained in the "jhzcs.pl" module. That module must be correctly configured and installed; see that module's embedded installation and configuration instructions for details.
3. If the location of brs.cgi an the dependent *.pl modules are installed/moved to a location other than the default installation location, change the assigned values to "$report_include", "$test_include", "$sample_include" and "$help_include" (following "$cgibin_root.") to correctly point to those modules relative to the path value assigned to "$cgibin_root"

Following successful test of your initial installation, you may relocate the Banner Rotator Data Directory and Template Directory, then modify the values above.

Modify Test Components

Using an ASCII text editor open the following file and change all occurrences of "www.yourdomain.com" to the URL of the website:

• brs.dat
• sample.dat
• /test/brs/test.html

Upload Components

FTP upload the directories and their contents to the website; refer to the Packing List above for details.

Authorize Components

Authorize the Banner Rotator CGI "brs.cgi" for execution, and the BRS Data File "brs.dat" for READ and WRITE; refer to the Packing List above for details.

Test

Access the Banner Rotator Test Page "test/brs/test.html" at your website using a Web Browser. The page initially displays the default banners when accessed as a static page without accessing it via Banner Rotator.

Then, using the instructions on the the Banner Rotator Test Page access the page thru Banner Rotator. When accessing the page thru Banner Rotator each time you reload the page the Banners will alternate.

Use the Test page to verify the initial installation. The Test page can also be used to test new banners and the statistical weight values as you add and replace banners.

Activate

To activate Banner Rotator System for all JHZ-CS supported solutions, locate the following configuration variable in "jhzcs.pl" and modify as described:

#-----------------------------------------------------------
#	BANNER ROTATOR SYSTEM
#

$BRS_installed			= undef;
$BRS					= $cgibin_root."pr/brs/brs.cgi";
$BRS_URL				= $cgibin_base."pr/brs/brs.cgi";
$BRS_data_dir			= $site_root."data/brs/";
$BRS_data_filename		= "brs.dat";

Change from:

$BRS_installed			= undef;

Changing to:

$BRS_installed			= 1;

NOTE: If the location of "brs.cgi" and/or "brs.dat" is to be different from the default install location, modify $BRS, $BRS_URL and $BRS_data_dir accordingly. It is strongly recommended that the default install locations are used until after having fully tested the installation.

Usage

• Special Markup Tag
• Data File
• Invocation Methods

Special Markup Tag

BRS searchs for occurences of its Special Markup Tag within the templates and static pages it processes. The special markup tag identifies the location, type as being top or bottom of page or text, and the page's department optionally used for restricting display only within certain items categories within the IID (Item Information Dataset).

Optionally, default content (text or an image reference) may be placed within the Special Markup Tag. This default content when specified is displayed when BRS is not referenced or used to display the page or when BRS is turned off in the JHZCS.pl configuration file. The specified default content is replaced when BRS is invoked to display the page. This is useful for editing and formatting static pages and templates using HTML authoring tools, and when phasing in the use of BRS where you can modify your existing static pages and templates to include the Special Markup Tags, but have not yet modified links to those pages to use BRS.

Syntax:

<JHZCS_BRS type="value" name="value" dept="value">
anchor-and-image|body-text
</JHZCS_BRS>

Data File

The BRS Data File maintains the banner definition data during the Special Markup Tag to values replacement process. It maintains the display and click-thru information as well as internal use only data used in processing.

Invocation Methods

BRS may be invoked using two Invocation Methods; Static Page Invocation and Dynamic Page Invocation.

Static Page Invocation

The BRS may be invoked against a static page. First, modify the page to include the BRS Special Markup. Then, modify links to the page from being hyperlinks to the page, to a hyperlink to the BRS along with the page´s path and filename as parameters.

Example:

Before BRS:

<a href="index.html">Home Page</a>

Modified for BRS:

Example:

<a href="brs.cgi?disp_URL=http://www.yourdomain.com/index.html">Home Page</a>

NOTE: As in the example above, the value specified for the disp_URL parameter must be a fully qualified page URL to the page to be processed and displayed.

Dynamic Page Invocation

The BRS is invoked automatically as a post-process by our products that generate dynamic pages; our RTPG20, Compare Chart, Search Engine and Shopping Cart products. After the page is generated by the product, the BRS post-process is performed executing the BRS against the generated page. Only the Product page templates requires modification to include the BRS Special Markup.

When modifying templates to support BRS, in order to specify the "dept" value use the special markup data-item tag <<category>>.

Example:

<JHZ-CS_banner...dept=<<category>>...>

Administrative Functions

The BRS has a set of Administrative functions. These functions are accessed and invoked using the following parameters.

EXAMPLE:

To generate a BRS Report, use the following command in your Browser´s location field:

http://www.yourdomain.com/cgi-bin/brs/brs.cgi?admin=report

Also, BRS is invoked via the BRS generated banner and text hyperlinks for Click-Thru tracking. The markup is automatically generated during processing; passing the "clickthru" parameter with its value being the BRS Data File entry name for the banner that is displayed.