Perlshop 4 - Creating Catalog Pages

The base content of this page was taken from the original Perlshop 3 manual. Minor additions and corrections have been made so that the content properly reflects Perlshop 4.

Table of Contents:

Creating the Catalog Pages
1. Catalog Page Format

Creating the Catalog Pages

Catalog Page Format

Important Note:
Every Perlshop HTML tag MUST be on a line by itself and the ITEM_CODE tag MUST be the last tag before the closing </form> tag.
1. Entering the Store Using a Form:
  You may have a page with a submit button on it to enter the store. You can add the button to one of your existing pages, or you can create a new entry page. The HTML for the form to create the button should have the following tags:
  1. <form method="post" action="http://www.yourdomain.com/cgi-bin/perlshop.cgi">
  2. <input type="submit" name="dummy" value="ENTER">
  3. <input type="hidden" name="ACTION" value="Start Shopping">
  4. <input type="hidden" name="thispage" value="page1.html">
  5. <input type="hidden" name="ORDER_ID" value="!ORDERID!">
  6. </form>
(NOTE: You can not use the !MYURL! option for the ACTION part of the <form...> tag here.)

The text of the Submit button can be anything you like (change the text of the 'value=' for the 'input type="hidden" name="ACTION"' tag), but the SUBMIT tag must have contain: value="ENTER".
Server Independence
Instead of using a hardcoded URL on your catalog pages, you can use the !MYURL! and !MYWWW! tags. If you ever move your catalog to another server or domain, you won't have to change all the references to your URL.
1. !MYURL!
  Use this as the action field for a form tag. For example:
  <form method="post" action="!MYURL!">
  
  Use this as the URL reference in a link:
  <a href="!MYURL!?action=thispage&thispage=page1.html&ORDER_ID=!ORDERID!">
2. !MYWWW!
  Use this as the URL for non-cgi references (e.g. images). For example:
  <img src="!MYWWW!/images/logo.gif">

Built-In Navigation tags
Each page of your catalog that you create can have a tag on the first line of the page that has links to the previous and next pages of the catalog. For example, the tag for the first line of page2 of the catalog would look like:


(If page1.html was the first page, then on page1.html you would use page1.html as the prevpage. If the last page was page3.html, then on page3.html you would use page3.html as the nextpage).

This tag is optional, and if not using it, you can set the $add_navigation variable to 'no'.

Custom Navigation tags
You can create a menu navigation system for your catalog by using either a submit button or <a href ...> link for each destination. These buttons or links can appear either on a menu page just after your Catalog Entry Page, or on any of your individual catalog item pages, or both.
1. Using Forms
  Each submit button would have the format shown below (with 'name="none"' for the SUBMIT tag), but with a different file title for the VALUE of the hidden 'name="thispage"' tag. For example:
  
  <form method="post" action="!MYURL!"> <input type="submit" name="none" value="VCR'S"> <input type="hidden" name="thispage" value="page1.html"> <input type="hidden" name="ORDER_ID" value="!ORDERID!"> </form> <form method="post" action="!MYURL!"> <input type="submit" name="none" value="CAMERA'S"> <input type="hidden" name="thispage" value="page2.html"> <input type="hidden" name="ORDER_ID" value="!ORDERID!"> </form>
2. Using Links
  Each <a href ...> tag would have the following format:
  <a href="!MYURL!?action=thispage&thispage=page1.html&ORDER_ID=!ORDERID!"> THISPAGE</a>

Single Item Selection Forms
In this format, each individual item for sale in the catalog is contained within it's own HTML <form>...</form> block. You can have both Single Item and Multiple Item selection forms in the same catalog, and even within the same page. A sample Single Item Selection Form follows with an explanation of each line below it: <form method="post" action="!MYURL!"> <input type="submit" name="none" value="Press to Order"> <input type="hidden" name="ACTION" value="ORDER"> <input type="hidden" name="ORDER_ID" value="!ORDERID!"> <input type="hidden" name="ITEM_ID" value="12345"> <input type="hidden" name="ITEM_NAME" value="Learn to Surf"> Learn to Surf $212.98 <br> <input type="hidden" name="ITEM_PRICE" value="212.98"> <input type="hidden" name="thispage" value=page1.html> Qty:<input type="text" SIZE=3 MaxLength=3 name="QTY" value="1"> This book is especially good for beginners. <br> <input type="hidden" name="ITEM_CODE" value="!ITEMCODE!"> </form>
Description of each line above:
1. This is the opening form tag with the location of the perlshop.cgi program on your server
2. This creates a submit button on the catalog page with the text."Press to Order", you can use any text you want to create the button.
3. This is a hidden field that tells the perlshop script to process the 'ORDER' action command.
4. This is a hidden field that has a placeholder !ORDERID! that will be replaced automatically by the perlshop script with the actual unique invoice number for this shopping session.
5. This is a hidden field whose value should be set to item number you have assigned for this catalog item. Each item number must be unique.
6. This is a hidden field whose value should be set to the name of the item.
7. This is the name of the item, and the price, as it will appear on the catalog page.
8. This is a hidden field whose value should be set to the price of the item. The price should be in the format '999999.99' Commas and a leading dollar sign are optional. There is no limit on the actual price of the item.
9. This is a hidden field whose value should be set to the actual file title of the page that this catalog item is located in.
10. This is the Quantity field that will appear on the form whose value is the default number of items that will be ordered if a customer orders this item.
11. This is some descriptive text you can add if the item name does not sufficiently describe the item being ordered.
12. This is a hidden field that has a placeholder !ITEMCODE! that will be replaced automatically by the perlshop script with a unique digital signature generated for this catalog item and shopping session only
13. This is the closing form tag.

Multiple Item Selection Forms
This format allows for ordering multiple items with one press of the 'ORDER' sumission button. More than one item is contained within the same HTML <form>...</form> block. You can have both Multiple Item and Single Item selection forms in the same catalog, and even within the same page. A sample Multiple Item Selection form follows, note that there is only one of each of the 'form', 'submit', 'ORDER_ID', 'ITEM_CODE', and 'thispage' tags.

<form method="post" action="!MYURL!"> <input type="hidden" name="ITEM_ID" value="12348"> <input type="hidden" name="ITEM_NAME" value="Learn to Surf in 623 Days"> Learn to Surf in 623 Days $15.98 <input type="hidden" name="ITEM_PRICE" value="15.98"> Qty:<input type="text" size="3" MaxLength="3" name="QTY" value="0"> Learn Surfing at your own rate. <input type="hidden" name="ITEM_ID" value="12349"> <input type="hidden" name="ITEM_NAME" value=" Learn to Surf in 53 easy lessons"> Learn to Surf in 53 easy lessons $31.98 <input type="hidden" name="ITEM_PRICE" value="31.98"> Qty:<input type="text" SIZE=3 MaxLength=3 name="QTY" value="0"> Easy guide to learning to Surf. <input type="submit" name="none" value="Press to Order"> <input type="hidden" name="ACTION" value="ORDER"> <input type="hidden" name="ORDER_ID" value="!ORDERID!"> <input type="hidden" name="thispage" value="multi.html"> <input type="hidden" name="ITEM_CODE" value="!ITEMCODE!"> </form>

Optional Tags
You can include the standard Server-Side include tags (SSI tags) on your catalog pages, Perlshop will emulate the server and process the SSI tags itself. The variable $allow_ssi_cgi can be set to allow the use of the SSI cgi command to run cgi programs, but this creates a BIG security hole, and should not be enabled unless absolutely necessary AND you know what you are doing!

The following HTML tags are optional:
1. WEIGHT
  This 'type=hidden' tag can be used if you want to calculate the shipping charges based on weight. The value of the tag should be the shipping weight of the item. If you want to use this tag, you must change the value of the '$weight_caption' variable (eg. $weight_caption="Weight").
2. TAXTYPE
  This 'type=hidden' tag can be used if some of the items that you sell are taxable, and some are not. The default is to add tax (if you have made an entry in the '@Tax_States' variable), but you can override it for individual items by using a tag like this one:
  <input type="hidden" name="ITEM_TAXTYPE" value="none">
3. OPTIONx
  These tags can be used to specify any attributes of the items that you sell. For example, this tag can be used to specify the Color or Size, or any other descriptive attributes of your items. You can have up to three different OPTION tags. If you want to use this tag, you must change the value of the '$option1_caption' variable to the name of the option (e.g. $option1_caption = "Color"), and so on for each option.
  (You can let the user pick the value of the option by creating listboxes, radio buttons, or even through an input field.)
4. StayOnPage
  By placing a tag within the <form>...</form> block, this tag can be used to override the value of the '$stay_on_page' variable in the script. For example, the following tag allows the user to change the default value from 'no' to 'yes' by selecting a checkbox:
  <input type=checkbox name="StayOnPage" value="YES">

Order of HTML Tags
The order of the HTML Tags is Very Important!
1. The 'ITEM_CODE' tag MUST be the very last tag just before the closing </form> tag.
2. If any of the optional tags 'ITEM_WEIGHT', 'ITEM_TAXTYPE', or 'ITEM_OPTIONx' exist, then they MUST appear before both the 'ITEM_ID' and 'ITEM_PRICE' tags.
3. Each HTML Tag Should be on a line by itself.