Associate Engine : Documentation : Virtual Directory / mod_rewrite  
Home > Associate Engine > Documentation > Virtual Directory / mod_rewrite

Virtual Directory / mod_rewrite

Browse Virtual Directory
 

Note to webmasters of Windows Servers:

See Windows Servers section below for important note.

Virtual Directory Explained

Virtual Directory makes it possible for Associate Engine results pages to appear as if they are static HTML files rather than accessed via a cgi-bin perl program.

Virtual Directory is implemented using "mod_rewrite". mod_rewrite is a standard feature of Apache webserver (running on linux/unix computers). If you're using a Windows server, see Windows Servers below.

For example, a typical Associate Engine URL that uses parameters is as follows:

The following URL that uses a Virtual Directory is equivalent to the above parameter-based URL:

This URL does not contain anything that suggests that it is a perl program. The URL looks like it is just referring to a directory that is within several subdirectories. To the "outside world" it appears that your webserver contains the following directory tree even though none of these directories actually exists:

The order of the directory names in the Parameters portion of the URL does not matter. The only thing that matters is the first directory name, that is, /amazon/ (this directory name is set in the configuration; see below).

Each of the parameters (NAME=VALUE) has become a directory name (/NAME_VALUE).

Creating a URL:

When you type in a URL, keep the following points in mind:

URL Ending Example URL Meaning
/ /amazon/type_search/mode_books/ URL looks like a directory
/index.html /amazon/type_search/mode_books/index.html URL looks like a index.html file
.html /amazon/type_search/mode_books.html URL looks like a .html file
.htm /amazon/type_search/mode_books.htm URL looks like a .htm file


Webserver Requirements

For Virtual Directory to work, your webserver must have RewriteEngine enabled. The RewriteEngine is part of Apache webservers and allows you to do "search and replace" on URL's (e.g.: replace URL "/amazon/bestbooks" with URL "/cgi-bin/ae.pl?type=best&mode=books"). Note: RewriteEngine might be disabled by your hosting company so you might have to ask your hosting company to enable RewriteEngine on your webserver.

If you're using a Windows server, see Windows Servers below.


Configuration

To configure your webserver and Associate Engine to use Virtual Directory, you have to do two things:

  1. Create a .htaccess file in the root directory of your website.
  2. Set the virtual.dir configuration variable.

.htaccess Server Configuration File

Look in the root directory of your website (i.e.: in the directory where your website's homepage index.html file is located) and see if there is a file called .htaccess located there. If it already exists, then you have to download it, edit it using a text editor (such as Windows Notepad), and then reupload it. If it does not exist, then you can just create a new .htaccess file using a text editor and upload it.

The following four lines need to be in your .htaccess file. Either add these lines to the end of your existing .htaccess file or create a new .htaccess file that contains these lines.

Important: The lines have to be typed exactly as shown below. To prevent typographical errors, open the text file ae-htaccess.txt found in the .zip distribution file, and copy and paste the lines to your .htaccess file.

RewriteEngine on
RewriteBase /
RewriteRule ^(amazon)$ $1/ [R]
RewriteRule ^(amazon)/(.*)(\.[a-z]+)$ cgi-bin/ae.pl?virtual=$2&virtual.dir=$1 [L]
RewriteRule ^(amazon)/(.*)$ cgi-bin/ae.pl?virtual=$2&virtual.dir=$1 [L]

These lines cause all requests that start with /amazon to be rewritten as requests to /cgi-bin/ae.pl The virtual directory path is passed to ae.pl as the virtual parameter and the virtual.dir parameter.

If you want to start your URL's with something other than /amazon such as /shop then change the amazon in the 3rd and 4th and 5th lines, such as shop. If you want to use a sub-directory such as /mystore/shop you can do that; in the above RewriteRule's you would use (mystore/shop)

IMPORTANT: If Associate Engine is located at a different URL than /cgi-bin/ae.pl then change the 4th and 5th lines so that they use the correct URL of Associate Engine (note: leave out the leading / character).

ae-ini.txt Associate Engine Configuration File

Edit your ae-ini.txt configuration file and set the following configuration variables:

virtual.dir    "/amazon"
virtual.ending "/"

IMPORTANT: The directory (or sub-directory) name that you set the virtual.dir variable to must be the same directory (or sub-directory) that you used in the .htaccess file (note: the value in the .htaccess file must not start with a leading / but the value in the virtual.dir variable must start with a leading /

If you want to start your URL's with something other than /amazon such as /shop then change the /amazon, such as /shop. If you want to use a sub-directory such as /mystore/shop you can do that; you would use virtual.dir "/mystore/shop"

IMPORTANT: The leading / in virtual.dir (such as "/amazon") is required. If you leave it out, an error will occur.

IMPORTANT: Do not enter a URL in virtual.dir; just enter /amazon or /shop or whatever you want to call the virtual directory. If you enter something other than /DIRECTORY, an error will occur.

The virtual.ending configuration variable sets the ending that is added to the end of URL's that Associate Engine generates to refer back to itself to do subsequent searches (e.g.: the "More Results" button).

virtual.ending Example Generated URL Meaning
/ /amazon/type_search/mode_books/ URL looks like a directory
/index.html /amazon/type_search/mode_books/index.html URL looks like a index.html file
.html /amazon/type_search/mode_books.html URL looks like a .html file
.htm /amazon/type_search/mode_books.htm URL looks like a .htm file

search.* Pre-Defined Searches

Virtual Directory can also be used in conjunction with pre-defined searches to create very short URL's. See: search.* for details.



Windows Servers

Windows servers do not come pre-installed with mod_rewrite functionality which is required to implement virtual directories. You have to add that functionality via a 3rd-party product such as ISAPI_Rewrite (from Helicon Tech) or IISRewrite (from QwerkSoft). Those products add rule-based rewriting functionality to Windows IIS.

IMPORTANT: We have not tested ISAPI_Rewrite nor IISRewrite with ae.pl. We are not associated with Helicon Tech or QwerkSoft in any way.


Search Forms

Associate Engine v3.06.27 (or less):

If you have a search form on your page template so that the user can do a keyword search, the URL that appears in the address bar when the user submits the form will not be a virtual directory.

The URL will be something like:
http://www.domain.com/cgi-bin/ae.pl?type=search&....

Even though the URL will not be a virtual directory, all the links in the results will be virtual directory links.

Associate Engine v4.01.01 (or higher):

You can set the virtual.redir configuration to yes. This setting will cause Associate Engine to automatically redirect non-virtual URL's (e.g.: /cgi-bin/ae.pl?type=search&...) to virtual URL's (e.g.: /amazon/type_search/...). In this case, when your search form is submitted, Associate Engine will redirect the user to the virtual version of the URL to do the search.

If you set the virtual.redir configuration variable to no, then Associate Engine will not do a redirect and the address bar will continue to show a non-virtual URL when your form is submitted.


Home Page

linux/unix web servers:

Virtual Directory can be configured so that Associate Engine output appears as your home page. Note this is different than including Associate Engine results on your existing home page with your existing content (by using <script> or SSI server-side-include).

To have Associate Engine as your home page, edit your .htaccess file and add the following lines:

RewriteEngine on
RewriteBase /
RewriteRule ^$ /cgi-bin/ae.pl?PARAMETERS [L]

Important notes about the RewriteRule line:

  1. Replace PARAMETERS with the search parameters that you want to use. You can use any search parameters (except for the script, ssi and iframe parameters) as you would with any Associate Engine search .

    For example, template=stores would cause the Stores Directory index to show up as your home page. This assumes that you are using the Store page templates.

    For example, type=browse&mode=books would cause the Books browse index to show up as your home page.

  2. The RewriteRule line assumes that Associate Engine is installed at /cgi-bin/ae.pl. If you have Associate Engine installed at a different location (e.g.: /cgi/shop.pl), then change this line.

  3. To link to your home page from your other pages, link to / or your full domain name. If you want to link to /index.html then edit the RewriteRule and change the ^$ to ^(index\.html)?$ Note: The \ before the . is required otherwise the webserver considers the . as a wildcard character that can match any character.


IMPORTANT: Each time your home page is requested, Associate Engine will run. This is slightly inefficient since the page output will look the same most of the time (as set by your cache.stale time). If you have a lot of users visiting your home page, rather than using the above RewriteRule, you might want to look into setting up a linux cron job that periodically (e.g.: every 1 hour) captures the output from /cgi-bin/ae.pl?template=stores (or whatever search parameters you are using) and save that output to your /index.html file. That way, when users go to your homepage, the webserver outputs the static /index.html file rather than running Associate Engine each time. We use this at our CollectibleCats.com website. For instructions on how to set this up, see: "How do I set up a linux cron job to create a static HTML home page file?"

Windows web servers:

If you are using a Windows web server, read the note above about Windows Servers. Windows servers do not come pre-installed with mod_rewrite. To get virtual directories to work on a Windows server you have to add a 3rd-party "mod_rewrite" product such as ISAPI_Rewrite or IISRewrite.

If all you want to do is show the stores template on your home page (and you do not want Virtual Directory), then the easiest thing to do is to view the stores template web page in your web browser (e.g.: /cgi-bin/ae.pl?template=stores) and then save the HTML to your /index.html home page file. In Internet Explorer, select "File > Save As..." and select "Save as type: Web Page, HTML only". Note: Before doing this, set configuration variable ssi.script to no. When you're done, set ssi.script back to yes (assuming you had it as yes initially).




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