Since 1994
Application Systems Design and Development Services
Ready-made Fully Customizable Solutions

Solutions: Ecommerce : Banner Rotator: Install & Use

:

Description - Installation & Use - FAQs

Banner Rotator System - Installation and Use

FILENAME: BR-ReadMe.html

DEPENDENCIES:

pr.pl (Promotion configuration and common logic modules)
jhzcs.pl - JHZ-CS configuration and common logic modules (see: jhzcs.html)
IID (Item Information Dataset)

REQUIREMENTS:

brs.cgi (web interface component)
brs.pl - Banner Rotator System configuration and common logic modules
help.pl
report.pl
smpl.pl
test.pl
data/brs/brs.dat (banner definition file)
data/brs/sample.dat
data/brs/images/ (directory where banner images reside)

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

PACKING LIST
PRODUCT ID: BR
COMPONENT TYPE SIZE AUTH*
.jhz-cs/.perl/solutions/geog.pl TEXT 11609 750
.jhz-cs/.perl/solutions/jhzcs.pl TEXT 34046 750
.jhz-cs/.perl/solutions/pr/brs/brs.pl TEXT 22427 750
.jhz-cs/.perl/solutions/pr/brs/help.pl TEXT 23411 750
.jhz-cs/.perl/solutions/pr/brs/report.pl TEXT 4661 750
.jhz-cs/.perl/solutions/pr/brs/smpl.pl TEXT 5627 750
.jhz-cs/.perl/solutions/pr/brs/test.pl TEXT 5339 750
.jhz-cs/.perl/solutions/pr/pr.pl TEXT 1187 750
.jhz-cs/data/solutions/brs/brs.dat TEXT 3358 700
.jhz-cs/data/solutions/brs/sample.dat TEXT 3350 700
.jhz-cs/logs/solutions/errorlog.txt TEXT 91 750
public_html/Templates/solutions/license.incl TEXT 7904 700
public_html/Templates/solutions/pr/brs/brs.incl TEXT 29761 700
public_html/cgi-bin/solutions/pr/brs/brs.cgi TEXT 865 750
public_html/images/solutions/JHZCS.gif BINARY 745 750
public_html/images/solutions/brs/bod1.gif BINARY 1498 750
public_html/images/solutions/brs/imgb1.gif BINARY 2520 750
public_html/images/solutions/brs/imgb1a.gif BINARY 2525 750
public_html/images/solutions/brs/imgb1b.gif BINARY 2528 750
public_html/images/solutions/brs/imgb1c.gif BINARY 2514 750
public_html/images/solutions/brs/imgb2.gif BINARY 2494 750
public_html/images/solutions/brs/imgb2a.gif BINARY 2510 750
public_html/images/solutions/brs/imgb2b.gif BINARY 2518 750
public_html/images/solutions/brs/imgb2c.gif BINARY 2507 750
public_html/images/solutions/brs/imgb3.gif BINARY 2483 750
public_html/images/solutions/brs/imgb3a.gif BINARY 2498 750
public_html/images/solutions/brs/imgb3b.gif BINARY 2499 750
public_html/images/solutions/brs/imgb3c.gif BINARY 2470 750
public_html/solutions/pr/brs/help.html TEXT 31285 750
public_html/solutions/test/brs/linked1.html TEXT 1029 750
public_html/solutions/test/brs/linkedb1.html TEXT 1032 750
public_html/solutions/test/brs/linkedb2.html TEXT 1032 750
public_html/solutions/test/brs/linkedb3.html TEXT 1056 750
public_html/solutions/test/brs/linkedb4.html TEXT 1056 750
public_html/solutions/test/brs/test.html TEXT 3524 750
*AUTH - Authorization/permissions octal equilvalents where:
7=RWX, 6=RW, 5=RX, 4=R (R=Read W=Write X=Executable)
1 char indicates Octal number
2 char Owner
3 char Group
4 char All Others

Installation

It is recommended that you read the entire installation process steps prior to performing installation. Each solution has specific instructions.

Installation Sequence

  1. Download solution to desktop
  2. Expand installation package (use any standard archive application; such as WinZip®, StuffIt Expander® or TAR command)
  3. Set configuration settings
  4. Upload components to server
  5. Set file permissions
  6. Test installation
  7. Customize Templates as desired
  8. Test customizations

Authorize non-Logic Components

  • Authorize graphic files for Read and Execute access; see "NOTE FOR NON-LOGIC COMPONENTS" below.
  • Authorize static HTML ".html" files for Read access; see "NOTE FOR NON-LOGIC COMPONENTS" below.
  • Authorize HTML Templates ".htm" files for Read access; see "NOTE FOR LOGIC COMPONENTS" below.

NOTE FOR NON-LOGIC COMPONENTS: Specify minimum required access permissions to achieve a more secure configuration; permission requirements for non-logic modules are dependent on server configuration where authorizations are required for either "group" only or for "owner", "group" and "other".

Modify Logic Components

Modify all logic components "*.cgi" and "*.pl" logic modules as follows:

  • First line of code (#!) correctly points to the PERL executable binary on the server (use command "which perl" or consult your server administrator)
  • All PERL "requires" statements contained in "*.cgi" and "*.pl" logic modules must use "absolute" directory paths (beginning with a forward slash "/")

Authorize Logic Components

Authorize logic components and dependent components (HTML and Email templates, and others) as follows:

  • Authorize "*.pl" logic modules for read access; see NOTE FOR LOGIC COMPONENTS below.
  • Authorize "*.cgi" logic modules for read and execute access; see NOTE FOR LOGIC COMPONENTS below.
  • Authorize all HTML and Email Templates documents for read access at the logic level; see NOTE FOR LOGIC COMPONENTS below.

NOTE FOR LOGIC COMPONENTS: Use minimum required permissions to achieve a more secure configuration; permission requirements for logic modules are dependent on the server configuration whether authorization is required for "owner" only (i.e., Apache with SUExec active), or "owner" and "group."

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

BRS searches for occurrences 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>
Parameter

Usage

Valid Values Description
type required TOP|BOT|BODY

Specifies the location within the page.

"TOP" may be replaced by any image/text specified as "TOP" or "BOTH" in the BRS Data File.

"BOT" may be replaced by any image/text specified as either "BOT" or "BOTH" in the BRS Data File.

Only one "TOP" and one "BOT" per page is allowed.

An unlimited number of "BODY" types may be specified (up to the number of BODY entries within the Banner Rotator Data File) within a page.

NOTE: "BOTH" is not a valid parameter value.

name required any alphabetic text value up to 32 characters in length

A unique name within each page to differentiate it from other occurrences within the page. Names may be shared/reused across multiple pages and templates.

NOTE: Unrelated to the "Name" data column in the Banner Rotation System Data File.

dept optional valid category value defined in the IID (Item Information Dataset)

Specifies the department for the page being displayed. Requires use of the IID (Item Information Dataset)

The value is used to determine whether to exclude particular image/text from display. The value is tested against the "Exclude" data column within the BRS Data File.

anchor-and-image recommended a valid HTML image reference wrapped in a valid HTML hyperlink anchor

Default Banner Image content to display without BRS for type=top|bot HTML anchor wrapped image banners.

body-text recommended Any valid text. May include HTML formatting markup.

Default Text content to display without BRS for type=body.

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.

File Name Data Column Name Description
brs.dat Name arbitrary but unique for each entry
Type top|bot|both|body
Weight a numeric value 1 through 99 (higher the value the more frequent the banner is displayed)
ImgSrcURL Image URL (absolute URL path and filename)
AHrefURL Hyperlink URL
Text Type=body only; any text
PID Type=body only; Product PID in Product Data File
Exclude Department to exclude from <<category>> in the IID (Item Information Dataset). The exclusion option requires use of the IID.
DisplayCount Tracks accesses via Banner Rotate System hyperlinks; internal use only
ClickThru Tracks accesses via Banner Rotate System hyperlinks; internal use only
InternalStatus total cumulated weight factor; internal use only.

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.

Parameter Value Response
admin report Generates and Displays Report
admin help Displays Online Help
admin template Displays the Report Template
admin sample Displays sample special markup

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.

JHZ-CS Solutions are offered exclusively under the terms and conditions of the JHZ-CS Software License Agreement.