DySE™ Script : Documentation
Home > DySE™ > Documentation   Updated: 26-Nov-2008

DySE™ Script Documentation

A video tutorial is available showing how to install DySE™. Click here to view the video tutorial.

How to read this documentation It is recommended that you start at the beginning of this document and read the chapters in order. Technical reference material that you only need to refer to when needed is located at the end of this documentation. The following icons are used:   Very important note.   Informational note.   Cautionary note.   Novice user note.   Unimplemented feature.   Tip.

Note:   "cgi-bin" directory The instructions in this documentation assume that your web server has a directory named cgi-bin where scripts are to be stored on your web server. Some web servers use a different name for this directory, such as: cgi-local, or cgi, or mainwebsite_cgi or something similar. In that case, where you see cgi-bin in any instruction, substitute it with the directory name that your web server uses.

» 1. Introduction to DySE™

This documentation provides:

1. Web server requirements.
2. An overview of DySE™ (Dynamic Store Engine).
3. Instructions on how to install the DySE™ viewer (view.pl).
4. Instructions on how to install and run a DySE™ module (make.pl).
5. Description of DySE™ module templates.

---

Web Server Requirements

DySE™ consists of cgi-bin perl scripts that you install on your linux/unix web server. The scripts cannot be run on your Windows personal computer and are not intended for a novice user. Experience using an FTP program and uploading cgi-bin perl scripts is requiring; perl programming experience is not required.

Important:   Web Server Requirements To be able to use DySE™, your web server must meet the following requirements: linux/unix web server with cgi-bin enabled. FTP enabled so you can upload files using FTP. mod_rewrite (.htaccess) enabled. 128 KB free disk space on web server. Additional disk space required by each DySE™ module database/template files; typically from 2 MB to 124 MB; see Merchant Module Sizes. (optional) Telnet/SSH login access enabled. (optional but recommended) Perl module LWP::Simple installed on your web server (this Perl module is used for internet access). If not installed, DySE™ will still work but auto-downloading of the merchant's datafeed will not be possible and you must manually download the merchant's datafeed file then upload it to your web server.

---

Overview of DySE™

DySE™ (short for "Dynamic Store Engine", pronounced "dice") is a modular system that makes it easy to quickly add products to your website. And because of its modularity, once you learn how to add one merchant, you use basically the same steps to add a different merchant. This modularity significantly reduces the learning curve.

The DySE™ system consists of two parts:

1. DySE™ Merchant Module: A DySE™ module for each merchant. The module consists of two components:

   1. cgi-bin perl script called make.pl that downloads the merchant's datafeed file and creates a product database file of that merchant's products.

   2. Customizable templates used when showing the products to the user.

   You run the make.pl script whenever you want to update the product database, such as once a day/week/month/quarter/etc. (can be run periodically via a cronjob). Each DySE™ module (make.pl script and templates) is designed to work with a particular merchant. For example, the DySE::InstrumentPro module is designed specifically for InstrumentPro.com.

   Note: If you want us to create a DySE™ module for a particular merchant, contact us (see also: Merchant FAQ).

2. DySE™ Viewer: The DySE™ viewer (view.pl) to access the product databases and output results to the user. The view.pl script runs (via mod_rewrite) each time the user accesses your website. The view.pl script is not specific to any merchant; the same view.pl script is used for all merchants. You can have more than one merchant on your website and you only need to install one copy of the view.pl script. And, the templates for each merchant all work the same way thus making it easier to modify/make templates. You can even use a default set of templates so all merchants on your website have a common look-and-feel.

---

Overview of Installing DySE™ System

Installing DySE™ consists of the following steps that are detailed in the rest of this documentation:

1. Request a DySE™ Merchant Key to unlock DySE™ from demo mode. Keys are free.
2. Download, unzip, and install the DySE™ view.pl viewer script.
3. Download, unzip, and install a DySE™ merchant module (make.pl script and template files).
4. Edit .htaccess file so web accesses are redirected to view.pl script via mod_rewrite.
5. Run the make.pl script to download the datafeed and make the database file.
6. Access web pages in your web browser to make sure the installation works properly.
7. If you want to add another merchant, repeat steps 3 through 6.

A video tutorial is available showing how to install DySE™. Click here to view the video tutorial.

---

A Brief Introduction to mod_rewrite

mod_rewrite is a built-in part of Apache web servers. It allows you to redirect one web address to another web address. The user sees the original web address in the Address bar of their web browser but is actually accessing something else on the web server. This redirection is what DySE™ is based on.

For example, if your website has the DySE::InstrumentPro merchant module (module for merchant InstrumentPro.com), when the user accesses /keyboards-midi/casio-lk-45-61-key.html then mod_rewrite internally redirects the web server to instead access /cgi-bin/dyse/view.pl?merch=instrumentpro&dir=&path=keyboards-midi/casio-lk-45-61-key.html which runs view.pl (with the specified parameters) and view.pl dynamically outputs the HTML for the "Keyboards/Midi > Casio LK-45 61 Key" product page. The user thinks they are accessing a .html file but the web server is actually running the view.pl script.

The configuration of mod_rewrite is specified in a .htaccess file (a text file) located in the main directory of your website.

» 2. DySE™ Merchant Module Sizes

Approximate sizes for each DySE™ Merchant Module are shown in the following table. Note: These numbers are approximate and will change when the merchant changes their product datafeed. The make.pl Time varies depending upon server capabilities and current server load.

Some disk space can be freed up by deleting the datafeed files after make.pl has completed. And, if you have multiple websites (on the same server) that use a particular script, one common datafeed file can be shared among them (using linux symbolic links) thus elminating duplicate copies of the datafeed. And, if you are using the same affiliate ID on more than one website, one common datafeed file can be shared among them (using linux symbolic links) thus eliminating duplicate copies of the database file.

» 3. DySE™ Merchant Keys

DySE™ runs in demo mode until you obtain a DySE™ Merchant Key file from us. Keys are free.

CRITICAL:   Demo mode In demo mode, all product links go to the merchant's home page and have no affiliate ID. After you install your DySE™ Merchant Key file, your affiliate ID will be included in your links.

Each key file is for a specific merchant affiliate ID. If you are using several DySE™ Merchant Modules, you will need to obtain a a DySE™ Merchant Key file for each one.

Click here to request a key file

While you are waiting to receive your key file, you can continue with the rest of the installation.

» 4. Download DySE™ view.pl

Important:   Install view.pl only once You only have to install the DySE™ view.pl script once. If you previously installed view.pl with another DySE™ merchant module, skip forward to the section "Download DySE™ Merchant Module".

1. Click here for the DySE™ view.pl download directory.

   The DySE™ view.pl viewer script is available for download as a Windows .zip file (dyse-yymmdd.zip) and as a linux/unix .tar.gz file (dyse-yymmdd.tar.gz).

   Note:   Version Number in filenames The yymmdd will be a 6-digit version number (year, month, date); for example, dyse-050123 indicates DySE™ view.pl version 5.01.23 released on January 23, 2005.

2. Download either the dyse-yymmdd.zip file or the dyse-yymmdd.tar.gz file if you prefer that file format.

   Important:   Download Directory Save the file into a directory that you can remember and can open later (e.g.: My Documents).

Important:   Substitutions In the following instructions, replace yymmdd with the 6-digit version number that appears in the name of the file that you downloaded.

» 5. Install DySE™ view.pl

Important:   Install view.pl only once You only have to install the DySE™ view.pl script once. If you previously installed view.pl with another DySE™ merchant module, skip forward to the section "Download DySE™ Merchant Module".

---

» cgi-bin Directory Structure

Before installing DySE™ view.pl and merchant modules, let's first look at what your cgi-bin directory will look like after the installation is completed:

Everything related to DySE™ goes in the /cgi-bin/dyse directory. The only exception to this is the .htaccess file and that goes in the / main directory of your website.

Inside /cgi-bin/dyse, each merchant module has its own sub-directory. That's also where view.pl goes. So, everything related to DySE::InstrumentPro goes in /cgi-bin/dyse/instrumentpro and everything related to DySE::Calendars goes in /cgi-bin/dyse/calendars and so on for other modules (shown above as merchantA ... merchantD). Each module gets its own directory. DySE™ can support an unlimited number of merchant modules (not just 4 as shown above). The default directory contains default templates.

---

» Installation

The DySE™ view.pl script is available for download as a Windows .zip file, as a Windows .exe self-extracting .zip file, and as a linux/unix .tar.gz file. Both download files have essentially the same contents.

Depending upon whether you want to download and unpack the .zip file (or .exe file) or the .tar.gz file, follow the instructions in one of the following sections:

• Install from .zip File (or .exe Self-Extracting .zip File)
• Install from .tar.gz File

---

» Contents

The .zip file, .exe file, and the .tar.gz file contain the following files:

Item Description Edit view.pl.lnk (in .zip file only). Windows shortcut to open view.pl for editing using Windows Notepad program. htaccess-directory.txt Sample .htaccess file to make store show up at a directory of the website, such as at www.domain.com/shop/ htaccess-homepage.txt Sample .htaccess file to make store show up at the home page of the website, such as at www.domain.com/ view.pl The DySE™ viewer script. default/ Directory containing default templates and graphic files used by those templates. The default templates are optional and are only used by the viewer if a merchant module does not have its own templates installed.

---

» Install from .zip File (or .exe Self-Extracting .zip File)

Important:   Substitutions In the following instructions, replace yymmdd with the 6-digit version number that appears in the name of the file that you downloaded.

1. Depending upon what file you downloaded, unpack either the dyse-yymmdd.zip file or the dyse-yymmdd.exe file:

   • .zip file: Open the dyse-yymmdd.zip file using your compression software (e.g.: CuteZip, WinZip) and unpack it to the folder where the .zip file itself is located (e.g.: My Documents) (or to some other folder that you regularly use for unpacking).

     Note: When unzipping the .zip file, be sure that your compression software is configured to recreate the .zip file's internal directory folder structure when unzipping, otherwise all the files will end up in one directory. For example, in WinZip, select menu item "Action > Extract..." and select the "Use folder names" checkbox option.

   • .exe file: Open the dyse-yymmdd.exe file and click Unzip to unpack it. You can specify the folder where to unpack to (e.g.: My Documents) (or to some other folder that you regularly use for unpacking). Note: The unpacking process will create a "Cusimano.com Scripts" folder that contains the equivalent contents as the.zip file.

2. Open the folder where you just unpacked the .zip or .exe (e.g.: My Documents).

   Note: If you unpacked from the .exe, you will see a "Cusimano.com Scripts" folder; open it.

3. Rename the dyse-yymmdd folder to dyse

4. Run your FTP program.

   Novice User:   FTP program explained FTP stands for "File Transfer Protocol". You use an FTP program to upload files to your web server. This is different than uploading files to your web server using a web-based "control panel" that some hosting companies provide so you can manage files on your web server. The following FTP programs are from 3rd-party companies. Some Windows-based FTP programs are: FTP Desktop CuteFTP WS_FTP more ...   Some Macintosh-based FTP programs are: Fetch Interarchy more...

5. In your FTP program:
   On the web server, go into the cgi-bin directory.
   On your local hard drive, go into the directory where you unpacked the .zip file (e.g.: My Documents).

   Important:   cgi-bin directory is a special; do not create it yourself The cgi-bin directory on your web server (the directory may be called cgi-local or cgi or something similar) is a special directory. If it does not already exist on your web server, do not create it yourself. Ask your hosting company if cgi-bin is enabled on your website account and what the directory is named.

6. Select the dyse directory located on your computer and upload it into the cgi-bin directory.

   Novice User:   Upload a directory and all its contents in one step With most FTP programs, you can upload an entire directory and all its contents by merely selecting the directory (as if you were selecting a single file) and clicking the upload command of your FTP program (as if you were uploading a single file).

   You should now have something like the following file structure on your web server:

   Important:   ASCII vs. Binary Transfer Mode Some FTP programs automatically select ASCII transfer mode for text files (e.g.: .html, .txt) and select binary transfer mode for binary files (e.g.: .gif, .jpg). If binary files are uploaded using ASCII transfer mode, those files will be corrupted and will not work (e.g.: graphics appear damaged). And if ASCII files (specifically .pl files) are uploaded in binary, they will not work (e.g.: 500 Internal Server Error). If you FTP program does not automatically select the appropriate transfer mode, then you should upload everything using binary transfer mode. Then go back and reupload the /cgi-bin/dyse/view.pl file using ASCII transfer mode.

   
   

   Important:   Upload view.pl using ASCII mode If your FTP program does not automatically upload .pl files using ASCII transfer mode, then reupload the view.pl file using ASCII transfer mode. If you're not sure how to select ASCII transer mode, run your FTP program and press F1 and search for help on keyword "ascii". Some FTP programs (such as CuteFTP) automatically select ASCII or BINARY transfer mode depending upon the file type (e.g.: ASCII for .pl and .html text files, and BINARY for .gif and .jpg graphic files).

7. On the web server, go into the dyse directory. Select view.pl and enable all of its execute permissions using the CHMOD command of your FTP program (chmod 755).

   Novice User:   CHMOD explained Try right-clicking on the file and selecting CHMOD or Properties, or press F1 and search for help on keyword "chmod" or "permissions". Your FTP program may display a window with a box that you can type into or with checkboxes that you can click:

8. You can now exit your FTP program.

9. Continue to the section "Test DySE™ view.pl" below to test view.pl.

---

» Install from .tar.gz File

Important:   Substitutions In the following instructions, replace yymmdd with the 6-digit version number that appears in the name of the file that you downloaded.

1. Run your FTP program.

   Novice User:   FTP program explained FTP stands for "File Transfer Protocol". You use an FTP program to upload files to your web server. This is different than uploading files to your web server using a web-based "control panel" that some hosting companies provide so you can manage files on your web server. The following FTP programs are from 3rd-party companies. Some Windows-based FTP programs are: FTP Desktop CuteFTP WS_FTP more ...   Some Macintosh-based FTP programs are: Fetch Interarchy more...

2. In your FTP program:
   On the web server, go into the cgi-bin directory.
   On your local hard drive, go into the directory where you saved the .tar.gz file (e.g.: My Documents).

   Important:   cgi-bin directory is a special; do not create it yourself The cgi-bin directory on your web server (the directory may be called cgi-local or cgi or something similar) is a special directory. If it does not already exist on your web server, do not create it yourself. Ask your hosting company if cgi-bin is enabled on your website account and what the directory is named.

3. Depending upon what FTP program you use, you may need to select binary transfer mode before continuing. If you're not sure what transfer mode your FTP program will use, then just continue to the next step.

   Novice User:   Binary transfer mode In your FTP program, press F1 and search for help on keyword "binary".

4. Upload dyse-yymmdd.tar.gz into your cgi-bin directory.

5. You can now exit your FTP program.

6. Login using Telnet/SSH.

   Novice User:   Telnet/SSH explained Telnet/SSH is a program that you run on your computer that allows you to login to your web server and type commands to your web server, such as to run the make.pl script. PuTTY (for Windows computers) is an excellent Telnet/SSH program and it is free (download puty.exe).

7. Go into the cgi-bin directory (using the cd command). Then type the following command:

   tar  -zxf  dyse-yymmdd.tar.gz

   For example: tar  -zxf  dyse-050123.tar.gz

8. Rename the dyse-yymmdd directory to dyse by typing the following command:

   mv  dyse-yymmdd  dyse

   For example: mv  dyse-050123  dyse

   You should now have something like the following file structure on your web server:

   

9. Change the "owner:group" of the dyse directory (and its contents) by typing the following command:

   Important:   Characters In the following command, the "-R" must be a capital R, and there must be two dashes before "reference=."

   
   

   chown  -R  --reference=.  dyse

10. For security reasons, limit the read/write/execute permissions of the dyse directory and of all the files that it contains, by typing the following command:

    Important:   Characters In the following command, the "-R" must be a capital R

    
    

    chmod  -R  go-w  dyse

11. Enable the execute permissions of the view.pl file by typing the following command:

    chmod  755  dyse/view.pl

12. Continue to the section "Test DySE™ view.pl" below to test view.pl.

» 6. Test DySE™ view.pl

1. Run your web browser. Access view.pl on your web server using the following special test URL (change the domain to your domain name, and change cgi-bin if you use a different directory):

   http://www.domain.com/cgi-bin/dyse/view.pl

   For example: http://www.mydomainname.com/cgi-bin/dyse/view.pl

2. If view.pl is working properly, then you should see something like the following:

   DySE view.pl v5.01.23

   If you see an error then see below.

3. view.pl is working properly.
   Continue to the section "Download DySE™ Merchant Module" below.

---

» Web server generated errors with view.pl

Otherwise, you may see one of the following web server generated errors:

• 500 Internal Server Error:

  1. Run your FTP program and verify that all of the file execute permissions of the file /cgi-bin/dyse/view.pl are set (CHMOD 755).

     

  2. Run your FTP program and examine the permissions of the directory /cgi-bin/dyse (just like a file, a directory also has permissions that you can set). Some servers report an error if a directory is set to CHMOD 777 (all permissions enabled) since that creates a security hole. Change the permissions of the /cgi-bin/dyse directory (from CHMOD 777) to CHMOD 755 (or if that still does not work, then try CHMOD 775).

     

  3. Reupload the view.pl file using ASCII transfer mode of your FTP program.
     And set the execute permissions of view.pl (CHMOD 755).

     Novice User:   ASCII transfer mode explained FTP programs can upload files in either of two ways: ASCII transfer mode or Binary transfer mode. ASCII transfer mode is used to upload files such as text files and .pl files that contain text. Binary transfer mode is used to upload files that contain binary data such as .gif, .jpg, and .tar.gz files. With ASCII transfer mode, carriage return / linefeed (CRLF) characters are translated to what the server expects (Windows/Macintosh and servers handle CRLF characters differently). With binary transfer mode, all data is uploaded exactly as is. If you're not sure how to select ASCII transer mode, run your FTP program and press F1 and search for help on keyword "ascii".

  4. It is assumed that your perl path is /usr/local/bin/perl   If it is different on your web server, then edit view.pl and change the first line to the correct path (you can use the Edit view.pl shortcut found in the .zip file to edit the view.pl file using the Windows Notepad editor). Then reupload the view.pl file and set the execute permissions of view.pl (CHMOD 755).

     Novice User:   Perl path If you're not sure what your perl path is, then ask your hosting company (tip: check your hosting company's online help/FAQ section). On some servers, the perl path is /usr/bin/perl

  5. Some web servers are configured such that cgi-bin script files must have a filename that ends with .cgi rather than the standard .pl ending. If your server requires the .cgi ending then rename view.pl to view.cgi   If you are not sure if your server requires the .cgi ending or the standard .pl ending, ask your hosting company or just go ahead and try renaming view.pl to view.cgi (if still does not work, just rename it back to view.pl).

     Very Important:   If using .cgi then use .cgi throughout If the viewer works when you rename it to view.cgi, then you must keep the following points in mind as you go through the rest of the DySE™ documentation: When you install make.pl (instructions in the next few chapters), you will have to similarly rename make.pl to make.cgi When you install .htaccess (instructions in the next few chapters), you must change the line in the .htaccess where it says view.pl to view.cgi In the rest of the DySE™ instructions where it says to access a URL that ends with view.pl or make.pl, instead access view.cgi or make.cgi, respectively; otherwise you will get a 404 File Not Found error.

  6. If you have access to your web server's error_log file, look at the last few lines to help isolate the problem.

  7. In rare cases: If your server uses Ensim and view.pl was working but has now stopped (and all other .pl files on our server have also stopped), check that the linux system file /var/log/httpd/suexec_log has not exceeded 2GB in size (2GB is the maximum file size that linux allows for any one file). If so, have your system administrator delete the /var/log/httpd/suexec_log file. Note: This file is in the "real" filesystem, it is not in your website's virtual filesystem; therefore, only the system administrator has permission to delete it.

• 404 File Not Found:

  1. Retype the special test URL.

  2. Run your FTP program and verify that view.pl is in the /cgi-bin/dyse directory. If not, move it there.

• Your home page appears:

  • You probably have a .htaccess file that causes redirection to your home page when a file is not found (e.g.: ErrorDocument 404 /). Therefore, handle this error as a "404 File Not Found" error as indicated above.

  • It is also possible that a 500 Internal Server Error has occurred and that your hosting company has configured your server to redirect to the home page when such server errors occur. See 500 Internal Server Error above and try those solutions too.

» 7. Download DySE™ Merchant Module

As indicated in the Introduction to DySE™, DySE™ is a modular system consisting of a viewer (which you downloaded and installed as instructed above) and DySE™ merchant modules.

Listed below are the various DySE™ merchant modules.

DySE™ Merchant Module	Merchant	Download
DySE::AqAM v9.04.22	AquinasAndMore.com	Download
DySE::Audible v7.06.22	Audible.com	Download
DySE::BettyMills v7.06.22	BettyMills.com	Download
DySE::Calendars v8.04.13	Calendars.com	Download
DySE::CFB v7.06.22	CrazyforBargains.com	Download
DySE::Hono v7.06.22	HouseOfNutrition.com	Download
DySE::InstrumentPro v7.10.18	InstrumentPro.com	Download
DySE::KimmyShop v7.06.22	KimmyShop.com	Download
DySE::NS v9.03.20	NetShops.com	Download
DySE::Rockler v7.06.22	Rockler.com	Download
DySE::StubHub v9.04.26	StubHub.com	Download
more modules coming soon

1. Click on the "Download" link of the merchant module that you want to download.

   Each DySE™ merchant module is available for download as a Windows .zip file (dyse-merchant-yymmdd.zip) and as a linux/unix .tar.gz file (dyse-merchant-yymmdd.tar.gz).

   Note:   Filename The merchant will be the merchant name and the yymmdd will be a 6-digit number (year, month, date); for example, dyse-instrumentpro-050123 indicates DySE::InstumentPro version 5.01.23 released on January 23, 2005 (InstrumentPro.com DySE™ merchant module).

2. Download either the dyse-merchant-yymmdd.zip file or the dyse-merchant-yymmdd.tar.gz file if you prefer that file format.

   Important:   Download Directory Save the file into a directory that you can remember and can open later, such as My Documents.

Important:   Substitutions In the following instructions, replace merchant and yymmdd with the merchant module name and the 6-digit version number that appears in the name of the file that you downloaded.

» 8. Install DySE™ Merchant Module

The following are generalized instructions on how to install a DySE™ merchant module. Once you learn how to install a merchant module, you will know how to install any DySE™ merchant module. They all work the same way.

Each DySE™ merchant module is available for download as a Windows .zip file, a Windows .exe self-extracting .zip file, and as a linux/unix .tar.gz file. Both download files have essentially the same contents.

Depending upon whether you want to download and unpack the .zip file (or .exe file) or the .tar.gz file, follow the instructions in one of the following sections:

• Install from .zip File (or .exe Self-Extracting .zip File)
• Install from .tar.gz File

---

» Contents

In general, the .zip file, the .exe file, and the .tar.gz file of each DySE™ merchant module contains the following files:

Item Description Edit make.pl.lnk (in .zip file only). Windows shortcut to open make.pl for editing using Windows Notepad program. htaccess-directory.txt Sample .htaccess file to make store show up at a directory of the website, such as at www.domain.com/shop/ htaccess-homepage.txt Sample .htaccess file to make store show up at the home page of the website, such as at www.domain.com/ make.pl The DySE™ make script. You run this script. make2.pl Sub-script used internally by make.pl. You do not run this script. templates/ Directory containing templates and graphic files used by the templates. templates-set1/ templates-set2/ templates-set3/ templates-set4/ templates-set5/ templates-set6/ Additional template sets. Each directory contains templates and graphic files used by those templates. The number of template sets depends upon the particular merchant module. Some merchant modules contain less than 6 template sets.

FAQ:   What does make2.pl do? The make.pl program optionally runs the make2.pl program during the "process category items" section of the make process. It does this to prevent the web server's RAM memory usage from peaking and remaining high (which can happen if a category has a very large number of products). If make2.pl cannot run or is missing, then make.pl internally does the equivalent of what make2.pl would do.

---

» Install from .zip File (or .exe Self-Extracting .zip File)

Important:   Substitutions In the following instructions, replace merchant and yymmdd with the merchant module name and the 6-digit version number that appears in the name of the file that you downloaded.

1. Depending upon what file you downloaded, unpack either the dyse-merchant-yymmdd.zip file or the dyse-merchant-yymmdd.exe file:

   • .zip file: Open the dyse-merchant-yymmdd.zip file using your compression software (e.g.: CuteZip, WinZip) and unpack it to the folder where the .zip file itself is located (e.g.: My Documents) (or to some other folder that you regularly use for unpacking).

     Note: When unzipping the .zip file, be sure that your compression software is configured to recreate the .zip file's internal directory folder structure when unzipping, otherwise all the files will end up in one directory. For example, in WinZip, select menu item "Action > Extract..." and select the "Use folder names" checkbox option.

   • .exe file: Open the dyse-merchant-yymmdd.exe file and click Unzip to unpack it. You can specify the folder where to unpack to (e.g.: My Documents) (or to some other folder that you regularly use for unpacking). Note: The unpacking process will create a "Cusimano.com Scripts" folder that contains the equivalent contents as the.zip file.

2. Open the folder where you just unpacked the .zip or .exe (e.g.: My Documents).

   Note: If you unpacked from the .exe, you will see a "Cusimano.com Scripts" folder; open it.

3. Rename the dyse-merchant-yymmdd folder to merchant (for example, rename dyse-instrumentpro-050123 to instrumentpro).

   Important:   Use all lowercase Use all lowercase. For example, "instrumentpro" will work, while "InstrumentPro" will not work.

4. Run your FTP program.
   On the web server, go into the cgi-bin directory.
   On your local hard drive, go into the directory where you unpacked the .zip file (e.g.: My Documents).

5. Then go into the dyse sub-directory on your web server.

   Note:   /cgi-bin/dyse  Directory You created the /cgi-bin/dyse sub-directory when you installed the DySE™ viewer.

6. Select the merchant directory located on your computer (e.g.: instrumentpro directory) and upload it into the /cgi-bin/dyse sub-directory.

   Novice User:   Upload a directory and all its contents in one step With most FTP programs, you can upload an entire directory and all its contents by merely selecting the directory (as if you were selecting a single file) and clicking the upload command of your FTP program (as if you were uploading a single file).

   You should now have something like the following file structure on your web server:

   Important:   ASCII vs. Binary Transfer Mode Some FTP programs automatically select ASCII transfer mode for text files (e.g.: .html, .txt) and select binary transfer mode for binary files (e.g.: .gif, .jpg). If binary files are uploaded using ASCII transfer mode, those files will be corrupted and will not work (e.g.: graphics appear damaged). And if ASCII files (specifically .pl files) are uploaded in binary, they will not work (e.g.: 500 Internal Server Error). If you FTP program does not automatically select the appropriate transfer mode, then you should upload everything using binary transfer mode. Then go back and reupload the /cgi-bin/dyse/merchant/make.pl and /cgi-bin/dyse/merchant/make2.pl files using ASCII transfer mode.

7. On the web server, go into the merchant directory (e.g.: instrumentpro directory). Select make.pl and enable all of its execute permissions using the CHMOD command of your FTP program (chmod 755).

   Novice User:   CHMOD explained Try right-clicking on the file and selecting CHMOD or Properties, or press F1 and search for help on keyword "chmod" or "permissions". Your FTP program may display a window with a box that you can type into or with checkboxes that you can click:

8. Optional step: If you have created a make-ini.txt configuration file then upload it now. Upload it into the same directory where make.pl is located.

9. Continue to the section "Configure .htaccess File" below.

---

» Install from .tar.gz File

Important:   Substitutions In the following instructions, replace merchant and yymmdd with the merchant module name and the 6-digit version number that appears in the name of the file that you downloaded.

1. Run your FTP program and go into the cgi-bin directory on your web server.

2. Then go into the dyse sub-directory on your web server.

   Note:   /cgi-bin/dyse Directory You created the /cgi-bin/dyse sub-directory when you installed the DySE™ viewer.

   Depending upon what FTP program you use, you may need to select binary transfer mode before continuing. If you're not sure what transfer mode your FTP program will use, then just continue to the next step.

   Novice User:   Binary transfer mode In your FTP program, press F1 and search for help on keyword "binary".

3. Upload dyse-merchant-yymmdd.tar.gz into your /cgi-bin/dyse sub-directory.

4. You can now exit your FTP program.

5. Login using Telnet/SSH and go into the cgi-bin/dyse directory (using the cd command).
   Then type the following command:

   tar  -zxf  dyse-merchant-yymmdd.tar.gz

   For example: tar  -zxf  dyse-instrumentpro-050123.tar.gz

6. Rename the dyse-merchant-yymmdd directory to merchant by typing the following command:

   mv  dyse-merchant-yymmdd  merchant

   For example: mv  dyse-instrumentpro-050123  instrumentpro

   Important:   Use all lowercase Use all lowercase. For example, "instrumentpro" will work, while "InstrumentPro" will not work.

   You should now have something like the following file structure on your web server:

   

7. Change the "owner:group" of the merchant sub-directory (and its contents) by typing the following command:

   Important:   Characters In the following command, the "-R" must be a capital R, and there must be two dashes before "reference=."

   
   

   chown  -R  --reference=.  merchant

   For example: chown  -R  --reference=.  instrumentpro

8. For security reasons, limit the read/write/execute permissions of the merchant directory and of all the files that it contains, by typing the following command:

   Important:   Characters In the following command, the "-R" must be a capital R

   
   

   chmod  -R  go-w  merchant

   For example: chmod  -R  go-w  instrumentpro

9. Enable the execute permissions of the make.pl file by typing the following command:

   chmod  755  merchant/make.pl

   For example: chmod  755  instrumentpro/make.pl

10. Optional step: If you have created a make-ini.txt configuration file then upload it now. Upload it into the same directory where make.pl is located.

11. Continue to the section "Configure .htaccess File" below.

» 9. Configure .htaccess File

DySE™ uses mod_rewrite to internally redirect requests for .html files to the view.pl script. The user thinks they are accessing a .html file but the server is actually running the view.pl script.

The configuration of mod_rewrite is specified in a .htaccess file (a text file) located in the main directory of your website.

Important:   . in filename .htaccess The filename of the .htaccess file is .htaccess The prefix . (period) in the filename is required. Do not name the file htaccess without a . (period).

DySE™ can be set up (via the .htaccess file) to either display the merchant's products in a sub-directory of your website (e.g.: www.domain.com/instruments/) or at the / main directory of your website (e.g.: www.domain.com/). If your adding the products as a store section of an existing website or want to have more than one DySE™ merchant module on your website, then put the merchant in a sub-directory; otherwise, put the merchant at the main directory of your website.

Depending upon which directory you want the merchant's products to appear at, follow the instructions in one of the following sections:

• Products at Main Directory, or
• Products in Sub-Directory.

---

» Products at Main Directory

1. Add the following 7 lines to your .htaccess file located in the / main directory of your website. Either add these lines to the end of your existing .htaccess file, or create a new .htaccess file and put these lines into it.

   Options  +FollowSymLinks RewriteEngine  on RewriteBase   / RewriteCond   %{REQUEST_FILENAME}   -d RewriteRule   ^.+$   -   [L] RewriteCond   %{REQUEST_FILENAME}   !-f RewriteRule   ^(.*)$   cgi-bin/dyse/view.pl?merch=merchant&dir=&path=$1  [L]

   
   

   Novice: For an explanation of these 7 lines see: Brief Introduction to .htaccess File below.

   CRITICAL:   RewriteRule is one long line On your screen (or printout), the above RewriteRule might appear split onto two lines. The RewriteRule is one long line and ends at the [L]

   
   

   Very Important:   Substitutions In the above lines, you must do the following substitutions: Replace merchant with the name of the merchant module (e.g.: instrumentpro for the DySE::InstrumentPro merchant module; upper/lowercase does not matter for merchant). Replace cgi-bin with the name of your "cgi-bin" directory if different than "cgi-bin" (e.g.: "cgi-local" or "cgi"). Ask your hosting company if you are not sure what your "cgi-bin" directory is named. Note: The RewriteRule uses URL's. So if you need to change cgi-bin then change it to whatever directory name you would use in a URL to access your cgi-bin directory via a web browser. Use just the directory name (e.g.: cgi-bin, cgi, cgi-local, etc.). Do not include your domain name or any initial part of the directory path used internally by your server (e.g.: /public-html/).

   
   

   FAQ:   Why can't I see my .htaccess file ? See Why can't I see my .htaccess file with WS_FTP or CuteFTP?

   
   

   FAQ:   How do I install several DySE™ on one website ? See Multiple DySE™ Merchant Modules below. Be sure to read the subsection "Module Already Installed at /" if you want to have a DySE™ module at the / (root directory) as well as in subdirectories.

   
   

   Tip:   Where in .htaccess file to add the 7 lines Since your server processes .htaccess in order starting at the first line, add the lines after all other RewriteRule's. That's because the second RewriteRule is a "match all" RewriteRule (e.g.: pattern ^.*$) that matches all URL's that reach that point in the .htaccess file. After this RewriteRule, no subsequent RewriteRule's in the .htaccess file will be processed.

   
   

   Tip:   Copy lines from file provided To prevent typographical errors, open the text file htaccess-homepage.txt that came in dyse-view-yymmdd.zip (and dyse-view-yymmdd.tar.gz) and copy and paste the lines to your .htaccess file. WARNING: This sample .htaccess file is generic, and after you copy the lines, you must still do the substitutions of MERCHANT with the actual name of the merchant module that you are installing. See the next warning box.

   For example, to have the DySE::InstrumentPro module show up at www.domain.com/  you would use the following lines in .htaccess:

   Options  +FollowSymLinks RewriteEngine  on RewriteBase  / RewriteCond   %{REQUEST_FILENAME}   -d RewriteRule   ^.+$   -   [L] RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(.*)$  cgi-bin/dyse/view.pl?merch=instrumentpro&dir=&path=$1  [L]

   At this point, the DySE™ viewer is installed and mod_rewrite has been configured (via .htaccess) to run the DySE™ viewer whenever the / directory (or any sub-directory of it) is accessed.

2. If you are using Microsoft FrontPage, then see the section FrontPage and .htaccess below then come back to this point in these instructions.

3. IMPORTANT: When you perform the next step, you should see the following DySE™ generated error message. This error is expected and indicates that mod_rewrite is working properly. It is ok to see any of the following errors. The errors are:

   DySE Error: no data directory: 'merchant'. Run make.pl DySE Error: no database file: 'merchant'. Run make.pl DySE Error: unknown merchant: 'merchant'

4. Run your web browser.
   Access the / main directory at your website:

   http://www.domain.com/

   For example: http://www.mydomainname.com/

   If you see an error other than indicated above, then see below: Web server generated errors with .htaccess

5. .htaccess is working properly.
   Continue to the section "Run DySE™ Merchant Module" below.

---

» Products in Sub-Directory

1. Decide what directory name you want to use for the merchant. For example, to put the merchant at www.domain.com/shop/ the directory name would be shop   In the following instructions, replace dir with the directory name that you have chosen.

   Tip:   Multi-level directory name supported The dir directory can be more than one level deep. For example, you could use "shop/instruments" for dir so that the products show up at www.domain.com/shop/instruments/  You could later add additional DySE™ merchant modules in the shop directory, such as using "shop/collectibles" for dir so that the products of the additional merchant show up at www.domain.com/shop/collectibles/ You can use any depth of sub-directories. You could even use "david/stuff/bargains/musical/instruments" for dir if you really wanted to. For example, use "shop/musical/instruments" for dir so that the products show up at www.domain.com/shop/musical/instruments/  In the future, if there were DySE™ merchant modules for CD's and sheet music, you could put those at "shop/musical/cds" and at "shop/musical/sheetmusic".

   
   

   Very Important:   Do not create the directory Do not create a directory on your website that has the same name as the one you have chosen otherwise the home page of your store may not work properly. For example, if you have chosen shop as the directory, then do not create a directory named shop on your website. DySE™ does not create .html files on your web server; DySE™ is dynamic and all output is virtual. If you are using a sub-directory inside a sub-directory, such as "shop/musical/instruments" for dir, it is acceptable if the leading directories exist as real directories on the hard drive, e.g: shop/musical. The last dierctory, e.g.: instruments, should not exist. In this example, it is assumed that you have created some sort of webpage at /shop/musical/index.html so that the user will see something if they try to access /shop/musical (similarly /shop/index.html).

   
   

   Important:   Use a descriptive directory name If you plan on adding additional DySE™ merchant modules to your website in the future, then use a descriptive directory name (e.g.: "instruments" for the DySE::InstrumentPro module) rather than a generic name (e.g.: "shop"). Thus, if you were to add calendar products using DySE::Calendars, you might use "calendars" as its directory name. Using a descriptvie directory name thus makes it easier to add additional merchant modules.

2. Add the following 5 lines to your .htaccess file located in the main directory of your website (i.e.: the directory used to show files for http://www.domain.com/). Either add these lines to the end of your existing .htaccess file, or create a new .htaccess file and put these lines into it.

   Options  +FollowSymLinks RewriteEngine  on RewriteBase  / RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(dir)(/.*)?$  cgi-bin/dyse/view.pl?merch=merchant&dir=$1&path=$2  [L]

   Novice: For an explanation of these 5 lines see: Brief Introduction to .htaccess File below.

   CRITICAL:   RewriteRule is one long line On your screen (or printout), the above RewriteRule might appear split onto two lines. The RewriteRule is one long line and ends at the [L]

   
   

   Very Important:   Substitutions In the above lines, you must do the following substitutions: Replace dir with the directory name where you want the products to show up at (e.g.: shop). Note: Do not include your domain name. Just use a directory name (e.g.: shop, instruments, calendars, store, etc.) Replace merchant with the name of the merchant module (e.g.: instrumentpro for the DySE::InstrumentPro merchant module; upper/lowercase does not matter for merchant). Replace cgi-bin with the name of your "cgi-bin" directory if different than "cgi-bin" (e.g.: "cgi-local" or "cgi"). Ask your hosting company if you are not sure what your "cgi-bin" directory is named. Note: The RewriteRule uses URL's. So if you need to change cgi-bin then change it to whatever directory name you would use in a URL to access your cgi-bin directory via a web browser. Use just the directory name (e.g.: cgi-bin, cgi, cgi-local, etc.). Do not include your domain name or any initial part of the directory path used internally by your server (e.g.: /public-html/).

   
   

   FAQ:   How do I install several DySE™ on one website ? See Multiple DySE™ Merchant Modules below.

   
   

   FAQ:   Why can't I see my .htaccess file ? See Why can't I see my .htaccess file with WS_FTP or CuteFTP?

   
   

   Tip:   Where in .htaccess file to add the lines Generally, you can put the lines anywhere in your .htaccess file. But since your server processes .htaccess in order starting at the first line, we recommend that you add the lines before other RewriteRule's. That's because if you happen to have a "match all" RewriteRule (e.g.: pattern ^.*$) then the server would stop there and never get to the DySE™ RewriteRule's.

   
   

   Tip:   Copy lines from file provided To prevent typographical errors, open the text file htaccess-directory.txt that came in dyse-view-yymmdd.zip (and dyse-view-yymmdd.tar.gz) and copy and paste the lines to your .htaccess file. WARNING: This sample .htaccess file is generic, and after you copy the 4 lines, you must still do the substitutions of MERCHANT with the actual name of the merchant module that you are installing. See the next warning box.

   For example, to have the DySE::InstrumentPro module show up at www.domain.com/shop/, you would use the following lines in .htaccess:

   Options  +FollowSymLinks RewriteEngine  on RewriteBase  / RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(shop)(/.*)?$  cgi-bin/dyse/view.pl?merch=instrumentpro&dir=$1&path=$2  [L]

   At this point, the DySE™ viewer is installed and mod_rewrite has been configured (via .htaccess) to run the DySE™ viewer whenever the dir directory (or any sub-directory of it) is accessed.

3. If you are using Microsoft FrontPage, then see the section FrontPage and .htaccess below then come back to this point in these instructions.

4. IMPORTANT: When you perform the next step, you should see the following DySE™ generated error message. This error is expected and indicates that mod_rewrite is working properly. It is ok to see any of the following errors. The errors are:

   DySE Error: no data directory: 'merchant'. Run make.pl DySE Error: no database file: 'merchant'. Run make.pl DySE Error: unknown merchant: 'merchant'

5. Run your web browser.
   Access the dir directory at your website:

   http://www.domain.com/dir/

   For example: http://www.mydomainname.com/shop/

   
   

   Important:   Substitutions In the web address http://www.domain.com/dir/ substitute in your own domain name and the directory name that you used for dir in your .htaccess file. For example, http://www.mydomainname.com/shop/

   
   

   Very Important:   Empty Directory shows up instead of error If you see an empty directory when you perform the next step, you most likely have created a real directory on your server named dir (e.g.: instruments, or calendars, or whatever you're using for dir). Delete that directory. You are not suppose to create that directory. It is a virtual (not real) directory that view.pl simulates. Index of /instruments Name Last modified Size Description Parent Directory 17-Nov-2005 03:23 -

   If you see an error other than indicated above, then see below: Web server generated errors with .htaccess

6. .htaccess is working properly.
   Continue to the section "Run DySE™ Merchant Module" below.

---

» Multiple DySE™ Merchant Modules

You can install several DySE™ Merchant Modules on the same server. Each module will appear in its own subdirectory, for example: /calendars/, /rockler/, /hono/.

Start with the htaccess-directory.txt sample .htaccess file supplied with one of the DySE™ merchant modules. For example, suppose you want to have DySE::Calendars as one of your multiple modules, so start with its htaccess-directory.txt file:

Options  +FollowSymLinks RewriteEngine  on RewriteBase  / RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(shop)(/.*)?$  cgi-bin/dyse/view.pl?merch=calendars&dir=$1&path=$2  [L]

shop specifies the name of the virtual directory (that will need to be changed since you can't have every DySE™ module using the same directory name!). calendars specifies which DySE™ module appears at the the specified virtual directory.

Now suppose that you want to add DySE::Rockler. Duplicate the RewriteCond and RewriteRule lines. Suppose you want to put calendars at the virtual directory /calendars/ and the Rockler.com products at the virtual directory /woodworking/ So you need to modify the two RewriteRule's as indicated in yellow:

Options  +FollowSymLinks # Following lines enable mod_rewrite RewriteEngine  on RewriteBase  / # Following lines for DySE::Calendars at /calendars/ RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(calendars)(/.*)?$  cgi-bin/dyse/view.pl?merch=calendars&dir=$1&path=$2  [L] # Following lines for DySE::Rockler at /woodworking/ RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(woodworking)(/.*)?$  cgi-bin/dyse/view.pl?merch=rockler&dir=$1&path=$2  [L]

Note: You can add comments to your .htaccess file to make it more understable. Comments start with the character # (you can indent comments with spaces and/or tabs). Any line starting with # is completely ignored by the server.

If you want to add more DySE™ merchant modules now or in the future, copy a pair of RewriteCond and RewriteRule lines and modify them as done above.

---

Module Already Installed at /

If you already have a DySE™ merchant module at your home directory (e.g.: calendars at www.domain.com/), you can still add other DySE™ merchant modules in virtual directories. In that case, you need to keep the RewriteCond and RewriteRule lines as the last two lines and add other RewriteCond and RewriteRule lines before them. For example, here's how to have Calendars.com at /, Rockler.com at /woodworking/, and KimmyShop.com at /kidstuff/

Options  +FollowSymLinks # Following lines enable mod_rewrite RewriteEngine  on RewriteBase  / # Following lines make real files and directories accessible. RewriteCond   %{REQUEST_FILENAME}    -d RewriteRule   ^.+$    -   [L] # Following lines for DySE::Rockler at /woodworking/ RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(woodworking)(/.*)?$  cgi-bin/dyse/view.pl?merch=rockler&dir=$1&path=$2  [L] # Following lines for DySE::KimmyShop at /kidstuff/ RewriteCond  %{REQUEST_FILENAME}  !-f RewriteRule  ^(kidstuff)(/.*)?$  cgi-bin/dyse/view.pl?merch=kimmyshop&dir=$1&path=$2  [L] # Following lines for DySE::Calendars at / (root). # These lines must be last since .* matches everything!!! # Add other DySE modules before this section. RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ cgi-bin/dyse/view.pl?merch=calendars&dir=&path=$1 [L]

Note: The RewriteCond and RewriteRule lines for DySE::Calendars must appear last since its RewriteRule line matches .* which matches everything.

Note: You can add comments to your .htaccess file to make it more understable. Comments start with the character # (you can indent comments with spaces and/or tabs). Any line starting with # is completely ignored by the server.

---

» FrontPage and .htaccess

If you are using Microsoft FrontPage with your website, you must also edit the following three files (this is in addition to the .htaccess changes that you did as instructed above) otherwise FrontPage will not work:

• _vti_bin/.htaccess
• _vti_bin/_vti_adm/.htaccess
• _vti_bin/_vti_aut/.htaccess

In each of those three files, you should see:

Options None

Change the word None to +FollowSymLinks (the character + is required). IMPORTANT NOTE: The word None may be followed or preceeded by other parameters. Leave those other parameters as is. Only change the word None. Example:

Options +FollowSymLinks

---

» Web server generated errors with .htaccess

Otherwise, you may see one of the following web server generated errors:

• no data directory: 'merchant'. Run make.pl:
  no database file: 'merchant'. Run make.pl:
  unknown merchant: merchant:

  • This error is expected and indicates that mod_rewrite is working properly. Continue to the section "Run DySE™ Merchant Module" below.

• 500 Internal Server Error:

  1. Verify that there are no typographical errors in .htaccess

  2. Reupload the .htaccess file using ASCII transfer mode of your FTP program.

  3. If you have access to your web server's error_log file, look at the last few lines to help isolate the problem.

• 404 File Not Found:

  1. Retype the web address and try again.

  2. Verify that the dir directory name in the web address is the same dir directory name in .htaccess

  3. Verify that the cgi-bin directory name in .htaccess is correct.

  4. Verify that there are no typographical errors in .htaccess

  5. Verify that you have the .htaccess file in the main directory of your website (i.e.: the directory used to show files for http://www.domain.com/). If when you login to FTP, you typically go into a "/public-html" or "/html" directory (or something similar), then that's where the .htaccess file is supposed to be.

  6. Verify that there are no .htaccess files in the following directories (ignore htaccess-directory.txt and htaccess-homepage.txt files): /cgi-bin, or /cgi-bin/dyse, or /cgi-bin/dyse/merchant. If there are .htaccess files in there then, determine why they are there; did you accidentally upload to the wrong directory? Either delete those extra .htaccess files, or to be safe, rename them to a different name so that the server does not use them, such as htaccess-old, thus you can restore them later if necessary.

• 403 Forbidden, You don't have permission to access {filename} on this server:

  • Make sure that the following line is in your .htaccess file:

    Options +FollowSymLinks

    If that does not work, then contact your hosting company and have them reconfigure your web server to have Options +FollowSymLinks in the web server's httpd configuration file.

• Username/Password box pops up:

  • You probably have a .htpasswd file in the same directory where .htaccess is located. Delete that .htpasswd file.

• Your home page appears:

  • You probably have a .htaccess file that causes redirection to your home page when a file is not found (e.g.: ErrorDocument 404 /). Therefore, handle this error as a "404 File Not Found" error as indicated above.

---

» Brief Introduction to .htaccess File

The following section is a brief explanation of the .htaccess file. It is optional reading. For the technical documentation, see: URL Rewriting Guide mod_rewrite reference documentation

• Options  +FollowSymLinks
  This statement tells your web server to enable the following of symbolic links (similar to Windows shortcuts). Symbolic links are used to implement the graphics used in the templates. The graphics are located in the /cgi-bin/dyse/merchant/templates/img directory and there is a symbolic link to it in the /dyse directory.

• RewriteEngine  on
  This statement enables the Rewrite Engine so that RewriteRule's are processed. If you set RewriteEngine off, then all RewriteRule's are ignored. This acts as a master on/off switch. Some servers are configured with the Rewrite Engine set to off by default, thus this statement ensures that it is on so that the RewriteRule's will be processed.

• RewriteBase  /
  This statement tells the Rewrite Engine that all URL's mention in subsequent RewriteRule's are relative to the / main directory.

• RewriteCond   %{REQUEST_FILENAME}   -d
  This statement is a conditional test (Cond means condition) that tests to see if the page requested in the URL is a directory that exists on the hard drive of the server (-d means "directory exists"). If the condition is met (i.e.: the requested page is a directory that exists), then the immediately following RewriteRule is processed. Otherwise, the immediately following RewriteRule is skipped and processing continues at the next RewriteCond or RewriteRule. This "existing directory" test is performed so that only requests for non-existent sub-directories are processed by the DySE™ view.pl script. Requests for existing sub-directories are not processed by DySE™ view.pl and are instead left for the server to process as usual.

• RewriteRule   ^.+$   -   [L]
  Use this RewriteRule when you have products showing up at the / main directory and want existing sub-directories to not be processed by DySE™ view.pl.

  The general format of a RewriteRule statement is:
  RewriteRule  SEARCH_PATTERN  REPLACEMENT_PATTERN  [OPTIONS]

  If the current URL does not match the SEARCH_PATTERN, this RewriteRule is skipped and processing continues at the next RewriteCond or RewriteRule.

  In the above RewriteRule:

  • SEARCH_PATTERN is: ^.+$
    This search pattern matches any URL's other than the home page (the ^ means "starts with"; the . matches any character; the + means one or more occurrences of what is before the +; the $ means up to the end of the URL).

  • REPLACEMENT_PATTERN is: -
    This replacement pattern is special; it means to leave the URL as is; no changes are done to the URL.

  • OPTIONS is: L
    This means that if this RewriteRule matches the current URL, then this is to be the last statement processed ("L" means last).

• RewriteCond   %{REQUEST_FILENAME}   !-f
  This statement is a conditional test (Cond means condition) that tests to see if the file requested in the URL does not exist (!-f means "not file exists"). If the condition is met (i.e.: the requested file does not exist), then the immediately following RewriteRule is processed. Otherwise, the immediately following RewriteRule is skipped and processing continues at the next RewriteCond or RewriteRule. This "files does not exist" test is performed so that only requests for non-existent files are processed by the DySE™ view.pl script. If you were to create a .html file at a URL that would normally be processed by the DySE™ view.pl script, the server will instead show that .html file rather than running DySE™ view.pl.

• RewriteRule   ^(shop)(/.*)?$   cgi-bin/dyse/view.pl?merch=instrumentpro&dir=$1&path=$2   [L]
  Use this RewriteRule when you want products to appear starting in a sub-directory (e.g.: /shop).

  The general format of a RewriteRule statement is:
  RewriteRule  SEARCH_PATTERN  REPLACEMENT_PATTERN  [OPTIONS]

  If the current URL does not match the SEARCH_PATTERN, this RewriteRule is skipped and processing continues at the next RewriteCond or RewriteRule.

  In the above RewriteRule:

  • SEARCH_PATTERN is: ^(shop)(/.*)?$
    This search pattern matches any URL's that start with "shop" (the ^ means "starts with") and is optionally followed by anything in that sub-directory (the . matches any character; the * means zero or more occurrences of what is before the *; the ? means the preceding character or group of parenthesized characters are optional; the $ means up to the end of the URL).

    Parenthesis are used so that those parts of the search pattern can be referenced in the REPLACEMENT_PATTERN. The first set of parenthesis is saved in $1, the second set in $2, and so on up to the ninth set in $9.

    The SEARCH_PATTERN matches partial URL's (i.e.: whatever appears in the web browser's URL after the domain name). Do not include your domain name in the SEARCH_PATTERN. Do not include FTP paths such as public_html in the SEARCH_PATTERN.

  • REPLACEMENT_PATTERN is: cgi-bin/dyse/view.pl?merch=instrumentpro&dir=$1&path=$2
    The URL is replaced with the REPLACEMENT_PATTERN with $1, $2, etc., substituted with the values set when matching the SEARCH_PATTERN. The URL in this particular REPLACEMENT_PATTERN causes cgi-bin/dyse/view.pl to be run with the specified parameters ?merch=instrumentpro&dir=$1&path=$2

  • OPTIONS is: L
    This means that if this RewriteRule matches the current URL, then this is to be the last statement processed ("L" means last).

• RewriteRule   ^(.*)$   cgi-bin/dyse/view.pl?merch=instrumentpro&dir=&path=$1   [L]
  Use this RewriteRule when you want products to appear starting at the home page (e.g.: /). rather than in a sub-directory (e.g.: /shop). This RewriteRule is similar to the above RewriteRule except that the SEARCH_PATTERN is ^(.*)$ and that matches all URL's. Note: Since this SEARCH_PATTERN matches everything, you should not put any other RewriteRule statements after this one since those statements will never be reached.

» 10. Run DySE™ Merchant Module

Each DySE™ merchant module comes with a make.pl script. When you run the make.pl script, the merchant's datafeed file is downloaded from the merchant to your web server and a database file of the merchant's products is created on your web server.

You can run make.pl via your web browser or via Telnet/SSH.

Novice User:   Telnet/SSH explained Telnet/SSH is a program that you run on your computer that allows you to login to your web server and type commands to your web server, such as to run the make.pl script. PuTTY (for Windows computers) is an excellent Telnet/SSH program and it is free (download puty.exe).

	via Web Browser	via Telnet/SSH
Advantages:	Suitable if merchant has a small number of products (e.g.: 10,000 or less). Simple to run make.pl via web browser. All you have to do is access a special web address in your web browser.	Suitable for any number of products. Can run make.pl in the "background" and immune to interruptions. You can disconnect from the internet and reconnect later and check on make.pl's progress. Disconnecting will not interrupt make.pl
Disadvantages:	Pressing the Esc (escape) key or disconnecting from the internet while make.pl is running may cause make.pl to stop running. In that case, the product's database file would be unusable and make.pl must be run again and allowed to finish uninterrupted. make.pl cannot be restarted where it left off. Not suitable if merchant has a large number of products (e.g.: 10,000 or more). Note that you can run make.pl via your web browser with a large number of products but any interruption may stop make.pl and thus require you to start make.pl all over again.	Requires knowledge of linux/unix commands (similar to using a Windows MS-DOS command window). Telnet/SSH access may not be available to you since some hosting companies disable Telnet/SSH for security. In that case, ask your hosting company for Telnet/SSH access or run make.pl via your web browser.

Note:   On Apache 1.3 web server, pressing Esc does not stop make.pl There is a bug in Apache 1.3 web server software that causes cgi-bin programs to keep running even after you press the Escape key or close the connection to the website. If you start any cgi-bin program and then press Escape, the program will keep running until it finishes. See: Apache bug report. It turns out that this bug is a benefit when you want to run a program such as make.pl that may take several minutes to finish. Because of this bug, you can start make.pl and then close your internet connection or web browser; make.pl will keep going. If you try to re-run make.pl while the first make.pl is still running, the second make.pl will merely display the current status of the first make.pl and then the second make.pl will immediately stop running.

Tip:   Automatically run make.pl on a scheduled basis Once you have confirmed that make.pl runs successfully, make.pl can be run automatically on a scheduled basis (e.g.: once a week, once a month, etc.) by setting up a cronjob. See: Automatic Updates using Cron Job. Novice User: Ask your hosting company to set up a cronjob to run make.pl. Refer them to this section of the DySE™ documentation and tell them where make.pl is located on your web server.

FAQ:   Can anyone maliciously run make.pl via the web and crash my server? Anyone can run make.pl via the web. If you want, you can use CHMOD to remove excute permissions between your runs. But you don't really have to remove permissions. When make.pl is run, it checks to see if a new datafeed is available at the merchant's site (it does that check/download at most once per day). And if the datafeed is unchanged, make.pl does not rebuild the database file. So if there's nothing to do, make.pl will typically end within 6 to 10 seconds. And only one make.pl will run at any one time (make.pl checks for running make.pl's). When a "nothing to do" make.pl is running, your store will be inaccessible for less than 1 second while make.pl has exclusive access to the configuration database.

Depending upon whether you want to run the make.pl script via your web browser or via Telnet/SSH, follow the instructions in one of the following sections:

• Run make.pl via Web Browser
• Run make.pl via Telnet/SSH

---

» Run make.pl via Web Browser

1. Install your DySE™ merchant key file.

   • If you have not requested your DySE™ merchant key file, click here to request key.

   • If you have received your DySE™ merchant key file merchant-key.txt, upload it to /cgi-bin/dyse/merchant/merchant-key.txt (e.g.: /cgi-bin/dyse/instrumentpro/instrumentpro-key.txt).

   • If you have not yet received the DySE™ merchant key file that you requested, then continue with the rest of the installation. When you receive your key file, come back to this step.

2. Run make.pl on your web server via your web browser by accessing the following URL:

   http://www.domain.com/cgi-bin/dyse/merchant/make.pl

   For example: http://www.mydomainname.com/cgi-bin/dyse/instrumentpro/make.pl

   
   

   Important:   Substitutions In the above web address, substitute in your own domain name and the merchant module name for merchant. For example: http://www.mydomainname.com/cgi-bin/dyse/instrumentpro/make.pl

3. If you see an error or a warning, see "Error/Warning while running make.pl" below.

4. As make.pl runs, it outputs status information.

   The status starts with a "start" section such as:

   #============================================================ # start: DySE::instrumentpro v5.01.23 (c)2005 Cusimano.Com Corporation, all rights reserved http://www.c3scripts.com/dyse/

5. » When make.pl finishes, the status concludes with a "finished" section, such as:

   #============================================================ # finished: Thank you for using DySE::instrumentpro v5.01.23

   
   

   Very Important:   No "finished" section. If make.pl starts to run and then stops abruptly, your web server may be configured to monitor memory and CPU usage. The web server thus stops any process that uses up too much memory or uses up too much processing power of the web server. Try running make.pl again to determine if the problem is repeatable (this is important). If it stops again, then ask your hosting company if your web server is monitoring memory/CPU and if those limits can be increased for your web site. Tell them the URL of your make.pl so that they can try it themselves and see why the web server is stopping the make.pl process. If the problem persists, move to a different web server that has higher usage limits or has more RAM memory, or move to a different hosting company. See also: Run make.pl on your Windows PC with ActivePerl below.

6. Continue to the section "View DySE™ Merchant Module" below.

---

» Run make.pl via Telnet/SSH

1. Install your DySE™ merchant key file.

   • If you have not requested your DySE™ merchant key file, click here to request key.

   • If you have received your DySE™ merchant key file merchant-key.txt, upload it to /cgi-bin/dyse/merchant/merchant-key.txt (e.g.: /cgi-bin/dyse/instrumentpro/instrumentpro-key.txt).

   • If you have not yet received the DySE™ merchant key file that you requested, then continue with the rest of the installation. When you receive your key file, come back to this step.

2. Login using Telnet/SSH and go into the cgi-bin/dyse/merchant directory (using the cd command).
   Then type the following command:

   perl  make.pl

   
   

   Tip:   Run make.pl in the background You can run make.pl in the background so you can do other work or so you can disconnect from the Internet before make.pl finishes without stopping make.pl. To run make.pl in the background and immune to disconnection, type the following command: nohup  perl  make.pl  &

3. If you see an error or a warning, see "Error/Warning while running make.pl" below.

4. As make.pl runs, it outputs status information.

   The status starts with a "start" section such as:

   #============================================================ # start: DySE::instrumentpro v5.01.23 (c)2005 Cusimano.Com Corporation, all rights reserved http://www.c3scripts.com/dyse/

5. When make.pl finishes, the status concludes with a "finished" section, such as:

   #============================================================ # finished: Thank you for using DySE::instrumentpro v5.01.23

   
   

   Very Important:   No "finished" section. If make.pl stops abruptly, your web server may be configured to monitor memory and CPU usage. The web server thus stops any process that uses up too much memory or uses up too much processing power of the web server. Try running make.pl again to determine if the problem is repeatable (this is important). If it stops again, then ask your hosting company if your web server is monitoring memory/CPU and if those limits can be increased for your web site. Tell them the URL of your make.pl so that they can try it themselves and see why the web server is stopping the make.pl process. See also: Run make.pl on your Windows PC with ActivePerl below.

6. Continue to the section "View DySE™ Merchant Module" below.

---

» Run make.pl on your Windows PC with ActivePerl

First, try to run make.pl via your web browser or via telnet/SSH. Only run make.pl on your Windows PC if you are finding that make.pl abruptly stops when you try to run it via the web browser or via telnet/SSH.

Also, try running make.pl via a local cron job on your web server that directly runs make.pl. See: "Cron Job on your Server > Run make.pl directly".

If make.pl abruptly stops then your server probably has limits on how much time a perl program can run or on how much RAM memory it can use. Contact your hosting company and ask them if they can increase or remove the execution limits for perl programs on your server. Or perhaps they could move your website to a different server that has no limits or has less websites on it.

Note: The following assumes that you have already installed make.pl and its associated files on your web server.

1. Install ActivePerl on your Windows PC. You will then be able to run make.pl locally on your Windows PC. See tutorial: How to install ActivePerl.

2. Download and unpack the DySE::MERCHANT .zip file onto the hard drive of your Windows PC.

3. Install your DySE™ merchant key file.

   • If you have not requested your DySE™ merchant key file, click here to request key.

   • If you have received your DySE™ merchant key file merchant-key.txt, put it in the same directory on your Windows PC where the make.pl file is located.

   • If you have not yet received the DySE™ merchant key file that you requested, then continue with the rest of the installation. When you receive your key file, come back to this step.

4. Run make.pl on your Windows PC. You can do that by simply double-clicking on the make.pl file. Or you can run make.pl by opening an MS-DOS window, cd to the directory where make.pl is located, then run make.pl by typing the command: perl make.pl    See tutorial: How to use an MS-DOS window.

5. After make.pl has finished, you can double-click the MERCHANT-log.txt file (located in the same directory where make.pl is located) to see a log of what make.pl did.

6. After make.pl has finished, upload the created data/*.db files to your web server (e.g.: /cgi-bin/dyse/MERCHANT/data/*.db). Note: The *.db files are BINARY files so select BINARY mode in your FTP program.

Note: You do not need to run make.pl on your server. If you installed make.pl on your server, it is a good idea to remove the make.pl file from your server, or at least use CHMOD 644, so that you do not accidentally run it and end up with an unfinished database file.

Very Important:   Compress::Zlib not installed on server Running make.pl on your Windows PC and then uploading the created *.db files will cause and error if your server does not have the Compress::Zlib compression library installed. Since ActivePerl on your Windows PC does have it installed, the created *.db files will contain compressed data. If your server does not have Compress::Zlib installed, then view.pl will issue an error when you try to view any DySE™ generated webpages: Error: FILE.db: contains compressed data but Compress::Zlib not installed To fix this error, do one of the following actions: Create a configuration file and set the data.compress configuration variable to no to tell make.pl to not use compression. Then re-run make.pl and reupload the *.db files. Or, ask your hosting company to install Compress::Zlib. See Compress::Zlib at cpan.org for installation instructions.

---

» Error/Warning while running make.pl

You may see one of the following web server generated errors:

• 500 Internal Server Error:

  1. Run your FTP program and verify that all of the file execute permissions of the file /cgi-bin/dyse/merchant/make.pl are set (CHMOD 755). And verify the permissions of the directory /cgi-bin/dyse/merchant are set properly (CHMOD 755).

     

  2. Reupload the make.pl file using ASCII transfer mode of your FTP program.
     And set the execute permissions of make.pl (CHMOD 755).

     

  3. It is assumed that your perl path is /usr/local/bin/perl   If it is different on your web server, then edit make.pl and change the first line to the correct path (you can use the Edit make.pl shortcut found in the .zip file to edit the make.pl file using the Windows Notepad editor). Then reupload the make.pl file and set the execute permissions of make.pl (CHMOD 755).

     Novice User:   Perl path If you're not sure what your perl path is, then ask your hosting company (tip: check your hosting company's online help/FAQ section). On some servers, the perl path is /usr/bin/perl

  4. Some web servers are configured such that cgi-bin script files must have a filename that ends with .cgi rather than the standard .pl ending. If your server requires the .cgi ending then rename make.pl to make.cgi   If you are not sure if your server requires the .cgi ending or the standard .pl ending, ask your hosting company or just go ahead and try renaming make.pl to make.cgi (if still does not work, just rename it back to make.pl).

  5. If you have access to your web server's error_log file, look at the last few lines to help isolate the problem.

  6. In rare cases: If your server uses Ensim and make.pl was working but has now stopped (and all other .pl files on our server have also stopped), check that the linux system file /var/log/httpd/suexec_log has not exceeded 2GB in size (2GB is the maximum file size that linux allows for any one file). If so, have your system administrator delete the /var/log/httpd/suexec_log file. Note: This file is in the "real" filesystem, it is not in your website's virtual filesystem; therefore, only the system administrator has permission to delete it.

• 404 File Not Found:

  1. Retype the web address and try again.

  2. Verify that the merchant directory name in the web address is correct. Note: merchant is the name of the merchant module, it is not the dir; for example, use instrumentpro rather than shop.

  3. Verify that the cgi-bin directory name in the web address is correct.

  4. Run your FTP program and verify that make.pl is in the /cgi-bin/dyse/merchant directory. If not, re-install the merchant module into the correct directory. See: Install DySE™ Merchant Module.

• Your home page appears:

  • You probably have a .htaccess file that causes redirection to your home page when a file is not found (e.g.: ErrorDocument 404 /). Therefore, handle this error as a "404 File Not Found" error as indicated above.

  • It is also possible that a 500 Internal Server Error has occurred and that your hosting company has configured your server to redirect to the home page when such server errors occur. See 500 Internal Server Error above and try those solutions too.

---

You may see one of the following DySE™ generated errors/warnings:

• Data > data.db file is already up-to-date with datafeed; leaving data.db as is

  The existing database file is already up-to-date with the merchant's datafeed file. Thus the existing database file does not need to be recreated. If you want to recreate the database file, then delete the database file /cgi-bin/dyse/merchant/data/data.db. If you also want to auto-download the merchant's latest datafeed file then also delete the datafeed file /cgi-bin/dyse/merchant/data/datafeed.txt. Then re-run make.pl.

• data/cfg.db: couldn't open database file: Permission denied
  data/data.db: couldn't open database file: Permission denied

  Delete the /cgi-bin/dyse/merchant/data/cfg.db file and delete the /cgi-bin/dyse/merchant/data/data.db file and then re-run make.pl.

• data/datafeed.txt: couldn't open data file for reading: No such file or directory

  The merchant's datafeed file could not be found. See: Manual Download of Merchant's Datafeed.

• Data > only number items will be processed

  If the test configuration variable is set to a non-zero number (e.g.: 1000), then only the specified number of items are read from the datafeed file. To process all items, set the test configuration variable to 0 (zero) which is the default.

• DBI Perl module is not installed. It is required.

  • Running make.pl on your server:
    Contact your hosting company and ask them to install the DBI Perl module (type: perl -MCPAN -e shell then insall DBI).

  • Running make.pl on your Windows PC:
    See: Install DBI Perl Module on Windows PC.

• /dyse: couldn't create directory: Permission denied

  make.pl could not create the directory /dyse (located in the root directory where your home page file would be located). DySE™ makes template graphics appear online at www.domain.com/dyse/merchant/img/*.gif. Run your FTP program (or use SSH) and manually create a dyse directory in the root directory.

• DySE Error: no data directory: 'merchant'. Run make.pl
  DySE Error: no database file: 'merchant'. Run make.pl

  The database directory or database file have not been created by make.pl. Run make.pl. See above: Run DySE™ Merchant Module.

• DySE > DySE::merchant v#.##.## is available; running v#.##.##

  A newer version of this DySE™ Merchant Module is available. Download and install the latest version of this DySE™ Merchant Module.

• DySE > make.pl is already running. Click here to view log file

  You tried to run make.pl again and the first make.pl is still running. Click the "Click here to view log file" link to see the current contents of the log file. Scroll down or press the "end" key on your keyboard to jump to the bottom. Press refresh in your web browser to refresh the screen.

• DySE > DySE::view v#.##.## (or higher) is required; using view.pl v#.##.##

  A newer version of DySE™ view.pl is required. Download and install the latest version of view.pl

• Data > data.db file is invalid; deleting data.db

  The data.db file is invalid and is being deleted so a valid new file can be created.

• Internet > 404 Not Found

  make.pl could not find the datafeed file on the merchant's website. If you are not using the latest version of this DySE™ Merchant Module, then download and install the latest version of this DySE™ Merchant Module. Otherwise, see: Manual Download of Merchant's Datafeed.

• Internet > 500 Can't connect to MerchantDomain:80 (Bad hostname 'MerchantDomain')

  Your web server probably has a firewall that is blocking internet access. If your web server has a firewall, then outbound access to port 80 (http:// protocol) must not be blocked by your web server's firewall. If blocked, DySE™ will still work but auto-downloading of the merchant's datafeed file will not be possible and you must manually download the merchant's datafeed file then upload it to your web server. See: Manual Download of Merchant's Datafeed. Ask your website hosting company to reconfigure the firewall to allow outbound access to port 80 of the merchant's domain (the domain appears in the warning).

• Internet > filename: couldn't download datafeed file

  The merchant's datafeed file could not be downloaded from the merchant's website. See: Manual Download of Merchant's Datafeed.

• Internet > filename: couldn't download latest datafeed file; using current file instead

  The latest datafeed could not be downloaded from the merchant's website. The datafeed file that is already on your web server (because it was auot-downloaded previously or you manually downloaded it) will be used instead.

• Internet > LWP module is not available. Datafeed will not be downloaded.

  For auto-downloading of the merchant's datafeed file to be possible, the Perl module LWP::Simple must be installed on your web server (this Perl module is used for internet access). If not installed, DySE™ will still work but auto-downloading of the merchant's datafeed file will not be possible and you must manually download the merchant's datafeed file then upload it to your web server. Your hosting company can install LWP::Simple by logging in as superuser then typing the following command (the apostrophes are required):

  perl -MCPAN -e 'install Bundle::LWP'

• Key > merchant-key.txt: key not found
  Key > key not found; running in demo mode
  Key > affiliate ID will not be included in links
  

  Key file merchant-key.txt (e.g.: instrumentpro-key.txt) not found. If you have not already requested a DySE™ key file for this merchant module from us, request a DySE™ key file. If you received a DySE™ key file for this merchant module from us, then upload it to the same directory where make.pl is located then re-run make.pl.

• Make > make2.pl sub-program is missing
  Make > couldn't locate perl interpreter
  Make > couldn't start make2.pl sub-program: reason
  Make > make2.pl sub-program returned unknown result: reason
  Make > make2.pl sub-program must be MinimumVersion (or higher)

  The make.pl program can run without the make2.pl program; that's why this message appers as a warning instead of a fatal error. If make2.pl is missing or cannot run, then make.pl itself takes over the functionality provided by make2.pl. The make process continues on without make2.pl.

  The make.pl program optionally runs the make2.pl program during the "process category items" section of the make process. It does this to prevent the web server's RAM memory usage from peaking and remaining high (which can happen if a category has a very large number of products). If make2.pl cannot run or is missing, then make.pl internally does the equivalent of what make2.pl would do.

• make.lck: couldn't open for writing: Permission denied:

  • Your web server probably runs under a user account other than your own account, such as user account "nobody" or user account "www". This error can usually be fixed by enabling all write permissions of the /cgi-bin/dyse/merchant directory (you can change the permissions of a directory just like you can change the permissions of a file; select the directory as you would select a file, but do not open the directory). Try chmod 775 and, if that does not work, then try chmod 777

---

» Install DBI Perl Module on Windows PC

Some merchant modules, such as DySE::NS (NetShops.com), require support for MySQL remote database access via the DBI Perl Module.

Assuming that you have already installed ActivePerl on your Windows PC, follow these steps: (Note: observe the capitlization of some words in these steps; that capitalization is critical and required!)

1. Open an MS-DOS command line window. Start > Run... > cmd

2. Type: ppm
   You should see something like: PPM interactive shell and the PPM> prompt.

3. Type: install DBI
   (Note: You must type DBI in all capitals).

4. Type: install DBD-mysql
   (Note: Unlike the previous command, this one is DBD (not DBI); and DBD must be typed in all capitals).

5. Type: exit
   You should be back at the MS-DOS command prompt. To close it, type: exit

» 11. Manual Download of Merchant's Datafeed

Read this section only if make.pl could not auto-download the merchant's datafeed file.

Your web server probably has a firewall that is blocking internet access. If your web server has a firewall, then outbound access to port 80 (http:// protocol) must not be blocked by your web server's firewall. If blocked, DySE™ will still work but auto-downloading of the merchant's datafeed file will not be possible and you must manually download the merchant's datafeed file then upload it to your web server. Ask your website hosting company to reconfigure the firewall to allow outbound access to port 80 of the merchant's domain (the domain appears in the warning).

Otherwise, continue with these steps:

1. Download the merchant's datafeed file from the merchant's website. Right-click on the appropriate datafeed link and select "Save Target As..." and save the file to your computer.

   Merchant	Datafeed
   AquinasAndMore.com	Datafeed
   Audible.com	Contact the Audible.com affiliate manager
   BettyMills.com	Datafeed
   Calendars.com	See documentation
   CrazyforBargains.com	Datafeed
   HouseOfNutrition.com	Datafeed
   InstrumentPro.com	Datafeed
   KimmyShop.com	Datafeed
   Rockler.com	Datafeed
   StubHub.com	Two files must be downloaded. File 1: Save as datafeed.txt File 2: Save as prices.txt

   
   

   Note:   Do not edit the datafeed file There is no need to do a "search & replace" of the ID in the datafeed file using a separate program such as Microsoft Excel or a search & replace utility. The make.pl script automatically does a search & replace using the ID found in your key file. Leave the datafeed file as is. The make.pl script does this automatic substitution for you so that you can have multiple websites, each with a different ID and a key file for each ID, and you would only need one datafeed file and each make.pl script substitutes in the ID from that website's key file.

2. Rename the datafeed file to datafeed.txt since this is the name that make.pl looks for.

3. Upload the datafeed.txt datafeed file to your website and put it in the /cgi-bin/dyse/merchant/data/ directory.

   If the data directory does not exist, create it inside the /cgi-bin/dyse/merchant/ directory.

4. Run make.pl and it should now see the datafeed.txt datafeed file. See the "Run DySE™ Merchant Module" section above.

» 12. View DySE™ Merchant Module

After make.pl has run successfully, you can view the products.

1. Run your web browser.

2. Access view.pl on your web server using one of the following URL's depending upon whether you configured the .htaccess file to show products at the main directory (/) or in a sub-directory (/dir).

   • Products at Main Directory:

     http://www.domain.com/

     For example: http://www.mydomainname.com/

   • Products in Sub-Directory:

     http://www.domain.com/dir/

     For example: http://www.mydomainname.com/shop/

3. If there are DySE™ errors, see " Error while viewing DySE™ Merchant Module" below.

4. If you see broken graphics, such as for the merchant's logo or for the "Buy" graphic, see " broken graphics" below.

   If the graphics (such as the merchant's logo) show up but appear damaged, the .gif graphic files were probably uploaded using ASCII transfer mode. Reupload them using binary transfer mode. From the .zip (or .exe or .tar.gz file), reupload the .gif files from the templates/img directory to the /cgi-bin/dyse/merchant/img directory.

   Valid graphic

   Damaged graphic

   
   

5. If you have not yet requested a key, you should do so now. Click here to request a key file.

   CRITICAL:   Demo mode In demo mode, all product links go to the merchant's home page and have no affiliate ID. After you install your DySE™ Merchant Key file, your affiliate ID will be included in your links.

6. If you have received your key, install it by uploading it (in ASCII mode) to the same directory where the make.pl file is located (e.g.: /cgi-bin/dyse/merchant).

   Then run make.pl so that your key is applied (see: Run DySE™ Merchant Module above). When you run make.pl, make.pl wil indicate whether your key is read or not.

   Then view any product's page at your website (press Refresh to make sure you're looking at the current version of that page). Verify that your affiliate ID shows up in the links.

   Novice User:   Verify your affiliate ID in links Move your mouse over any product's "Buy" button or over the merchant's logo. Right-click on the button/logo and select "Copy Shortcut" to copy the link's URL. Click in the Address bar of your web browser then paste in the URL (i.e.: press Ctrl-V, or select Edit > Paste, or right-click and select Paste). You should see your ID somewhere in the link (the format and position of the ID in the URL varies depending upon the merchant).

   
   

   Important:   No affiliate ID after clicking "Buy" button If you click a product's "Buy" button or click on the merchant's logo, your affiliate ID may not show up in the Address bar of your web browser. That is ok.. Some merchants do a redirection at their website and the final URL that the user lands at may not show your ID. Go back to your website and look at the URL of the "Buy" button and you should see your affiliate ID in that URL (see Novice User box immediate above).

7. If you want to customize the format of the web pages, such as adding a custom header/footer or your logo to every page, continue to the "Customization" section below.

8. If you want to install other DySE™ Merchant Modules (either now or in the future), repeat the same installation steps that you just did to install the current DySE™ Merchant Modules; note that you do not have to install the view.pl viewer script more than once on the same server. See: Download DySE™ Merchant Module.

9. Congratulations. The installation is done.

   Tip:   How to prevent your commission from being stolen A lot of computers are infected with parasite/scumware and that can cause your affiliate ID to be overwritten, thus causing the commission to go to the parasite/scumware author and not you. To help fight parasite/scumware, you can install a parasite/scumware detector on all your DySE™-generated webpages. It is extremely easy to install the detector and it is free. See: DoxDesk Parasite/Scumware Detector.

   
   

---

» Error while viewing DySE™ Merchant Module

You may see one of the following DySE™ generated errors:

• DySE error: unknown merchant: 'MerchantName'

  1. View your .htaccess file and verify that the merch=merchant parameter has the correct value. It should be set to the name of the merchant module, e.g.: instrumentpro (not shop). See: Configure .htaccess File.

  2. Run your FTP program and verify that /cgi-bin/dyse/merchant/data/data.db exists. The error indicates that view.pl could not find this file. This file is the database file and was created when you ran make.pl. If the data.db file does not exist, then run make.pl again (see: Run DySE™ Merchant Module above).

• DySE error: dir/data/data.db: database is currently locked
  DySE error: dir/data/cfg.db: database is currently locked

  While make.pl is running and building the merchant database file, the merchant database file is locked and is not accessible by the DySE™ view.pl script. Wait until make.pl has finished successfully, then refresh your web browser.

• DySE error: Server is too busy (number > 30)

  If the current server load (a measure of how busy the server is) goes above a preset limit (default 30), view.pl reports an error and immediately exits. The server load includes everything running on the server (includes all processes and all websites on the server). If you're on a shared server, move to a less busy shared server or to a dedicated server. Or to increase the limit (default 30) to a higher number such as 50, create a make-ini.txt configuration file that contains maxload 50 Alternatively, to make view.pl skip the HTML pack function (it removes extraneous spaces, carriage returns, and other characters), create a make-ini.txt file that contains write.html.pack no or add the HTML comment <!--nopack--> to your HTML/include files.

You may see one of the following server generated errors:

• » broken graphics

  If you see broken graphics, such as for the merchant's logo or for the "Buy" graphic, follow these steps and stop when the graphics are fixed.

  1. Check the directory /cgi-bin/dyse/merchant/templates/img and verify you have uploaded all the images that were in the .zip (or .tar.gz) file. If a file is missing or is zero length, then reupload it --- or just reupload the entire img directory to be sure everything is uploaded properly.

     View any webpage in your store. Press Refresh.
     If the graphics are now ok, stop here. Otherwise, continue to the next step ...

  2. Open your .htaccess file. Add the following line anywhere in the file (if the line is already present, then continue to the next step):

     Options +FollowSymLinks

     View any webpage in your store. Press Refresh.
     If the graphics are now ok, stop here. Otherwise, continue to the next step ...

  3. Create a directory named dyse in the root directory of your website (if it already exists, then that's fine). Now run /cgi-bin/dyse/merchant/make.pl -- The make.pl program will attempt to create the symbolic link (the unix equivalent of a Windows shortcut) from /dyse/merchant/img to the /cgi-bin/dyse/merchant/templates/img directory.

     View any webpage in your store. Press Refresh.
     If the graphics are now ok, stop here. Otherwise, continue to the next step ...

  4. If you have not already done so (as indicated in the previous step), create a directory named dyse in the root directory of your website. In that dyse directory, create a directory named merchant (for example, for DySE::InstrumentPro, name the directory instrumentpro). Go into that directory (e.g.: go into dyse/instrumentpro). Then upload the img directory (using BINARY transfer mode). You should end up with an img directory inside the /dyse/merchant directory. So, you should now be able to view www.domain.com/dyse/merchant/img/logo.gif

     View any webpage in your store. Press Refresh.

  The graphics should now appear.

• Username/Password box pops up:

  • You probably have a .htpasswd file in the same directory where .htaccess is located. Delete that .htpasswd file.

» 13. Automatic Updates using Cron Job

DySE™ merchant modules can be run automatically on a periodic scheduled basis to keep your store up-to-date with the latest datafeed from the merchant. This is done using what is known as a "cron job" (cron comes from the word chronos, the Greek word for time).

You can either setup the cron job locally on your own server, or you can signup for our free DySE™ Remote Cron Job Service. With the remote cron job service, you do not have to do anything to the setup on your server; we setup a cron job on our server that calls make.pl via http (just like when you access make.pl on your server via a web browser).

Select the type of cron job you want to use:

• Cron Job on your Server
• DySE™ Remote Cron Job Service

---

» Cron Job on your Server

DySE™ merchant modules can be run automatically on a periodic scheduled basis. This is done by you or your hosting company setting up a cron job on your web server.

Each cron job has two properties:

1. What command to run, and
2. What day/time to run the command.

For example, you could set up a cron job that makes your web server run the DySE™ make.pl script every Thursday at 4:00 a.m. Or you might configure the cron job to run on the first day of each month, or perhaps every day.

Novice User:   Cron Job explained See: Cron Help Guide

Important:   Cron Job is an Advanced Topic Cron Job is an advanced topic. You may need to contact your hosting company for assistance on setting up a cron job on your web server. We cannot help you with this task; if necessary, contact your hosting company for assistance and tell them that you want a cron job to periodically run cgi-bin/dyse/merchant/make.pl and that the script may require a cd to its directory.

There are four different ways to run the DySE™ make.pl script as a cron job. Use one of the following methods depending upon your server's configuration. The methods are shown in order of preferences, so we recommend using the lynx command if your server has it installed.

• lynx command
• GET command
• Run make.pl directly
• Run make.pl via batch file

---

lynx command

If your web server has the linux text-based web browser lynx installed, then the command in the cron job would be: (this command is one long line; it may appear on your screen wrapped as two lines; type it as one long line)

lynx  -dump  "http://www.domain.com/cgi-bin/dyse/merchant/make.pl"  >  /dev/null

The lynx is the program to run (the linux/unix text-based web browser); the -dump option tells lynx to output the web page being accessed rather than waiting for you interactively navigate the web page by using keyboard commands; the http://... is the full web address of make.pl; and the "> /dev/null" causes any status information from make.pl to be discarded.

The "> /dev/null" part is optional and if you leave it out, the output from make.pl will be included in the email that the cron job sends to you when a cron job is run by the server. (Note: Whether or not your server sends an email to you upon completion of the cron job depends upon the configuration of your server; that's not part of DySE™).

Note: Depending upon your server's configuration, you may need to replace lynx with the full path to lynx which is typically: /usr/bin/lynx

---

GET command (part of LWP::Simple bundle)

Otherwise, if your web server has the GET command installed (note: the command is "GET" -- all uppercase; it is not "get" -- all lowercae), then the command in the cron job would be: (this command is one long line; it may appear on your screen wrapped as two lines; type it as one long line)

GET  -d  "http://www.domain.com/cgi-bin/dyse/merchant/make.pl"

The GET is the program to run; the http://... is the full web address of make.pl; and the -d causes any status information from make.pl to be discarded.

The -d part is optional and if you leave it out, the output from make.pl will be included in the email that the cron job sends to you when a cron job is run by the server. (Note: Whether or not your server sends an email to you upon completion of the cron job depends upon the configuration of your server; that's not part of DySE™).

If you use -ds instead of -d then a one-line result code is output, such as "200 OK" to indicate whether the GET succeeded or not.

Note: Some servers may report an error if GET outputs anything; in that case, use -d so that GET runs silently.

Note: Depending upon your server's configuration, you may need to replace GET with the full path to GET which is typically: /usr/bin/GET

---

» Run make.pl directly

Otherwise, if the version of your make.pl is v6.04.08 or greater, then the command in the cron job would be: (this command is one long line; it may appear on your screen wrapped as two lines; type it as one long line)

/path_to_your_website/cgi-bin/dyse/merchant/make.pl  >  /dev/null

If you are not sure what the path to make.pl is on your website, run make.pl in your web browser and see what the value is after "dir:" and use that value.

The "> /dev/null" part is optional and if you leave it out, the output from make.pl will be included in the email that the cron job sends to you when a cron job is run by the server. (Note: Whether or not your server sends an email to you upon completion of the cron job depends upon the configuration of your server; that's not part of DySE™).

---

Run make.pl via batch file

Important:   Upgrade to make.pl v6.04.08 (or higher) We strongly recommend that you upgrade to make.pl v6.04.08 (or higher), and use the above solution which is simpler.

Otherwise, create a shell batch text file that contains the following 3 lines:

#!/bin/sh cd  /path_to_your_website/cgi-bin/dyse/merchant/ make.pl  >  /dev/null

The #!/bin/sh tells the server that this file is a shell batch file (your server might instead need #!/bin/csh or #!/bin/bash); the cd command says what directory to go into, use the full path to the directory that contains make.pl; and the make.pl command says to run the make.pl command, and the "> /dev/null" says to discard any status information output from make.pl.

Note: The cd command is required because make.pl (less than v5.05.05) only checks the current directory for the key file and the cd command ensures that the server is running make.pl from the correct directory.

If you are not sure what the path to make.pl is on your website, run make.pl in your web browser and see what the value is after "dir:" and use that value.

You can save this shell batch file in any directory of your web site and name it whatever you want. For example, you could name it update and save it in the cgi-bin/dyse/merchant directory.

For example, on our example website great-calendars.com, the file /home/virtual/great-calendars.com/var/www/cgi-bin/dyse/calendars/update contains:

#!/bin/sh cd  /home/virtual/great-calendars.com/var/www/cgi-bin/dyse/calendars/ make.pl  >  /dev/null

And our cron job is configured to periodically run the command /home/virtual/great-calendars.com/var/www/cgi-bin/dyse/calendars/update

The remainder of this documentation is optional reading. You only need to read the following documentation if you want to customize the appearance of the Merchant Module such as adding your own logo/header to each page.

» 14. Customization

Now that you have DySE™ installed, you might want to customize the appearance of the webpages.

• Add logo / header / footer on all pages
• Change the design to match your website
• Use one of the other template sets provided
• Relabel "Home" in the navigation bar
• Add "Home" link to start of navigation bar
• Add Google AdSense
• Root Category Selection -- Niche Store with Subset of Products
• See also: Template Files below.

---

» Add logo / header / footer on all pages

To put a common header/footer on all pages, you can do either of the following:

• Type the HTML of your header/footer directly into each of the template files /cgi-bin/dyse/merchant/templates/*.html

• Or, type the HTML of your header/footer into an include file (e.g.: /cgi-bin/dyse/merchant/include/hdr.html) and then type an include directive into each of the template files. For example, add {include hdr} or <!--include hdr--> in each of the template files /cgi-bin/dyse/merchant/templates/*.html

See also: <!--include--> directive.

---

» Change the design to match your website

Edit the template files /cgi-bin/dyse/merchant/templates/*.html

Important:   <IMG> and <SCRIPT> SRC must start with a / If you have <IMG> or <SCRIPT> tags in your templates, the SRC value must start with a / character otherwise the <IMG> and <SCRIPT> tags will not work since they will access the wrong directory. See below: <IMG> and <SCRIPT> in Templates -- Leading / in SRC URL's.

For a complete explanation of templates files, see the "Template Files" section below.

---

» Use one of the other template sets provided

Each DySE™ Merchant Module comes with several sample sets of templates. Each one presents a different website design. See "Sample Template Sets" below.

---

» Relabel "Home" in the navigation bar

If you have products showing up in a directory, such as /calendars, then you might want to rename the "Home" link in the navigation bar to something else, such as "Calendars".

Use a plain text editor (such as Windows Notepad) and create a plain text file and save it as /cgi-bin/dyse/merchant/make-ini.txt (this is in the same directory where make.pl is located).

In make-ini.txt, type the following one line:

navbar.home "TEXT"

Replace TEXT with the text that you want to show up in place of "Home", such as "Calendars".

For make-ini.txt to take effect, you must run make.pl again. See above: Run DySE™ Merchant Module.

---

» Add "Home" link to start of navigation bar

If you also want a "Home" link that goes to your website's real home page (i.e.: http://www.domain.com/), then do one of the following:

• In make-ini.txt, type the following one line:

  navbar.prefix [<A HREF="/">Home</A>]

  
  

  For make-ini.txt to take effect, you must run make.pl again. See above: Run DySE™ Merchant Module.

• Or, edit the template files /cgi-bin/dyse/merchant/templates/*.html and add the following HTML just before the navigation bar {page.navbar} code:

  <A HREF="/">Home</A> {navbar.separator}

  Note: Those are curly braces { and } around navbar.separator. They are not round parentheses ( and ).

---

» Add Google AdSense

To add Google AdSense ads to DySE™ generated webpages, follow these steps:

1. Login to Google Adsense, select the ad settings, and copy your AdSense code.

2. Edit your items.html product details template. If you don't have a local copy of that file, FTP download it from /cgi-bin/dyse/merchant/templates/items.html

3. Paste your AdSense code into the items.html template file where you want the ads to be placed.

4. Upload your revised items.html template file to your web server. Note: You do not have to run make.pl again. Template changes will appear immediately online.

5. View any of your product details pages to confirm the placement of the ads. You may need to press Refresh in your web browser to refresh the page.

---

» Root Category Selection -- Niche Store with Subset of Products

Use Root Category Selection to create niche stores. By default, make.pl uses all the products in the merchant's datafeed. Root Category Selection lets you specify a part of the merchant's datafeed to use for your niche store. For example, with DySE::InstrumentPro (musical instruments), you could create a guitars store by selecting "Guitars" as the Root Category; only the "Guitars" category (and its sub-categories, if any) would appear in your store.

Example store with default root (entire datafeed):
		EverythingInstruments.com
Example niche store with "Guitars" selected as the Root Category:
		www.bime.com/guitars/

To select a root category:

1. Determine the category that you want to use as the root category. Do that by visiting your store website (or one of the sample websites) and navigate to the category you want to use. For example, "Home > Guitars" at http://www.everythinginstruments.com/guitars/. Look at the navigation bar and copy everything after the "Home >" such as "Guitars".

2. Then create a make-ini.txt configuration file (in the same directory where make.pl is located) and set the category.root configuration variable to that category. For example, the following setting would cause the "Guitars" category to be used as the root category:

   category.root "Guitars"

3. Run make.pl. The selected sub-category becomes the root category to be shown on the home page of your store.

Category that only has products and no sub-categories:

Note that DySE™ does not support having products on your home page; only sub-categories can appear on the home page. For example, "Guitars > Acoustic Guitars" consists only of products and has no sub-categories. The solution is to create a pseudo category by setting the category.root.new configuration variable to the pseudo category name. For example, the following settings in make-ini.txt cause "Guitars > Acoustic Guitars" to appear on the home page as a category called "Store":

category.root "Guitars > Acoustic Guitars" category.root.new "Store"

If www.domain.com/ is the home page, then www.domain.com/store/ would show the acoustic guitars products index. On the home page, the "Main Categories" index would list the one category "Store". In this case, you might want to edit the home.html template file and remove the category index and replace it with text such as "Click here to enter store" and link it to /store/. You can use any text for the category.root.new setting. In the above example, you could have used category.root.new "Acoustic Guitars" and the products would have shown up at www.domain.com/acoustic-guitars/

Alternatively, you can make the category appear on the home page by adjusting .htaccess so that DySE™ thinks the user is accessing the category sub-directory. For example, with the above settings of category.root and category.root.new, use the following .htaccess file with an adjusted value for the path parameter:

Options  +FollowSymLinks RewriteEngine  on RewriteBase   / RewriteCond   %{REQUEST_FILENAME}   -d RewriteRule   ^.+$   -   [L] RewriteCond   %{REQUEST_FILENAME}   !-f RewriteRule   ^(.*)$   cgi-bin/dyse/view.pl?merch=merchant&dir=&path=store/$1  [L]

With the above .htaccess and make-ini.txt files, accesses to www.domain.com/FILENAME.html make DySE™ think the user is accessing www.domain.com/store/FILENAME.html (the "true" URL). Note: You will need to edit the templates and remove the navigation bar ({page.navbar}) and the categories sidebar (cat.main.text) since they will link to the "true" URL's. Also, remove the featured products (<--cat.feature-->) because they will use "true" URL's that include the category directory (those will not work). Also, note that the home.html template is never accessed, only the cats.html and items.html templates are accessed.

You can also skip the make-ini.txt file and just use the .htaccess file by setting path to path=guitars/acoustic-guitars/$1 (note: the last character is the digit 1). You will still need to edit the emplates and remove the navigation bar and categories sidebar as indicated above.

» 15. Template Files

---

Purpose of Template Files

Template files let you customize the web 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 DySE™ view.pl script takes a template, fills in the category and item information and outputs the result to the user. To tell the view.pl script where in the template to fill in the information, you type in "substitution variables" -- they look like text such as {item.price} or as HTML comments such as <!--item.price--> (see below for full details about substitution variables).

---

Template Types and Filenames

Template files are located in the /cgi-bin/dyse/merchant/templates directory. There are several 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 main Categories will appear. Depending upon whether you configured the .htaccess file to show products at the main directory or in a sub-directory, the home.html template will be used to generate the web page either at http://www.domain.com/ or at http://www.domain.com/dir/

2. Category page templates:

   • cats.html : (required) This template is used to display sub-category and product index pages.

   • cats-2.html, cats-3.html, cats-4.html, etc. : (optional) These optional templates are used instead of the cats.html template to display sub-category and product index pages at the category depth specified in the filename (e.g.: 2, 3, 4, etc.). The depth of the home page is 1. These templates thus let you customize the index pages based on the depth of the page.

3. Item page template:

   • items.html : (required) This template is used to display product details pages.

4. Sitemap page template:

   • sitemap.html : (optional) This template is used to display a list of all categories/sub-categories on the sitemap page (/sitemap/ or /dir/sitemap/ depending upon whether you configured the .htaccess file to show products at the main directory or in a sub-directory).

5. Error page template:

   • errors.html : (optional) This template is used to display any errors that may occur when viewing web pages output by view.pl

---

» Sample Template Sets

Each DySE™ Merchant Module comes with several sample sets of templates. Each one presents a different website design. Each template set is in its own directory: templates, templates-set1, templates-set2, templates-set3, etc.  The number of template sets depends upon the particular merchant module.

templates-set1 is an exact copy of templates so you can overwrite the contents of templates and still have set one if you want to go back to using it.

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

To see a sample of what each template set looks like, see the documentation for the particular DySE™ Merchant Module you're using.

Note:   How to use a different sample template set To use a different template set, overwrite the contents of the /cgi-bin/dyse/merchant/templates directory with the templates you want to use. For example, to use the templates-set2 template set, upload the contents of the templates-set2 directory (it's in the .zip file and .tar.gz file) into the /cgi-bin/dyse/merchant/templates directory. If you later want to get the original contents of the templates directory back, it is in the templates-set1 directory.

---

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. You can also learn by opening the sample template sets in your HTML editor and see how they work.

---

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.

---

» PHP and template files

It is not possible to directly use PHP statements (<?php ... ?>) in DySE™ templates.

When you access any DySE™ page, view.pl (a perl script) is run; since view.pl is a .pl file, the server runs it using the server's perl interpreter (/usr/bin/perl); it is not run using the server's PHP interpreter (/usr/bin/php).

The web server takes the output of view.pl and sends it to the user. The server does not do any further processing of the output from .pl files, so it is not possible to mix PHP and perl statements. That's a server design limitation, not a DySE™ limitation.

But you can include the output of PHP scripts in DySE™ templates via a server-side-include (SSI) statement. For example, in the items.html template, you could use the following SSI and pass the item's name as a parameter (e.g.: k):

<!--#include virtual="/myscript.php?k={item.name+}"-->

• In this example, myscript.php is the name of your script; you can use any name for your script; just be sure to use a / at the start of the URL so that the script can be found.

• In this example, k is the name of the parameter (k is short for "keyword"); you can use any name for the parameter; use the parameter name that your script is programmed to read from. You might want to name your parameter q (short for "query").

• In this example, k={item.name+} causes the item's name to be passed to your script as the k parameter. You can pass any item value to your script. For example, to pass the name and the price, you could use: k={item.name+}&p={item.price}  This parameter list would set k to the item name and set p to the item price. The + modified in {item.name+} is required to convert any spaces in the value to + characeters (+ is the internet standard for representing spaces in URL's).

Your myscript.php script would read the k parameter and use it to output keyword-relevant output. The output must not have <HTML>, <HEAD>, or <BODY> tags since the output of your script will be inserted into the webpage at the point where the SSI is located.

Thus when a user accesses a product webpage, mod_rewrite runs view.pl, view.pl processes the template, view.pl does variable substitutions (such as {item.name+}), view.pl sees the SSI and calls the specified script (myscript.php in this case) with the specified parameters, view.pl replaces the SSI statement with the output of the specified script, then after view.pl has done all substitutions the template is sent to the user's web browser.

---

» <META> Tags

The standard items.html template does not have a <META> description or <META> keyword tag. If desired, you can edit the items.html template and add those tags. For example, if you have a DySE::InstrumentPro store (musical instruments) then you might want to add this <META> keywords tag:

<meta name="keywords" content="{item.name*}, musical instruments, {item.category*}">

Note: The * in the variable names (e.g.: {item.name*}) are required. It causes all HTML to be removed from the variable's value so that the value can be used properly inside an HTML tag.

See item.* for a list of the standard item-related variables.

---

» <IMG> and <SCRIPT> in Templates -- Leading / in SRC URL's

If you add an image in your template, the SRC URL of the <IMG> tag must start with a / character; otherwise, your image will appear broken . Similarly, if you have <SCRIPT> tags in your templates, the SRC URL of the <SCRIPT> tag must start with a / character; otherwise, your javascripts will not be included.

For example, the SRC URL "images/logo.gif" will not work; the SRC URL "/images/logo.gif" (with a leading / character) will work. Similarly, the SRC URL "header.js" will not work; the SRC URL "/header.js" (with a leading / character) will work.

Without a leading /, the image and <SCRIPT> is broken because such a URL is relative to the current directory rather than the root directory. For example, suppose the webpage at http://www.domain.com/calendars/cats/siamese.html has an <IMG> wth SRC="images/logo.gif". Since this SRC URL is relative (no leading /), the web browser accesses the image relative to the current webpage; thus accessing http://www.domain.com/calendars/cats/images/logo.gif which displays a broken graphic . By adding a leading / to the URL (SRC="/images/logo.gif"), the web browser then accesses http://www.domain.com/images/logo.gif and the image appears.

Note:   Special directory "img/" DySE™ handles SRC URL's that start with "img/" (no leading /) as special (e.g.: SRC="img/logo.gif"). Look in the templates directory and you will see an img directory that contains graphics. Look in the sample .html template files and you will see <IMG>'s that use that directory, e.g.: <IMG SRC="img/logo.gif"> When DySE™ fills in a template and sends the output to the user, DySE™ looks for SRC's that start with img/ and automatically adjusts the SRC value to start with a / character. For example, SRC="img/logo.gif" is automatically adjusted to SRC="/dyse/merchant/img/logo.gif" (Technical details: For the adjusted path to work, DySE™ creates a symbolic link on the hard drive from /dyse/merchant/img/ to /cgi-bin/dyse/merchant/templates/img/ If the images appear broken, see: Broken Graphics above).

---

» <BASE> Tag

Important:   <BASE> Tags must not be used DySE™ view.pl outputs relative links (e.g.: "item.html" and "../category/"). Relative links are not compatible with <BASE> tags. You must not use a <BASE> tag in your templates. You must make all your URL's start with / so they are relative to the root directory. See above: <IMG> and <SCRIPT> in Templates -- Leading / in SRC URL's

» 16. 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.

Below is a list of the template substitution variables. You can also learn by opening the sample template sets in your HTML editor and see how they work.

To learn more about templates, see: Template Files above.

See also: Template Directives below.

---

» cat.*

The cat.* substitution variables can be used in all templates unless otherwise specified. If a variable cannot be used on a certain page, it returns "" (nothing) on those pages.

Variable	Description
cat.depth	Depth of category; home page has zero depth. Equivalent to path.depth Example: Page path.depth Example URL Home page 0 / Category page 1 /arts-leisure/ Sub-category page 2 /arts-leisure/arts/ Sub-sub-category page 3 /arts-leisure/arts/surrealism/
cat.elders cat.elders.list cat.elders.list.NCOL	Bulleted list of the elder categories of this category ("elders" = grandparent category and its siblings). Can optionally specify number of columns (1, 2, or 3 columns). For example, cat.elders.list.2 shows a 2-column bulleted list.
cat.elders.menu cat.elders.text cat.elders.count	cat.elders.menu: Drop-down menu of elder categories of the current category. If there are no elder categories of the current category, returns "" (nothing). cat.elders.text: Text list of elder categories of the current category. If there are no elder categories of the current category, returns "" (nothing). cat.elders.count: Count of the number of elder categories of the current category. For example, on the home page this substitution variable would return 10 if the home page had 10 sub-categories.
cat.feature.grid cat.feature.grid.NCOL cat.feature.grid.NCOL.NROW	Thumbnails grid of randomly featured products chosen from this category and its subcategories (from the first 300 products; at most 10 per sub-category). Default is grid of 2-columns by 1-row. Can optionally specify number of columns and number of rows. For example, cat.feature.grid.3 shows 3-column by 1-row grid, cat.feature.grid.3.2 shows 3-column by 2-row grid.
cat.feature.list cat.feature.list.NROW	This variable is not implemented yet. It currently returns "" (undefined). Bulleted list of randomly featured products chosen from this category and its subcategories (from the first 300 products; at most 10 per sub-category). Default is list of 5-rows. Can optionally specify number of rows. For example, cat.feature.list.3 shows 3-row list.
cat.feature.text cat.feature.text.NROW	This variable is not implemented yet. It currently returns "" (undefined). Text list of randomly featured products chosen from this category and its subcategories (from the first 300 products; at most 10 per sub-category). Default is list of 5-rows. Can optionally specify number of rows. For example, cat.feature.text.3 shows 3-row list.
cat.fullname	Full name of current category. For example, "Arts & Leisure > Arts". On the home page, returns "Main Categories".
cat.gparent cat.gparent.name cat.gparent.fullname	cat.gparent and cat.gparent.name: Short name of grandparent category. For example, on category page "Tools > Power Tools & Accessories > Planers & Joiners" (or an item page of that category), returns "Tools". cat.parent.fullname: Full name of grandparent category. For example, on category page "Tools > Power Tools & Accessories > Planers & Joiners" (or an item page of that category), returns "Tools".
cat.items.count	Count of the number of products in the current category (does not include products in sub-categories of the current category). For example, on the home page there are no products so this substitution variable would return 0 (zero). You can use this substitution variable to determine if the current page has products on it. Example: <!--if cat.items.count-->     Products Index:     <!--cat.items.grid.3--> <!--else-->     Category Index:     <!--cat.kids--> <!--endif-->
cat.items.grid cat.items.grid.NCOL cat.items.grid.NCOL.NROW	Thumbnails grid of products in this category (does not include products in sub-categories of the current category). Default is grid of 2-columns by 10-rows (defaults set by the grid.rows and grid.columns configuration variables). If there are no products in the current category, returns "" (nothing). Can optionally specify number of columns and number of rows. For example, cat.items.grid.3 shows 3-column by 10-row grid, cat.items.grid.2.5 shows 2-column by 5-row grid. If there are more products than can fit in the grid, then a page navigation bar is automatically added after the grid.
cat.items.menu	Drop-down menu of products in this category. If there are no products in the current category, returns "" (nothing).
cat.items.text	Text list of products in this category. If there are no products in the current category, returns "" (nothing).
cat.items cat.items.list cat.items.NCOL cat.items.list.NCOL	Bulleted list of products in this category. If there are no products in the current category, returns "" (nothing). Can optionally specify number of columns (1, 2, or 3 columns). For example, cat.items.list.2 shows a 2-column bulleted list. All the items are show in one list; they are not split across multiple pages like the way grids are (see cat.items.grid).
cat.kids.count	Count of the number of sub-categories in the current category. For example, on the home page this substitution variable would return 10 if the home page had 10 sub-categories. You can use this substitution variable to determine if the current category has sub-categories. Example: <!--if cat.kids.count-->     Category Index:     <!--cat.kids--> <!--endif-->
cat.kids.menu	Drop-down menu of sub-categories of the current category. If there are no sub-categories of the current category, returns "" (nothing).
cat.kids.text	Text list of sub-categories of the current category. If there are no sub-categories of the current category, returns "" (nothing).
cat.kids cat.kids.list cat.kids.list.NCOL	Bulleted list of sub-categories of the current category. If there are no sub-categories of the current category, returns "" (nothing). Can optionally specify number of columns (1, 2, or 3 columns). For example, cat.kids.list.2 shows a 2-column bulleted list.
cat.main.count	Count of the number of categories on the home page. For example, if the home page had 10 categories, then this substitution variable would return 10.
cat.main.fullname	Full name of main category. For example, on the "Arts & Leisure > Arts" category page, returns "Arts & Leisure". On the home page, returns "" (nothing).
cat.main.menu	Drop-down menu of categories of the home page.
cat.main.name	Short name of main category. For example, on the "Arts & Leisure > Arts" category page, returns "Arts & Leisure". On the home page, returns "" (nothing).
cat.main.text	Text list of categories on the home page. Can be used on an item page to display a list of the main categories.
cat.main cat.main.list cat.main.list.NCOL	Bulleted list of categories on the home page. Can optionally specify number of columns (1, 2, or 3 columns). For example, cat.main.list.2 shows a 2-column bulleted list.
cat.name	Short name of current category. For example, on the "Arts & Leisure > Arts" category page, returns "Arts". On the home page, returns "Main Categories".
cat.parent cat.parent.name cat.parent.fullname	cat.parent and cat.parent.name: Short name of parent category. For example, on category page "Tools > Power Tools & Accessories > Planers & Joiners" (or an item page of that category), returns "Power Tools & Accessories". cat.parent.fullname: Full name of parent category. For example, on category page "Tools > Power Tools & Accessories > Planers & Joiners" (or an item page of that category), returns "Tools > Power Tools & Accessories".
cat.siblings cat.siblings.list cat.siblings.list.NCOL	Bulleted list of the sibling categories of this category ("siblings" = other categories at the same category level as the current category). Can optionally specify number of columns (1, 2, or 3 columns). For example, cat.siblings.list.2 shows a 2-column bulleted list.
cat.siblings.menu cat.siblings.text cat.siblings.count	cat.siblings.menu: Drop-down menu of sibling categories of the current category (note: includes the current category). cat.siblings.text: Text list of sibling categories of the current category (note: includes the current category). cat.siblings.count: Count of the number of sibling categories of the current category (note: count includes the current category).
cat.sub.count	Count of the number of sub-categories in this main category. For example, on the "Arts & Leisure > Arts" category page, counts the number of sub-categories of the "Arts & Leisure" category. On the home page or a main category page, returns "" (nothing).
cat.sub.fullname	Long name of sub-category. For example, on the "Arts & Leisure > Arts > Surrealism" category page, returns "Arts & Leisure > Arts". On the home page or a main category page, returns "" (nothing).
cat.sub.menu	Drop-down menu of sub-categories in this main category. For example, on the "Arts & Leisure > Arts", displays drop-down menu of sub-categories of the "Arts & Leisure" category. Can be used on an item page to display a list of the sub-categories.
cat.sub.name	Short name of sub-category. For example, on the "Arts & Leisure > Arts > Surrealism" category page, returns "Arts". On the home page, returns "" (nothing).
cat.sub.text	Text list of sub-categories in this main category. For example, on the "Arts & Leisure > Arts", displays a text list of sub-categories of the "Arts & Leisure" category. Can be used on an item page to display a list of the sub-categories.
cat.sub cat.sub.list cat.sub.list.NCOL	Bulleted list of sub-categories in this main category. For example, on the "Arts & Leisure > Arts", displays a bulleted list of sub-categories of the "Arts & Leisure" category. Can be used on an item page to display a bulleted list of the sub-categories.
cat.type.home	Returns 1 if current page is the home page. Otherwise, returns 0 (zero).
cat.type.main	Returns 1 if current page is a main category, such as "Arts & Leisure". Otherwise, returns 0 (zero).
cat.type.sub	Returns 1 if current page is a sub-category of the main category, such as "Arts & Leisure > Arts". Otherwise, returns 0 (zero).
cat.type.subdeep	Returns 1 if current page is deeper into the category hierarchy than a sub-category of the main category (i.e.: depth is greater than 2), such as "Arts & Leisure > Arts > Surrealism". Otherwise, returns 0 (zero).

---

» cfg.*

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

See also: cfg Template Directive below.

Variable	Description
cfg.NAME	The configuration variable cfg.NAME. For example, cfg.navbar.home would be the value of the navbar.home configuration variable.
NAME	Same as cfg.NAME if NAME is not one of the built-in variables.

---

» date.*

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

Variable	Description
date	Today's short date, e.g.: 01/31/2005
date.long	Today's long date, e.g.: Monday, January 31, 2005
date.ymd	Today's YYMMDD date, e.g.: 050131. Such a date can be used in an {if} statement to conditionally include/exclude HTML based on today's date. Example: <!--if date.ymd >= 050701-->     <P>Today is July 1, 2005 or later</P> <!--endif--> <!--if date.ymd = 050701-->     <P>Today is July 1, 2005</P> <!--endif--> <!--if date.ymd < 050701-->     <P>Today is before July 1, 2005</P> <!--endif--> <!--if date.ymd >= 050701-->     <!--if date.ymd <= 050731-->         <P>Today is some day in July 2005</P>     <!--endif--> <!--endif--> The last example above demonstrates how to use two nested {if} statements to test a range of dates (e.g.: "if today is on or after 2005/07/01, and if today is before or on 2005/07/31, then show some HTML"). You could use such a date range comparison to automatically display a coupon when it becomes valid, and then automatically hide it when it expires.
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/2005 The "as of" date is the last modified date of the datafeed file.
date.asof.long	The "as of" long date, e.g.: Monday, January 31, 2005
date.asof FORMAT	The "as of" date formatted using FORMAT clock codes (see Clock Codes as described in the Associate Engine documentation).

---

if

if is not a Substitution Variable. It is a Template Directive.
See: if Template Directive below.

---

include.*

include.* is not a Substitution Variable. It is a Template Directive.
See: include.* Template Directive below.

---

img.*

img.* is not a Substitution Variable. It is a Template Directive.
See: img.* Template Directive below.

---

» item.*

The item.* substitution variables can be used only in an item template. Depending upon the particular merchant, additional item.* substitution variables may be available. See the DySE™ documentation for the particular merchant module.

Variable	Description
item.category	Short name of category. For example, if product is in category "Arts & Leisure > Arts > Surrealism", then item.category would be "Surrealism". To display the full category name, use cat.fullname instead.
item.currency	Currency. Example; "USD".
item.desc	Description 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	Manufacturer of item. Note: This substitution variable is not available for some merchants; in that case, the value is "" (undefined).
item.name	Name of item.
item.price	Price of item. Does include $ sign and cents, e.g.: "$153.31".
item.sku	SKU (merchant's unique ID #) of item.
item.url	URL to buy item. Contains your affiliate ID. Use this URL in a link, such as: <A HREF="{item.url}">Click here to buy {item.name}</A>

Some merchant modules also support these additional item.* substitution variables:

Variable	Description
item.price.retail	Retail price of item. Does include $ sign and cents, e.g.: "$153.31". See item.price for the sale price.
item.save	The difference between item.price and item.price.retail. Does include $ sign and cents, e.g. "$15.30". Note: Only available if item.price.retail is available.
item.save.percent	The percentage difference between item.price and item.price.retail. Includes % sign, e.g.: "5%". Note: Only available if item.price.retail is available.

---

» merch.*

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

Variable	Description
merch.fullname	Full name of the merchant. Example: "Music Unlimited (InstrumentPro.com)". See also: merch.name
merch.home	URL of the merchant's home page (link includes affiliate ID). Use this as the URL in a link.
merch.id	Affiliate ID. This variable is set in the key file. If no valid key is found, then this variable is empty. Equivalent to the id and cfg.id substitution variables.
merch.name	Short name of the merchant. Example: "InstrumentPro.com". See: merch.fullname
merch.search	URL of merchant's "Advanced Search" page (link includes affiliate ID). Use this as the URL in a link. If the merchant does not have a search page, this URL will be the affiliate link for the merchant's home page instead (link includes affiliate ID).
merch.signup	URL of merchant's sub-affiliate signup page (link includes affiliate ID). Use this as the URL in a link. If the merchant does not support sub-affiliates, this URL will be the affiliate link for the merchant's home page instead (link includes affiliate ID).
merch:URL	Converts an arbitrary non-affiliate URL into an affiliate URL (with your affiliate ID). If the merchant does not support linking to arbitrary URL's, the non-affiliate URL will be returned instead (without any affiliate ID). Notice the colon ":" between merch and URL. For example, with DySE::InstrumentPro, "merch:http://www.instrumentpro.com/C-Whyshophere#freereturn" returns "http://www.instrumentpro.com/C-Whyshophere?source=Affiliates&kbid=1234#freereturn" (this example assumes the affiliate ID is 1234; your ID would be used).

---

» page.*

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

Variable	Description
page.depth	Depth of category; home page has zero depth. Equivalent to cat.depth Example: Page path.depth Example URL Home page 0 / Category page 1 /arts-leisure/ Sub-category page 2 /arts-leisure/arts/ Sub-sub-category page 3 /arts-leisure/arts/surrealism/
page.name	Name of page. On a category page, returns short name of the category. On a product page, returns the name of the product.
page.navbar	Navigation bar. Includes a "Home" link as the first link that goes to the store's home page. Note: If your store is in a sub-directory such as /shop/ then this link goes to /shop/ --- If your store is at the root of your domain (/) then this link goes to / Tip: To change "Home" to some other text, see: Relabel "Home" in the navigation bar.
page.navbar.nohome	This variable is not implemented yet. It currently returns "" (undefined). Navigation bar, without "Home" link.
page.path.dir	Directory name of the current category. On the home page, returns "" (nothing). On a category or sub-category page, returns just the last part of the directory path. For example, for the item at "/art-leisure/arts/surrealism/dali.html", the directory path is "/arts-leisure/arts/surrealism/", so page.path.dir returns surrealism For example, on an item page, you could have a link such as: <A HREF="../{page.path.dir}/">Other items in category {cat.name}</A>
page.path.home ~	Relative directory path to the home page directory. Does not include a trailing "/". On the home page, returns "" (nothing); on category page, returns ".."; on sub-category page, returns "../..", etc. For example, to access the home page from within any template, you could use: <A HREF="{page.path.home}/>Home</A> The tilde character ~ is synonymous with {page.path.home} which returns the relative path to the home page directory. The characeter ~ is easier to use to create links in your templates that are relative to the home page directory. For example, with DySE::Calendars, you can link to the "Animals" category by using HREF="~/animals/"

» 17. Template Directives

To learn more about templates, see: Template Files

• cfg directive
• if directive
• img.* directive
• include.* directive

---

» 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 example sets the navbar.link.style configuration variable to "color: white"   Duration: The duration of the cfg directive is temporary and only applies to the template that it appears in. Read-Only: Some configuration variables are "read-only" and cannot be set inside a template using the cfg directive, e.g.: write.fn.ext. Instead, set those configuration variables globally in the .ini configuration file. if Directive: All the cfg directives are processed (in order from the start of the template file to the end of the file), even those that are inside an if directive that evaluates to false. Thus if there are two or more cfg directives for the same configuration variable, then the last configuration variable value is the one that "sticks".

---

» if

The if directive can be used in all templates.

---

if: if/endif

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:   Matching style of if/endif For each particular set of if/endif, the style must be the same. Be consistent for each set: {if}, {endif} <!--if-->, <!--endif-->

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.

---

if: if/else/endif

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:   Matching style of if/else/endif For each particular set of if/else/endif, the style must be the same. Be consistent for each set: {if}, {else}, {endif} <!--if-->, <!--else-->, <!--endif-->

---

if: if/elsif/else/endif

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). Any number of elsif sections can be used. 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}

Note:   Matching style of if/elsif/else/endif For each particular set of if/elsif/else/endif, the style must be the same. Be consistent for each set: {if}, {elsif}, {else}, {endif} <!--if-->, <!--elsif-->, <!--else-->, <!--endif-->

---

if: condition

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 cat.kids}    This category has sub-categories {else}    This category does not have sub-categories {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:   No space after ! There is no space between the ! and VARIABLE Example: {if !cat.kids}    This category does not have sub-categories {else}    This category has sub-categories {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:   " is optional if no spaces in value 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 Operators: 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:   Numeric or lexicographical comparison If both VARIABLE and VALUE are numeric then they are compared numerically; otherwise, they are compared lexicographically (case-insensitive text comparison). Pattern Match Operators: With the following pattern match operators, "word break" means: space, comma, dash, non-alphanumeric, or start or end of variable value. Pattern Match Operator Meaning Equivalent Regular Expression ^~ First word match (complete word only) This operator allows you to match the first word of the variable. Examples: {if item.name ^~ "cat"}    First word is cat {endif} VALUE Variable ^~ Result cat cat and mouse Yes, starts with word cat. cat caterpillar cocoon No, does not start with word cat (can only match with complete word). ^(VALUE)\b ^* First text match (may be partial word) This operator allows you to match the beginning text of the variable. Examples: {if item.name ^* "cat"}    Starts with cat {endif} VALUE Variable ^* Result cat caterpillar cocoon Yes, starts with text cat. cat dogs and cats No, does not start with text cat. ^(VALUE) ~^~ Inside word match (complete word only) This operator allows you to match a word anywhere inside the variable; does not match word at the start or end of the variable, only in the middle and only a complete word. "Inside" excludes the first and last words of the variable, so cannot match there. Examples: {if item.name ~^~ "cat"}    Contains word cat {endif} VALUE Variable ~^~ Result cat dog and cat chase Yes, contains word cat. cat cat and dog chase No, word not inside the variable (first and last words are excluded from possible match; can only match inside). cat cat No, word not inside the variable (first and last words are excluded from possible match; can only match inside). .\b(VALUE)\b. *^* Inside text match (may be partial word) This operator allows you to match text anywhere inside the variable; does not match text at the start or end of the variable, only in the middle. "Inside" excludes the first and last characters of the variable, so cannot match there. Examples: {if item.name *^* "cat"}    cat inside text {endif} VALUE Variable *^* Result cat cat and dog chase Yes, contains text cat. cat crane and caterpillar Yes, contains text cat. cat vacation to Paris Yes, contains text cat. cat pet the cat No, text not inside the variable (first and last character of variable are excluded from possible match; can only match inside). cat cat and mouse No, text not inside the variable (first and last character of variable are excluded from possible match; can only match inside). .(VALUE). ~ Anywhere word match (complete word only) This operator allows you to match a complete word anywhere (at beginning, inside, or at end). Does not match with partial words. Examples: {if item.name ~ "cat"}    Word cat appears somewhere {endif} VALUE Variable ~ Result cat cat and mouse Yes, contains word cat. cat dog and cat chase Yes, contains word cat. cat caterpillar cocoon No, does not contain word cat (can only match complete word). \b(VALUE)\b * Anywhere text match (may be partial word) This operator allows you to match text anywhere. Will also match partial word. Example: {if item.name * "cat"}    Text cat appears somewhere {endif} VALUE Variable * Result cat caterpillar cocoon Yes, contains text cat. cat vacation to Paris Yes, contains text cat. cat dog and pony show No, does not contain text cat. (VALUE) ~^ Last word match (complete word only) This operator allows you to match the last word of the variable. Examples: {if item.name ~^ "cat"}    Last word is cat {endif} VALUE Variable ~^ Result cat dog and cat Yes, ends with word cat cat dog and cat show No, since last word is not cat. cat silk caterpillar No, since last word is not cat. pillar silk caterpillar No, since last word is not pillar. \b(VALUE)$ *^ Last text match (may be partial word) This operator allows you to match the last text of the variable. Examples: {if item.name *^ "cat"}    Ends with text cat {endif} VALUE Variable *^ Result pillar silk caterpillar Yes, since last text is pillar. cat cat Yes, since last text is cat. cat dog and cat show No, since last text is not cat. (VALUE)$ ~* Anywhere text beginning match (may be partial word) This operator allows you to match word-beginnings anywhere. Examples: {if item.name ~* "cat"}    Some word starts with cat {endif} VALUE Variable ~* Result cat help catch the dog Yes, some word starts with text cat. pillar caterpillar cocoon No, no word starts with the text pillar \b(VALUE) *~ Anywhere text ending match (may be partial word) This allows you to match word-endings anywhere. {if item.name *~ "cat"}    Some word ends with cat {endif} VALUE Variable *~ Result pillar caterpillar cocoon Yes, some word ends with pillar. pillar concrete pillars No, no word ends with pillar. (VALUE)\b 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 false then keep everything up to next matching else or endif. This is the opposite of what if EXPRESSION does (see above). Note:   No space after ! There is no space between the ! and EXPRESSION Note:   ! has lower precedence than the operator 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:   No space after ? There is no space between the ? and VARIABLE Example: {if ?cfg.myvariable}    myvariable is {cfg.myvariable} {else}    myvariable has no value {endif}
if !?VARIABLE	Negated conditional if. If VARIABLE is not defined then keep everything up to next matching elsif or else or endif. This is the opposite of what if ?VARIABLE does (see above). Note:   No space after !? There is no space between the !? and VARIABLE Example: {if !?cfg.myvariable}    myvariable has no value {else}    myvariable is {cfg.myvariable} {endif}

---

» img.*

The img.* directive can be used in all templates. It allows enables you to include an image <img> tag; the image's filename is based on the specified substitution variable or a random filename.

When including an <img> tag, the DySE™ viewer looks for graphic files in the directory /cgi-bin/dyse/merchant/templates/img/

Directive	Description
img.FIELD	Include an image <img> tag. The image's filename is based on the specified field FIELD. If there is no graphic file with that filename, no <img> tag is included, that is, the result is undefined. The syntax of this directive is: img.FIELD /DIR .ENDING FORMAT Everything after img.FIELD are optional parameters. The ordering of parameters is important and they must be specified in the order shown above. The optional parameters are: /DIR Add the optional /DIR parameter to specify a sub-directory where the image file is located. When /DIR is specified, the DySE™ viewer looks in the directory /cgi-bin/dyse/merchant/templates/img/DIR/ .ENDING Add the optional .ENDING parameter to specify a different filename ending; the default is .gif FORMAT Add the optional FORMAT parameter to specify one or more formatting options. Specify the formatting options as a comma-separated list of one or more of the following formatting options: Formatting Option Meaning a Put <img> in <a></a> containter tag, linking the image to the merchant home page. p Put image in <p></p> paragraph container tag. center Put image in <center></center> center container tag. hspace hspace=NUMBER Add hspace attribute to <img> tag, adding horizontal spacing on the left and right of the image. The default spacing is 8. Add NUMBER to specify a different hspace value. middle Add align="ABSMIDDLE" attribute for vertical alignment. click Append text "<br>Click here for MERCHANT" to link. Only works if a formatting option is also specified. > Separator: If the value of the FIELD contains " > " (such as found in cat.fullname) then the DySE™ viewer splits up the value at each " > " and tries each of those sub-values as a filename in turn until a graphic file is found. For example, if cat.fullname is "Animals > Bears > Polar Bears", then the DySE™ viewer looks for: polar-bears.gif, then for bears.gif, then for animals.gif.
img.FIELD.fn	Similar to img.FIELD directive above. (Note: You can specify the optional parameters /DIR and .ENDING). Rather than including an <img> tag, the filename of the intended graphic file is returned instead. Use this directive to determine what to name your graphic file. > Separator: If the value of the FIELD contains " > " (such as found in cat.fullname) then all possible values are returned as a comma-separated list. For example, if you specify /clipart as the /DIR parameter and if cat.fullname is "Animals > Bears > Polar Bears", then the result is: clipart/(polar-bears, bears, animals).gif. The left-to-right order of the list inicates the search order that the DySE™ viewer uses. Also, a unique 8-character value based on the entire value (e.g.: "Animals > Bears > Polar Bears") is also used as a filename.

---

» include.*

The include.* directive can be used in all templates. It allows you to include static text files into the webpage. DySE™ cannot run any programming code (e.g.: PHP) that is in the static text files. To include dynamic content, use Server-Side-Include (SSI) statements instead. See also: "PHP and template files".

Tip:   Server-Side-Include (SSI) statements Server-Side-Include (SSI) statements such as <!--#include virtual="/inc/header.txt"--> are supported in view.pl v5.06.23 (and higher). You can include your static or dynamic content using an SSI, such as: <!--#include virtual="/cgi-bin/myprogram.pl"--> <!--#include virtual="/stuff/header.txt"--> <!--#include virtual="/footer.txt"-->

When a file is to be included, the DySE™ viewer looks in the following directories and stops when it finds the specified file:

1. /cgi-bin/dyse/merchant/include/FILE
   /cgi-bin/dyse/merchant/templates/include/FILE

2. /cgi-bin/dyse/merchant/FILE

3. /cgi-bin/dyse/include/FILE
   /cgi-bin/dyse/templates/include/FILE

4. /cgi-bin/dyse/default/include/FILE
   /cgi-bin/dyse/default/templates/include/FILE

5. /cgi-bin/dyse/default/FILE

When you create include files, the filename can end with any of the following filename endings (the DySE™ viewer looks for files in this order): .html, .htm, .shtml, .txt. The filename ending cannot be .php since DySE™ cannot run any programming code; see above: "Server-Side-Include (SSI) statements".

Tip:   Header/footer on all pages See: Add logo / header / footer on all pages

The following include.* directives can be used in all templates:

Directive	Description
include FILE include /DIR FILE	Include the specified file FILE located in one of the include directories. Do not include the filename extension (.html, .htm, .shtml, .txt) as part of FILE. If the file contains a <BODY> tag, then only the contents of the <BODY> is inserted instead of all of the file's contents. Add the optional /DIR option to specify a sub-directory where the file is located. Note the space between /DIR and FILE For example, {include hdr} would include file hdr.html, and {include /common hdr} would include file common/hdr.html
include.all FILE include.all /DIR FILE	Same as {include FILE} except that all of the file is included rather than just the contents of the <BODY> tag.
include.random include.random /DIR	Include a random file from the include directory: /cgi-bin/dyse/merchant/include/ Note that all files with a filename starting with the word "block" are ignored and are excluded from the random file selection (see include.random.block below). If include.random is used more than once in the same template (or a repeat count is specified), each include.random inclusion is guaranteed to include a different random file. Each file will be included at most once. If there are less files available than the number of include.random inclusions, the latter ones will include nothing. If the file contains a <BODY> tag, then only the contents of the <BODY> is inserted instead of all of the file's contents. Add the optional /DIR option to specify a sub-directory where the files are located. For example, {include.random} would include a random file from /cgi-bin/dyse/merchant/include/, and {include /common} would include a random file from /cgi-bin/dyse/merchant/include/common/
include.random.all include.random.all /DIR	Same as {include.random} except that all of the file is included rather than just the contents of the <BODY> tag.
include.random.block include.random.block /DIR include.random.block FILE include.random.block /DIR FILE	Include a random block of HTML from a file in the include directory. The default block file is named "block" (followed by any of the permitted filename endings), such as block.html, located in the include directory. In the block file, each block of text/HTML starts with a <!--block--> HTML comment and ends with a <!--/block--> HTML comment. The text/HTML of a block can be multiple lines. For example: <!--block-->    The text/HTML of the first block <!--/block--> <!--block-->    The text/HTML of the second block <!--/block--> <!--block-->    The text/HTML of the third block <!--/block--> ... <!--block-->    The text/HTML of the last block <!--/block--> If include.random.block is used more than once in the same template (or a repeat count is specified), each include.random.block inclusion is guaranteed to include a different random block. Each block will be included at most once. If there are less blocks available than the number of include.random.block inclusions, the latter ones will include nothing. To specify a different block file, add the optional FILE option. For example, {include.random.block banners} would include from include/banners.html Add the optional /DIR option to specify a sub-directory where the block file is located. For example, {include.random.block /common} would include from include/common/block.html, and {include.random.block /common banners} would include from include/common/banners.html
include.FIELD include.FIELD /DIR	Include a file located in one of the include directories. The filename is based on the field FIELD. The field can be any substitution variable, such as any item variable (see item.*). For example, {include.mfg} includes a file based on the manufacturer's name. If the manufacturer is "All That Jazz" then would include file all-that-jazz.html (note: all lowercase). If the file contains a <BODY> tag, then only the contents of the <BODY> is inserted instead of all of the file's contents. Add the optional /DIR option to specify a sub-directory where the files are located. For example, {include.mfg /stuff} would include from include/stuff directory. See: {include.FIELD.fn} > Separator: If the value of the FIELD contains " > " (such as found in cat.fullname) then the DySE™ viewer splits up the value at each " > " and tries each of those sub-values as a filename in turn until an include file is found. For example, if cat.fullname is "Animals > Bears > Polar Bears", then the DySE™ viewer looks for include files: polar-bears.*, then for bears.*, then for animals.*. Also, a unique 8-character value is also searched for as an include file (see .fn below to determine the unique value used).
include.FIELD.fn include.FIELD.fn /DIR	Displays the filename of the intended include file for {include.FIELD}. Use this directive to determine what to name your include file. For example, if the product's SKU is "ABC123" then {include.sku.fn} would display abc123 (note: all lowercase). This is the base filename that would be searched for by {include.sku} Add the optional /DIR option to specify a sub-directory. For example, {include.sku.fn /stuff} for SKU "ABC123" would display stuff/abc123 > Separator: If the value of the FIELD contains " > " (such as found in cat.fullname) then all possible values are returned as a comma-separated list. For example, if you specify /clipart as the /DIR parameter and if cat.fullname is "Animals > Bears > Polar Bears", then the result is: clipart/(polar-bears, bears, animals). The left-to-right order of the list inicates the search order that the DySE™ viewer uses. Also, a unique 8-character value based on the entire value (e.g.: "Animals > Bears > Polar Bears") is also used as a filename.
include.FIELD.all include.FIELD.all /DIR	Same as {include.FIELD} except that all of the file is included rather than just the contents of the <BODY> tag.
include.FIELD.block include.FIELD.block /DIR include.FIELD.block /DIR FILE	Similar to {include.random.block} except that the block number remains constant per page. With {include.FIELD.block}, the block number remains constant. In contrast, with {include.random.block}, the block number changes each time the webpage is viewed. For example, {include.sku.block} will include a block and the block number is based on the SKU. The conversion from SKU to block number is evenly distributed.

In addition to the above include.* directives, the following additional include.* directives can be used in items templates:

Directive	Description
include include.sku	Include a file (based on the product's SKU) located in one of the include directories. 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, if the product's SKU is "ABC123" then <!--include--> would include file abc123.html (note: all lowercase).
include.all include.sku.all	Same as {include} except that all of the file is included rather than just the contents of the <BODY> tag.

Repeat Count

All include.* directives support a repeat count. Add *NUMBER to the end of the directive to repeat the inclusion. For example {include.random *5} includes five random files; and {include /banners 120x60 *3} includes the file /banners/120x60.html three times. Note that the repeat count must appear as the last option of the directive. The maximum repeat count is 100.