bettym.pl Script : Documentation  
Home > bettym.pl > Documentation

bettym.pl Script Documentation

Browse bettym.pl Script Documentation
 

Note about "cgi-bin" directory: The instructions in this documentation assume that your web server has a directory called cgi-bin where scripts are stored on the web server. Some web servers use a cgi-local directory or a cgi directory rather than a cgi-bin directory. In that case, where you see cgi-bin in any instruction, substitute it with the directory name that your web sever uses.

Introduction

The bettym.pl script is a Perl script program that will create HTML pages showing products offered by BettyMills.com. A live example website that was created using the bettym.pl script is EverythingJanitorial.com

Note that the bettym.pl script is a "run-once" script; you run it and it creates HTML files. When you want to update the created HTML files, you run the script again.

You can install and run the bettym.pl script on either your Windows PC, or on your linux/unix server if you have telnet or SSH access. Throughout the following documentation, you will see sections entitled "Installation on Windows PC" and "Installation on linux/unix server". Depending upon where you install and run the bettym.pl script, read the appropriate section.

Depending upon the speed of your Windows PC (or your linux/unix server), it may take up to 1 hour for the bettym.pl script to create all the HTML files for the approximately 30,000 products that BettyMills.com offers.


To use the bettym.pl script:

  1. Setup an affiliate account with BettyMills.com.

  2. Download the bettym.pl script.

  3. Request a bettym.key key file to unlock the demo bettym.pl script so it becomes the full-version.

The rest of what you need to do is summarized in the following points and elaborated upon in full detail in the rest of this documentation.

  1. Download and unpack the bettym.pl script. It comes compressed in a .zip file (or a .tar.gz file). See: Downloading and Unpacking below.

  2. After you receive your bettym.key file from us, put it in the same directory where bettym.pl is located. This will unlock the script. Note: You can run the bettym.pl script without a bettym.key file but the script will run in demo mode. In demo mode, all product links go to the BettyMills.com home page (and do not contain any affiliate ID).

  3. Download the BettyMills.com datafeed files. See: Datafeed Files below.

  4. Modify the bettym.ini configuration file. See: Configuration below.

  5. Modify the templates files, or create your own, or use the samples supplied.

  6. If you are going to run the bettym.pl script on your Windows PC computer, then install ActivePerl. If you are going to run the bettym.pl script on your linux/unix server, then upload all the files (script, data, and templates files) to your web server.

  7. Run the bettym.pl script. See: Running bettym.pl Script.

  8. If you ran the bettym.pl script on your Windows PC, then upload the created HTML files to your web server.


If you have any questions about the bettym.pl script, contact us.


Downloading

Request the bettym.pl script.
You will automatically receive an email that contains download instructions.


Installation on Windows PC:


Installation on linux/unix server:


Unpacking


Installation on Windows PC:

Create a new directory, such as "c:\www\bettym". If you use one of our other scripts in the future, you could put that script's files into "c:\www\SCRIPTNAME" -- this way all the files will be kept organized.

Novice User: To create the c:\www\bettym directory, double click your "My Documents" folder. In the Address bar, type c:\ and press enter (the Address bar should now say "c:\"). If there is no "Address" bar, select View > Toolbars > Address Bar. If it says "These files are hidden", then click "Show the contents of this folder". Now create a new folder and call it www then open that folder (the Address bar should now say "c:\www\"). In there, create a new folder and call it bettym then open that folder (the Address bar should now say "c:\www\bettym\")..

Now unpack bettym-######.zip (such as bettym-040123.zip) into it using WinZip or equivalent Zip compression software.


Installation on linux/unix server:

Using your FTP program, create a "bettym" directory in your "cgi-bin" directory. Upload bettym-######.tar.gz into your bettym directory using ftp BINARY transfer mode.

Login using telnet/SSH and go into the cgi-bin/bettym directory. Then type:

gzip -c -d bettym*.tar.gz | tar xf -


Contents:

When you unpack the file, you will get:

Item Description

bettym.ini

Configuration file.

bettym.pl

The bettym.pl script.

bettym-template/

Subdirectory containing templates.

Edit bettym.ini.lnk

(in .zip file only). Windows shortcut to open bettym.ini for editing using Windows Notepad program.

Edit bettym.pl.lnk

(in .zip file only). Windows shortcut to open bettym.pl for editing using Windows Notepad program.

htmlgz-######.zip
htmlgz-######.tar.gz

The htmlgz.pl script which can be used to save disk space; use of this script is optional. See: htmlgz.pl Script.



Datafeed Files

The bettym.pl script works with the datafeed files available directly from BettyMills.com. See the following instructions to download the datafeed files.

You will put the datafeed files into the same directory where you unpacked the bettym.pl script. When you run the bettym.pl script, it will read the datafeed files and create an HTML file for each product. In the future when BettyMills.com comes out with a new version of their datafeed files (typically 4 times per year), you can download the newer version and rerun the bettym.pl script to update your website with the latest products.

To download the BettyMills.com datafeed:

  1. Go go the BettyMills.com datafeed webpage and click on the datafeed link on that webpage. Save the datafeed .zip file (about 3MB) on your computer -- remember where on your computer you save this .zip file.

  2. Unpack the .zip file (if you need zip compression software, use CuteZip or WinZip). You should end up with two .csv files.

  3. For the "master" file which is about 32MB (e.g.: bettymills_products_0205.csv), rename it to datafeed.csv

  4. For the "category/manufacturer" file which is about 140KB (e.g.: bettymills_category_0205.csv), rename it to datafeed2.csv (notice the 2 in this filename).

  5. If you are running bettym.pl on your linux/unix server, then upload datafeed.csv and datafeed2.csv to the cgi-bin/bettym directory on your server. Use ASCII transfer mode for both files.



Configuration

The configuration of the bettym.pl script is specified via a .ini configuration file called "bettym.ini". Included with the script is a sample bettym.ini file that you can start with.

In the bettym.ini configuration file, each variable setting is specified on a separate line with the variable name first and then followed by the value. Comments are preceeded by a "#" symbol therefore you can comment out a line by adding a "#" to the start.


Installation on Windows PC:

To edit the bettym.ini file, double-click on "Edit bettym.ini" or run Windows Notepad and open the bettym.ini file.


Installation on linux/unix server:

To edit the bettym.ini file on your linux/unix server, use a plain text editor such as vi or pico.

Alternatively, you can edit the bettym.ini file on your Windows PC and then upload the bettym.ini file; see instructions in the "Installation on Windows PC" section above.


For a list of the configuration variables and their meaning, see the bettym.ini file itself.

Note: Your BettyMills.com affiliate ID is set by us in your bettym.key file that we send to you. You do not set your BettyMills.com affiliate ID in the bettym.ini file.


write.html.gzip Configuration Variable

If you use a linux or unix web server, you can reduce the amount of disk space that the created HTML files use by about 50%. Set the write.html.gzip configuration variable to yes and install the htmlgz.pl script. See: htmlgz.pl Script for installation instructions and SSI limitations when using htmlgz.pl.


Template Files


Purpose of Template Files

Template files let you customize the created pages so that they match the look and feel of the rest of your website. A template file is just a regular HTML file just like the kind you normally create for the rest of your website. Basically, the script takes a template, fills in the category and item information and saves that HTML to disk as a new file -- the script does that repeatedly for all the categories and items. To tell the script where in the template to fill in the information, you type in "substitation variables" -- they look like text such as {item.price.sale} or as HTML comments such as <!--item.price.sale--> (see below for full details about substitution variables).


Template Types and Filenames

There are three types of template files:

  1. Store home page template:

    • home.html : (required) This is the "store home page" template. This page is where the list of Super-Categories will appear. The "store home page" can be the home page of your website but it does not have to be; it is the front page of your BettyMills.com store.

  2. Category page templates:

    • cats-sup.html : (optional) This template is used by each Super-Category to display a list of its Main-Categories. If this template does not exist, then the cats.html template is used instead.

    • cats-main.html : (optional) This template is used by each Super-Category to display a list of its Sub-Categories. If this template does not exist, then the cats.html template is used instead.

    • cats-sub.html : (optional) This template is used by each Sub-Category to display a list of its items. If this template does not exist, then the cats.html template is used instead.

    • cats.html : (optional) If you want all the Super/Main/Sub-Category pages to look the same, you can use this one template file. If any of the Super/Main/Sub-Category template files are missing, then this cats.html template file is required.

  3. Item page template:

    • items.html : (required) This template is used to display details about each item.


Sample Template Sets

Several sample sets of templates are included with the script. They are located in the "bettym-template" directory. See screen snapshots below.

You are not limited to using the sample template sets. You can use a set of templates as is, or you can copy then modify one of these sets of templates, or you can create your own templates from scratch.

The template.dir configuration variable controls which template set to use. For example, if you want to use the templates "set1", then set template.dir to "bettym-template/set1".


EverythingJanitorial.com

(templates "set1")


EverythingJanitorial.com

(templates "set2")


EverythingJanitorial.com

(templates "set3")


EverythingJanitorial.com

(templates "set4")


EverythingJanitorial.com

(templates "set5")

 

Template Substitution Variables

To use a substitution variable in your template, type it as text {variableName} or as an HTML comment <!--variableName-->. For example, {date} and <--date--> are substituted with today's date.

To learn more about substitution variables, see: Template Substitution Variables below.


Template Directives

Template directives let you direct the script as to what to do at various points in the template. For example, you could use an {include} directive to include a file, or use an {if} directive to conditionally include a section of HTML based on the value of a variable.

To learn more about template directives, see: Template Directives below.


Running bettym.pl Script


Installation on Windows PC:

If you plan on running the bettym.pl script on your Windows PC computer, you will need to install ActivePerl. ActivePerl is free and we use it ourselves to run our scripts.

  1. Open an MS-DOS window.

    Novice: To open an MS-DOS window, select "Run..." from the Windows Start menu and type the word "command" (no quotation marks). See "How to use an MS-DOS window".

  2. "cd" to the directory where you have the bettym.pl file (e.g.: "cd \www\bettym").

    Novice: See "How to use an MS-DOS window". The MS-DOS window lets you work with one directory at a time. The prompt tells you what the current working directory is. When you first open an MS-DOS window, its default is typically the directory "c:\windows\desktop" as indicated in the prompt. You need to change to the directory where you unpacked the bettym.pl file. So, type "cd \www\bettym" (no quotation marks). The command line prompt will change to "c:\www\bettym>".

  3. If you haven't already done so, edit the template files so that they match the look and feel of your website. Or you can just use one of the sample template sets provided.

  4. If you haven't already done so, edit the bettym.ini file. You may want to change some of the configuration variables. To edit the file, type "notepad bettym.ini" (no quotation marks) or double-click on the "Edit bettym.ini" icon.

  5. For testing purposes, you might want to set the "test" configuration variable in bettym.ini to "1000". This will cause bettym.pl to process only the first 1000 product records rather than process all product records (the datafeed file typically contains about 30,000 product records). Later when you are satisfied that the created HTML files look okay, you can change the "test" configuration variable back to "0" (i.e.: zero) so that all product records are processed.

    NOTE: If you set the write.html.gzip configuration variable to yes, you should install and test the htmlgz.pl script to verify that it works on your server before you run bettym.pl with "test" set to "0" (i.e.: zero; all products). There's no point in creating all files as .html.gz and then finding out that your web server can't handle them!

  6. You're ready to run the script. Type "perl bettym.pl" (no quotation marks). As the script runs, it will display status information as it progresses.

  7. After the script creates all your HTML files, they will be in the "html" directory (or the directory specified in the write.dir configuration variable). If you want, you can view the index.html file in your web browser -- open your web browser and view the file "c:\www\bettym\html\index.html" (the write.fn.home configuration variable specifies the filename "index.html" as the home page file).

  8. If you want to revise the templates, do that and then go back and re-run the bettym.pl script.

  9. If you set the "test" configuration variable to a non-zero value, change the "test" configuration variable back to "0" (i.e.: zero) and then re-run the bettym.pl script so that all product records are processed.

  10. After you run the bettym.pl script with the "test" configuration variable set to "0", there should be about 30,000 HTML files in the "html" directory that take up about 150MB of disk space (the number of HTML files and the amount of disk space used depends upon the number of records in the datafeed file).

  11. Use your FTP program to upload the contents of the "html" directory to your web server. Since there are about 30,000 HTML files, it may take several hours to upload all the files.

Advanced: If you have telnet/ssh access to your linux/unix server, you can use WinZip to zip the files on your Windows PC computer, FTP upload the .zip file to your server, login to telnet/ssh, then run the linux/unix unzip command. To see if the unzip command is installed on your linux/unix server, just type "unzip" and you should see usage instructions. To unzip the file filename.zip into the current directory (and create any new subdirectories if there are any subdirectories in the .zip file), use the linux/unix command "unzip filename.zip" (without quotation marks).


Installation on linux/unix server:

To run the bettym.pl script on your linux/unix server, you must have telnet/SSH access. If you don't have telnet/SSH access then you must run the bettym.pl script on your Windows PC instead.

  1. Edit your bettym.ini file if you have not already done so. In particular, be sure that the write.dir configuration variable specifies the path to the directory where you want the created HTML files to be written to.

  2. Run your FTP program and connect to your server.

  3. Create a directory called "bettym" inside your "cgi-bin" directory.

  4. In this new "bettym" directory, upload the following files using ASCII transfer mode:

    1. the bettym.pl script file.
    2. your bettym.ini configuratoin file.
    3. your bettym.key key file; without this, the script will run in demo mode.
    4. your .html template files
    5. the datafeed.csv and datafeed2.csv datafeed files.

  5. Change file permissions of bettym.pl to CHMOD 744 (rwx r-- r--).

  6. Login to your server using telnet/SSH.

  7. "cd" to the cgi-bin/bettym directory.

  8. For testing purposes, you might want to set the "test" configuration variable in bettym.ini to "1000". This will cause bettym.pl to process only the first 1000 product records rather than process all product records (the datafeed file typically contains about 30,000 product records). Once you are satisfied that the created HTML files look okay, you can change the "test" configuration variable back to "0" (i.e.: zero) so that all product records are processed.

    NOTE: If you set the write.html.gzip configuration variable to yes, you should install and test the htmlgz.pl script to verify that it works on your server before you run bettym.pl with "test" set to "0" (i.e.: zero; all products). There's no point in creating all files as .html.gz and then finding out that your web server can't handle them!

  9. Now type the following linux/unix command to run the bettym.pl script:

    nohup perl bettym.pl &

    The "&" at the end of the above command is required. This command will cause the bettym.pl script to be run in such a way that it will continue even if your internet connection is interrupted. If you have a dialup connection, you can disconnect at any time and the script will continue to completion. "nohup", an acronym for "no hangup", is a linux/unix command that causes the specified program to be run immune to disconnections.

    Status output is sent to the bettym-log.txt file. On some linux/unix systems output also appears on the screen; if that does not happen with your server, then you can type "tail -n50 -f bettym-log.txt" to view the log file (press ctrl-C to stop viewing).

    When you use this "nohup ..." command you can then disconnect (the script will keep running) and you can then reconnect later. When you reconnect later, cd to the directory where the bettym-log.txt log file is located then use "tail -n50 -f bettym-log.txt" to view the log file (press ctrl-C to stop viewing).

  10. After you run the bettym.pl script with the "test" configuration variable set to "0", there should be about 30,000 HTML files in the "html" directory that take up about 150MB of disk space (the number of HTML files and the amount of disk space used depends upon the number of records in the datafeed file).


Template Substitution Variables

To learn more about templates, see: Template Files


bettym.*

The bettym.* substitution variables can be used in all templates.

Variable Description
bettym.home

URL of BettyMills.com home page (link includes BettyMills.com affiliate ID). Use this as the URL in a link.

bettym.id

BettyMills.com affiliate ID. This variable is set in the bettym.key key file. If no valid key is found, then this variable is empty.

bettym.signup

URL of BettyMills.com sub-affiliate signup page (link includes BettyMills.com affiliate ID). Use this as the URL in a link.



cfg.*

The cfg.* substitution variables can be used in all templates.

Variable Description
cfg.NAME

The configuration variable cfg.NAME. For example, cfg.navbar.home would be the value of the navbar.home configuration variable.



credit.*

The credit.* substitution variables can be used in all templates.

Variable Description
credit

"Powered by c3scripts.com" credit line. Use this substitution variable if you want the credit line to appear in a specific location in your template. Otherwise, the credit line will be added just before the closing </BODY> tag. The credit line is contained inside a right-aligned table. See also: credit and credit.color configuration variables to not show the credit line and to set its color, respectivley.



date.*

The date.* substitution variables can be used in all templates.

Variable Description
date

Today's short date, e.g.: 01/31/2002

date.long

Today's long date, e.g.: Thursday, January 31, 2002

date FORMAT

Today's date formatted using FORMAT clock codes (see Clock Codes as described in the Associate Engine documentation).


Variable Description
date.asof

The "as of" short date, e.g.: 01/31/2002
The "as of" date is the last modified date of the primary datafeed file.

date.asof.long

The "as of" long date, e.g.: Thursday, January 31, 2002

date.asof FORMAT

The "as of" date formatted using FORMAT clock codes (see Clock Codes as described in the Associate Engine documentation).



item.*

The date.* substitution variables can be used only in an item template.

Variable Description
item.attrs.1

First attribute of item. This is empty if there is no first attribute.

item.attrs.2

Second attribute of item. This is empty if there is no second attribute.

item.attrs.3

Third attribute of item. This is empty if there is no third attribute.

item.attrs.all

Comma-separated list of item attributes. This is empty if there are no attributes.

item.attrs.list

Bulleted list of item attributes. This is empty if there are no attributes.

item.cats.*

Same as page.cats.*

item.desc

Description of item.

item.id

ID (SKU) of item.

item.img

URL of image of item.

item.img.thumb

URL of thumbnail image of item.

item.keywords

Keywords of item. If the item has no keywords, then this will be the name of the item.

item.mfg.img

URL of manufacturer logo. Example: <A HREF="{item.mfg.url}><IMG SRC="{item.mfg.img}" ALT="{item.mfg.name*}"></A>

item.mfg.name

Name of manufacturer. Example: <A HREF="{item.mfg.url}><IMG SRC="{item.mfg.img}" ALT="{item.mfg.name*}"></A>

item.mfg.url

URL of manufacturer. Example: <A HREF="{item.mfg.url}><IMG SRC="{item.mfg.img}" ALT="{item.mfg.name*}"></A>

item.name

Name of item.

item.price

Price of item. This will be the sale price if there is a sale price, otherwise this will be the retail price; see below.

item.price.retail

Retail price of item. Does include $ sign and cents, e.g.: "$153.00".

item.price.sale

Sale price of item. Does include $ sign and cents, e.g.: "$153.00".

item.save

Savings between retail price and sale price. This will be empty if the retail and sale prices are the same or if either is empty. Does include $ sign and cents, e.g.: $0.42

item.save.percent

Percentage savings between retail price and sale price. This will be empty if the retail and sale prices are the same or if either is empty. Includes % percent sign and is a whole number (no decimal place digits), e.g.: 17%

item.store

Store ID of item, e.g.: "Cleaning & Maintenance" or "Office Products".

item.units
item.units.code

Units of item, and code for units of measure.

item.units.code item.units Meaning
BD

(empty)

N bags per case

BG

per bag

per bag

BL

per bundle

per bundle

BX

per box

per box

CD

per card

per card

CS

per case

per case

CT

per carton

per carton

DP

(empty)

per dispenser

DR

(empty)

per drum

DY

(empty)

per display

DZ

per dozen

per dozen

EA

each

each

Ea

(empty)

each

GR

(empty)

gross

KT

per kit

per kit

M

(empty)

per shipment

PD

per pad

per pad

PK

per pack

per pack

PL

(empty)

per 5-Gallon pail

PP

(empty)

N Pads per Polypack

PR

per pair

per pair

RL

per roll

per roll

RM

per ream

per ream

ST

per set

per set

TB

per tube

per tube

(other)

(empty)

unknown code

item.url

URL to buy item.

item.weight

Weight of item.



page.*

The page.* substitution variables can be used in all templates unless otherwise indicated.

Variable Description
page.cats.main

Main category of page. If current page is a super-category index or home page, then this is empty.

page.cats.main.url

URL of main category at BettyMills.com website. If current page is a super-category index or home page, then this is empty.

page.cats.sub

Sub-category. If current page is a super-category or main-category index or home page, then this is empty.

page.cats.sub.url

URL of sub-category at BettyMills.com website. If current page is a super-category or main-category index or home page, then this is empty.

page.cats.sup

Super-category. If current page is home page, then this is empty.

page.cats.sup.url

URL of super-category at BettyMills.com website. If current page is home page, then this is empty.

page.keywords

Keywords of the current page. If this is a category page or the product has no keywords, then this will be the name of the page, that is, the name of the current category or product.

page.kids

Bulleted list of links to descendent pages. Can be used on the home page and category pages. Cannot be used on item pages.

page.kids.text

List of links to descendent pages. Can be used on the home page and category pages. Cannot be used on item pages.

page.name

Name of the current page. If this is an item page, then this will be the name of the product. Otherwise, if this is a category page, this will be the name of the category.

page.navbar

Navigation bar.

page.navbar.nohome

Navigation bar, without "Home" link.

page.pagebar

If the current category page is split across multiple pages, this will be links to next/previous pages otherwise it will be empty. This is empty for the home page and for item pages.

page.type.home
page.type.sup
page.type.main
page.type.sub
page.type.item

Type of the current page. Depending upon the type of the current page, one of these variables will have the value "1" and the others will have the vale "0" (zero). You can use it with an {if} directive.

Example:

<!--if page.type.sup-->
  this is a super-category page
<!--elsif page.type.main-->
  this is a main-category page
<!--elsif page.type.sub-->
  this is a sub-category page
<!--elsif page.type.item-->
  this is a product page
<!--endif-->

page.url

URL of current page at BettyMills.com website. Depending upon the current page, this is equivalent to one of:

  • bettym.home (home page)
  • page.cats.sup.url (super-category page)
  • page.cats.main.url (main category page)
  • page.cats.sub.url (sub-category page)
  • item.url (item page)


path.*

The path.* substitution variables can be used in all templates.

Variable Description
path.home

Relative directory path to the home page directory. For example, to access the home page from within any template, you could use:

<A HREF="{path.home}/{write.fn.home}>Home</A>

path.img

Relative directory path to the images directory which contains images used by some templates (note: not all template sets use graphics such as "Add to Cart"). To use a template image in a template, preceed its filename with {path.img}, such as:

<IMG SRC="{path.img}/buy.gif">

See also: img.dir configuration variable.


Template Directives

To learn more about templates, see: Template Files


cfg

The cfg directive can be used in all templates.

Directive Description
cfg VARIABLE "VALUE"

Set the specified configuration variable VARIABLE to the specified VALUE.

Example:

<!--cfg navbar.link.style "color: white"-->

This sets the navbar.link.style configuration variable to "color: white"

Duration: The duration of the cfg directive is temporary and only applies to the current template.

Read-Only: Some configuration variables are "read-only" and cannot be set inside a template using the cfg directive, e.g.: make.home and bettym.id. Instead, set those configuration variables globally in the .ini configuration file.

if Directive: All the cfg directives are processed, even those that are inside an if directive that evaluates to false.



if

The if directive can be used in all templates.

The if directive allows for conditional inclusion or exclusion of sections of HTML depending upon the specified condition. The simplest format of the if directive is:

{if CONDITION}
   some HTML to be included if CONDITION is true
{endif}

or, alternatively, you can use the equivalent <!--...--> style:

<!--if CONDITION-->
   some HTML to be included if CONDITION is true
<!--endif-->

Note: For each particular set of if/endif, the style of the if (i.e.: {if} or <!--if-->) must be the same as the style of the endif (i.e.: {endif} or <!--endif-->). You cannot use {if} and then close it off with <!--endif-->; you would have to use {endif} in that case; and vice versa.

If the CONDITION turns out to be true (e.g. "Is the price less than $100?"), then everything up to the endif is included. If the CONDITION turns out to be false, then everything up to the endif is excluded.

You can also specify an else section that will be included if the condition is false. That way you can alternatively include the first section or the second section depending upon the CONDITION. Example:

{if CONDITION}
   some HTML to be included if CONDITION is true
{else}
   some HTML to be included if CONDITION is false
{endif}

or, alternatively, you can use the equivalent <!--...--> style:

<!--if CONDITION-->
   some HTML to be included if CONDITION is true
<!--else-->
   some HTML to be included if CONDITION is false
<!--endif-->

Note: For each particular set of if/endif, the style of the if (i.e.: {if} or <!--if-->) must be the same as the style of the endif (i.e.: {endif} or <!--endif-->). You cannot use {if} and then close it off with <!--endif-->; you would have to use {endif} in that case; and vice versa.

You can also specify optional elsif CONDITION sections. Each CONDITION is evaluated in turn. If one is found to be true, then that section is included only, otherwise the else section is included (if present). Example:

{if CONDITION1}
   some HTML to be included if CONDITION1 is true
{elsif CONDITION2}
   some HTML to be included if CONDITION2 is true
{elsif CONDITION3}
   some HTML to be included if CONDITION3 is true
   {else}
   some HTML to be included if CONDITION3 is false
   {endif}
{endif}

The CONDITION can be a VARIABLE or an EXPRESSION. See the following table:

Directive Description
if VARIABLE

Conditional if. If VARIABLE is non-empty and not value zero then keep everything up to next matching elsif or else or endif. Example:

{if cfg.credit}
   Powered by c3scripts.com
{else}
   no credit
{endif}

if !VARIABLE

Negated conditional if. If VARIABLE is empty or is value zero then keep everything up to next matching elsif or else or endif. This is the opposite of what {if VARIABLE} does.

Note: There is no space between the ! and VARIABLE.

Example:

{if !cfg.credit}
   no credit
{else}
   Powered by c3scripts.com
{endif}

if EXPRESSION

Conditional if. If EXPRESSION is true then keep everything up to next matching elsif or else or endif.

The format of the EXPRESSION is:

VARIABLE OPERATOR "VALUE"

Note: The " quotation marks around the VALUE are required only if VALUE contains spaces, e.g.: "hot water".

OPERATOR indicates how the VARIABLE and VALUE are to be compared, e.g.: = compares for an exact match. See tables below for meanings of the comparison operators and of the pattern match operators.

Example:

{if item.price > 100}
   This item is over $100
{else}
   This item is $100 or less
{endif}


Comparison
Operator
Meaning Example

<

Less than.

item.price < 100

<=
=<

Less than or equal.

item.price <= 100
item.price =< 100

=
==
is

Equal.

item.price = 100
item.price == 100
item.price is 100

!=
<>
!is
isnot

Not equal.

item.price !=100
item.price <> 100
item.price !is 100
item.price isnot 100

>=
=>

Equal or greater than.

item.price >= 100
item.price => 100

>

Greater than.

item.price > 99.95

Note: If both VARIABLE and VALUE are numeric then they are compared numerically; otherwise, they are compared lexicographically (case-insensitive text comparison).

Pattern Match Operator Meaning Example

^~

Starts with VALUE text followed by a word break (e.g.: space, comma, dash, etc.) (note: "cat" would not match "caterpillar").

page.name ^~ "soap"

^*

Starts with VALUE text (note: "cat" would match "caterpillar").

page.name ^* "soap"

~^~

Contains VALUE text preceeded and followed by a word break (e.g.: space, comma, dash, etc.) (note: "cat" would only match word "cat"). Note: Will not match at the start or end; will only match somewhere in the middle.

page.name ~^~ "soap"

*^*

Contains VALUE text anywhere except at start or end (note: "cat" would match "cat", "catch", "vacation", etc.) Note: Will not match at the start or end; will only match somewhere in the middle.

page.name *^* "soap"

~

Contains VALUE text preceeded and followed by a word break (e.g.: space, comma, dash, etc.) (note: "cat" would only match word "cat"). Note: Can match at the start or end or somewhere in the middle.

page.name ~ "soap"

*

Contains VALUE text anywhere (note: "cat" would match "cat", "catch", "vacation", etc.)

page.name * "soap"

~^

Ends with VALUE text preceeded by a word break (e.g.: space, comma, dash, etc.) (note: "pillar" would not match "caterpillar").

page.name ~^ "soap"

*^

Ends with VALUE text. (note: "pillar" would match "caterpillar").

page.name *^ "soap"

Acronyms:

  • ^ : anchor the match to start, end, or somewhere in between.
  • * : wildcard match with partial words, e.g.: cat in caterpillar.
  • ~ : match on complete words, e.g.: cat will not match caterpillar.

Word List: For a pattern match, the VALUE can be a list of words/phrases to match, e.g.: "hot water|warm drink|ice" would match any of the words/phrases "hot water", "warm drink", or "ice". This is useful if you want to match a word and its plural, e.g.: "beverage|beverages" .

if !EXPRESSION

Negated conditional if. If EXPRESSION is flase then keep everything up to next matching else or endif. This is the opposite of what if EXPRESSION does (see above).

Note: There is no space between the ! and EXPRESSION.

Note: Unlike other programming languages, the boolean negation operator ! has lower precedence than the OPERATOR. Thus the expression !VARIABLE > VALUE is evaluated internally as !(VARIABLE > VALUE) rather than (!VARIABLE) > VALUE.

if ?VARIABLE

Conditional if. If VARIABLE is defined then keep everything up to next matching elsif or else or endif.

Note: There is no space between the ? and VARIABLE.

Example:

{if ?cfg.myvariable}
   myvariable is {cfg.myvariable}
{else}
   myvariable has no value
{endif}

The condition can be negated using the format:
if !?VARIABLE
which can be read as "if not defined VARIABLE, then ..."



include.*

The include.* directive can be used in all templates.

Variable Description
include FILENAME

Include the specified file FILENAME located in the include directory (see include.dir configuration variable). Do not include the filename extension (.html, .htm, .shtml, .txt) as part of FILENAME. If the file contains a <BODY> tag, then only the contents of the <BODY> is inserted instead of all of the file's contents. For example, {include hdr} would include file hdr.html

include.all FILENAME

Include all of the specified file FILENAME located in the include directory (see include.dir configuration variable). Do not include the filename extension (.html, .htm, .shtml, .txt) as part of FILENAME. For example, {include.all hdr} would include file hdr.html


htmlgz.pl Script

Use of the htmlgz.pl script is optional. You do not have to use it.


Note: The htmlgz.pl script works only on linux/unix web servers; it will not work on Windows NT servers. This limitation is because mod_rewrite is required.

IMPORTANT: Use of Server-Side-Includes (SSI) is restricted when using the htmlgz.pl script. See "Disadvantages" below.


Purpose

The htmlgz.pl script lets you save disk space on your web server by allowing you to have your HTML files as compressed .html.gz files (.gz is the filename extension associated with the linux/unix gzip compression program).

When a user requests any .html file, the htmlgz.pl script will decompress the corresponding .html.gz file "on-the-fly" and show the original HTML to the user. This is all transparent to the user; they think that they are accessing a .html file.

Advantages of using htmlgz.pl:

Disadvantages of using htmlgz.pl:


Creation of .html.gz files

To have bettym.pl create .html.gz files rather than .html files, set the write.html.gzip configuration variable in bettym.ini to yes.

If you already have .html files, you can compress them to .html.gz files by using the linux/unix gzip compression program. To do this, telnet/SSH into your web server and cd to the directory that contains your .html files then type gzip *.html (this command compresses all .html files in the current directory) or if your files are in several subdirectories, you can type:

find -name '*.html' | xargs gzip

The above command will compress all .html files in the current directory and in all subdirectories. If necessary, you can add -f to the end of the above command (after gzip) to force overwriting of existing .html.gz files.


Installation instructions

  1. Unpack the htmlgz-######.zip (or htmlgz-######.tar.gz) file. It is found in the bettym-######.zip (or bettym-######.tar.gz) file. The ###### will be a number indicating the version number.

    If you are logged into your web server using telnet/SSH, then you can unpack the .tar.gz file by using the following command:

    gzip -c -d htmlgz*.tar.gz | tar xf -

    When you unpack the file, you will get:

    File Description

    htmlgz.pl

    The htmlgz.pl script.

    htmlgz-htaccess.txt

    Sample .htaccess file.

    test.html.gz

    Test file to verify installation of htmlgz.pl.


  2. Upload htmlgz.pl to your cgi-bin directory using ASCII mode.

    Note: If your web server uses some other directory than cgi-bin for scripts, such as cgi-local or cgi, then upload htmlgz.pl there instead. When you get to Step 4 below, read the Note.

  3. Use CHMOD 755 on htmlgz.pl to enable execute permissions so that the htmlgz.pl script can be run.

  4. Open htmlgz-access.txt and copy its contents to your .htaccess file located in the root directory of your website, i.e.: in the directory where your home page is located. If you do not already have a .htaccess file in that directory, then create a blank file and then copy the contents of htmlgz-access.txt into it.

    Note: If your web server uses some other directory than cgi-bin for scripts, such as cgi-local or cgi, then you must modify the lines that you added to your .htaccess file so that the text /cgi-bin/htmlgz.pl in the last line instead says /cgi-local/htmlgz.pl (or whatever directory you use instead of "cgi-bin").

  5. Upload test.html.gz to the root directory of your web server using BINARY mode. You must use BINARY mode for this particular upload since .html.gz files are BINARY files (just like a Windows .zip file is a binary file).

  6. In your web browser, go to http://www.DOMAIN.com/test.html (substitute in your own domain name); be sure to type test.html; do not type test.html.gz. You should see a webpage saying that htmlgz.pl is working.

    1. "403 Forbidden" Error: If you get this error, then:

      1. Edit your .htaccess file and add the following line at the top:

        Options FollowSymLinks

      2. Verify that your .htaccess file has been updated as indicated above in Step 4.

      3. Verify with your hosting company that RewriteEngine has not been disabled. If the hosting company has disabled RewriteEngine then you cannot enable it via your .htaccess file; your hosting company has to enable it. It may also be necessary for your hosting company to enable Options FollowSymLinks

    2. "404 File Not Found" Error: If you get this error, verify that your .htaccess file has been updated as indicated above in Step 4.

    3. "500 Internal Server Error": If you get this error, then:

      1. Verify that htmlgz.pl was uploaded in ASCII mode.

      2. Verify that test.html.gz was uploaded in BINARY mode. All .html.gz files are binary files.

      3. Verify that the file permissions of htmlgz.pl were set using CHMOD 755.

      4. Verify that the file ownership (user & group) of test.html.gz is correct. If not, change it to your user & group using the linux/unix chown user:group filename command.

      5. If necessary, change the first line of htmlgz.pl if perl is at a different path then /usr/local/bin/perl on your web server. If you have other perl scripts on your web server that you know work, see what their first line says and use the same first line.





E.&O.E.; © Cusimano.Com Corporation; www.c3scripts.com