Associate Engine : Page Templates  
Home > Associate Engine > Documentation > Page Templates

Affiliate Marketing Blog · Follow Us on Twitter · PPC ROI Calculator

Page Templates

Browse Page Templates
 


Page Templates vs. Format Templates

Associate Engine supports two types of templates: Page Templates (described below) and Format Templates. Page Templates control the "big picture". Format templates control the "small picture".

  1. Page Templates (formerly known as "Results Templates") let you control the overall look of the page so it matches the rest of your website; you would put your navbar, page header/footer in here using standard HTML like on all your other webpages -- and you would use {results} to say where you want the results to show up in the page. See template parameter.

  2. Format Templates let you control the format of the results shown using the {results} substitution variable in your Page Templates.. You can think of formatting codes as macros and form letters in a word processor. The format parameter (which is optional) specifies what format template to use.



Page Templates:

Page Templates are used customize the page that results are shown on. The Associate Engine script creates the results page by first fetching data from amazon.com, formatting it so it contains your affiliate ID in the links, and then reads a "Page Template" (located on the same webserver where the Associate Engine script is located) and substitutes the results into the template. The Page Template is just an HTML file that you creating using whatever tools you typically use to create HTML files.



Sample Page Templates:

Sample Page Templates are included in the script's .zip (and .tar) distribution file.

Three types of sample page templates are included: Basic, Basic2, and Store.


Basic page template (orange)

 


Store page template

The Basic and Basic2 page templates are similar. Basic has a sidebar showing links to all the amazon.com product categories, whereas Basic2 does not have that sidebar.

Unpack the distribution file and see the ae-template directory included with the script.

VERY  IMPORTANT: To use the sample Page Templates, upload the ae-template directory as well as the the ae-format directory to your webserver. Put them in the same directory where ae.pl is located. So if you have ae.pl in cgi-bin, then you should end up with the following: (your cgi-bin may have more subdirectories in it then shown below)


Basic:

This type consists of a single Page Template file that applies to all search results (i.e.: the same template is used for books, DVDs, toys, etc.). See the ae-template/basic directory. Included in that directory are four color variations of the Page Template (i.e.: aqua, blue, green, orange).

To use one of these basic templates, set the template.dir configuration variable in ae-ini.txt to one of the following values:

Value Meaning
ae-template/basic/aqua Use the aqua-colored basic template.
ae-template/basic/blue Use the blue-colored basic template.
ae-template/basic/green Use the green-colored basic template.
ae-template/basic/orange Use the orange-colored basic template.


Basic page template (aqua)

 


Basic page template (blue)



Basic page template (green)

 


Basic page template (orange)


Basic2:

This type consists of a single Page Template file that applies to all search results (i.e.: the same template is used for books, DVDs, toys, etc.). See the ae-template/basic2 directory. Included in that directory are four color variations of the Page Template (i.e.: aqua, blue, green, orange).

To use one of these basic templates, set the template.dir configuration variable in ae-ini.txt to one of the following values:

Value Meaning
ae-template/basic2/aqua Use the aqua-colored basic2 template.
ae-template/basic2/blue Use the blue-colored basic2 template.
ae-template/basic2/green Use the green-colored basic2 template.
ae-template/basic2/orange Use the orange-colored basic2 template.


Basic2 page template (aqua)

 


Basic2 page template (blue)



Basic2 page template (green)

 


Basic2 page template (orange)


Store:

This type consists of a set of 23 Page Template files that form a complete store. There is a template file for each possible value of the mode parameter (i.e., dvd.html, books.html, toys.html, blended.html, etc.).


Store page template

To use the store templates, do the following steps:

  1. Set the template.dir configuration variable in ae-ini.txt to ae-template/store

  2. In the .zip file, there is a ae-template/ae-img directory. Upload the ae-img directory to the root directory of your website. The graphic files in that directory are used in the templates. Once uploaded, you should be able to see them in your web browser; go to: www.DOMAIN.com/ae-img/on.gif (substitute your own website's domain name for DOMAIN ); you should see a horizontal line such as at http://www.bime.com/ae-img/on.gif Note: If you want to use a different directory, then set the store.img.url configuration variable in ae-ini.txt to the URL (default is /ae-img)

  3. To change the colors, change the store.* configuration variables in ae-ini.txt. For example, store.tabs.color specifies the color of the tabs along the top of the page.



Multiple Page Templates:

You can also setup a different Page Template for each of the different possible values of the mode script parameter. For example, your "Books Bestsellers" page (mode=books) can have a different layout than your "Toys Bestsellers" page (mode=toys). You do this by creating Page Template files named books.html and toys.html in the ae-template directory. (See: mode values)

When you do an ASIN search of one ASIN, a mode is implied based on the amazon.com product section the product belongs to. For example, asinsearch=1561708755 shows the product that has ASIN 1561708755; since this product is a book, ae-template/books.html is used if it exists.

The script determines what template file to use by going through the following list and stopping once a template file is found:

  1. If script parameter specified, use template defined in {format.template.script} formatting code.

  2. If iframe parameter specified, use template defined in {format.template.iframe} formatting code.

  3. If ssi parameter specified, use template defined in {format.template.ssi} formatting code.

  4. If template parameter specified, use the template file ae-template/TEMPLATE.html if it exists. TEMPLATE is specified by the template parameter. So template=myresults causes ae-template/myresults.html to be used if it exists.

  5. If mode parameter is specified and is a number NUMBER (e.g.: 163357) and browse.NUMBER configuration variable is defined in ae-ini.txt (e.g. browse.163357 = "comedy-dvds"), then use the template file specified in the variable (e.g.: ae-template/comedy-dvds.html).

  6. If mode parameter is specified and is a number NUMBER (e.g.: 163357) then use the template file specified by the number NUMBER (e.g.: ae-template/163357.html).

  7. If mode parameter is specified (or is implied in an ASIN search), use the template file ae-template/MODE.html if it exists. MODE is specified by the mode parameter explicitly or by an implied mode when doing an ASIN search of one ASIN. So mode=dvd causes ae-template/dvd.html to be used if it exists.

  8. If the template configuration variable in ae-ini.txt is set, use ae-template/TEMPLATE.html if it exists. TEMPLATE is specified by the template configuration variable in ae-ini.txt. So setting template configuration variable in ae-ini.txt to myresults causes ae-template/myresults.html to be used if it exists.

  9. If ae-template/ae.html exists then use it; where ae is implied by the name of the ae.pl file itself. If you change the name of ae.pl to shop.pl, then ae-template/shop.html would be used if it exists.

  10. If ae-template/default.html exists then use it.

  11. Otherwise, use template defined in {format.template.default} formatting code.

Note: The name of the directory ae-template is specified by the template.dir configuration variable in ae-ini.txt.



Creating a Page Template to Match Your Site:

Associate Engine comes with several Sample Page Templates in the ae-template directory. You can either use those as is, modify them to match your website design by using your HTML editor, or create your own page template from scratch to match your website design.

Modify an existing template:

Open it in your HTML editor. The only necessary part of a template is the {results} tag. It tells Associate Engine where to search insert the results in template. You can modify/delete anything else in the template. See: Page Template Substitution Variables.

From Scratch:

The quickest way to make a page template from scratch that matches your website design is as follows:

  1. Start with one of your existing webpages (preferably a file located in your / root directory) and make a copy of it (so you don't accidentally modify your original file).

  2. Delete the "content" portion of that page to make space for where the search results will go. Keep all the design elements of the page, such as page header, page footers, navigation bars, sidebars, etc. The user will see whatever you keep in this file. (Note: If you're using SSI statements in your template, see Server-Side-Include Statements).

  3. Type {results} in that space where the "content" was. IMPORTANT: Those are curly braces { and } rather than parentheses ( and ) around the word results. If your HTML editor is strict about syntax and won't let you type text in that space, then insert the HTML comment <!--results--> instead.

  4. Insert a <BASE HREF="http://www.DOMAIN.com/"> statement somewhere inside the <HEAD></HEAD> tag (IMPORTANT: use your own domain name). This will cause all partial URL's on the page to be prefixed with the value of the HREF specified in the BASE (e.g.: http://www.DOMAIN.com/). Thus a partial URL such as "images/logo.gif" will be interpretted by the web browser as http://www.DOMAIN.com/images/logo.gif (See: Partial URL's for an explanation of why the <BASE> statement is necessary).

  5. Upload your template file to ae-template/default.html Note: You might want to rename the existing ae-template/default.html file (e.g.: rename it to ae-template/default-original.html) so you still have the original file in case you want to use it later.

  6. To see the template in use, access any Associate Engine URL, such as http://www.DOMAIN.com/cgi-bin/ae.pl?type=best&mode=dvd
    If any of your graphics appear broken [x], check the HREF value of the <BASE>.



Partial URL's:

When creating your Page Templates, keep in mind that the address of the page being displayed will by something like:

http://www.DOMAIN.com/cgi-bin/ae.pl?type=...

Thus all partial URL's (e.g.: logo.gif) will be prefixed with http://www.DOMAIN.com/cgi-bin/ (e.g. http://www.DOMAIN.com/cgi-bin/logo.gif). This is most likely not what you intended.

There are two possible solutions to solve this problem. Do one of the following:

<BASE> Statement:
The simplest solution (and the quickest to do) is for you to include a <BASE HREF="http://www.DOMAIN.com/"> somewhere inside the <HEAD></HEAD> tag of the Page Template. Thus all partial URL's on the page will be prefixed with the value of the HREF specified in the BASE (e.g.: http://www.DOMAIN.com/). Thus a partial URL such as "images/logo.gif" will be interpretted by the web browser as http://www.DOMAIN.com/images/logo.gif

URL's relative to / (root directory):
Edit your Page Template file and change all your <A> tags, <IMG> tags, and BACKGROUND attributes to use URL's relative to the root (e.g.: "/images/logo.gif") or full URL's (e.g.: "http://www.DOMAIN.com/images/logo.gif"). You cannot use partial URL's (e.g.: "images/logo.gif" or "logo.gif").



Page Template Substitution Variables:

To tell the Associate Engine script where you want the results to appear in the Page Template, you just include the text {results} or a comment <!--results--> at that point in the Page Template file.

Besides the "results" substitution variable, the script supports several other substitution variables (see the table below for details). To use a substitution variables in your template file, include the text {NAME} or a comment <!--NAME--> where NAME is the name of the substitution variable. Uppercase/lowercase in the name does not matter.

Substitution variables can be nested, that is, defined one inside another. For example, in the ae-ini.txt configuration file you could define a user-defined substitution variable "xtitle=<P>Results of {title} as of {date}:</P>" and then in all your templates use "{xtitle}". Nesting is supported to a depth of 10 levels, and the maximum expansion length is 128K.

Variable Description
amazon

URL of the amazon.com home page. This URL contains your affiliate ID so you can use it in the HREF of a link, such as <A HREF="{amazon}">Click here for amazon.com</A>

amazonID

Your amazon.com associate ID.

asofDate
asofDate FORMAT

The date of the results. If the results are coming from the cache, then this will be the date that the results were originally fetched from amazon.com and stored in the cache. If the FORMAT clock format is not specified, then the date is formatted as: "Wednesday, January 1, 2003". See Clock Codes. See also: substitution variable {date} which displays the current date.

cfg.NAME

The configuration variable called NAME. For example, you can use "{cfg.amazonid.uk}" to display or use your amazon.co.uk associates ID specified in the amazonid.uk configuration variable.

date
date FORMAT

Today's date. Format is: "Weekday, Month Day, Year", such as "Wednesday, January 1, 2003". You can use this in text, such as: <P>Prices as of {date}</P>. If the FORMAT clock format is not specified, then the date is formatted as: "Wednesday, January 1, 2003". See Clock Codes.

form.NAME

The script parameter called NAME. For example, you can use "form.keyword" to display the keywords specified in the keyword script parameter. Note: Some script parameters are modified by the script; use form1.NAME to access the original unmodified script parameters.

form1.NAME

The script parameter called NAME. For example, you can use "form1.keyword" to display the keywords specified in the keyword script parameter. Note: That's a digit one in the variable name, not a lowercase L.

include TEXT

Include the include file ae-include/TEXT.html based on the specified TEXT (the TEXT supports Clock Codes). If the file does not exist, then nothing is included. The text TEXT is automatically converted to lowercase thus the filename on disk must be all lowercase.

Note: If you are using the latest beta version of ae.pl, the filename on disk can have the ASIN as all lowercase or as all uppercase. Thus ae.pl will search for ae-include/b00005yw4h.html and then for ae-include/B00005YW4H.html -- so you can use either name.

includeasin

Include the include file ae-include/ASIN.html based on the ASIN of the current product. If the file does not exist, then nothing is included. The text ASIN is automatically converted to lowercase thus the filename on disk must be all lowercase.

Note: If you are using the latest beta version of ae.pl, the filename on disk can have the ASIN as all lowercase or as all uppercase. Thus ae.pl will search for ae-include/b00005yw4h.html and then for ae-include/B00005YW4H.html -- so you can use either name.

includeasin TEXT

Include the include file ae-include/ASIN-TEXT.html based on the ASIN of the current product and the specified TEXT (the TEXT supports Clock Codes). If the file does not exist, then nothing is included. The text ASIN-TEXT is automatically converted to lowercase thus the filename on disk must be all lowercase.

Note: If you are using the latest beta version of ae.pl, the filename on disk can have the ASIN as all lowercase or as all uppercase. Thus ae.pl will search for ae-include/b00005yw4h-review.html and then for ae-include/B00005YW4H-REVIEW.html -- so you can use either name.

mode

The full name of the amazon.com section selected by the "mode" script parameter as text. E.g.: If the mode=music then returns "Popular Music". To access the mode script parameter use {form1.mode} instead.

navbar

Use "{navbar}" to display the navigation bar ("navbar" for short) that appears on the amazon.com page that the results are based on.

results

The results as read from amazon.com and reformatted so that links contain your affiliate ID. See Format Templates.

title

Use "{title}" to display the page title.

type

Value of the "type" script parameter as text.

URLkeyword

Value of the "keyword" script parameter with all spaces replaced with "%20". This allows the keyword value to be used as part of a URL. For example, to link to a search at Google.com using the keywords, use the following URL in the link: http://www.google.com/search?q={urlkeyword}

viewcart

URL to display amazon.com shopping cart. You can use this substitution variable in the HREF of a link, such as: <A HREF="{viewcart}">View shopping cart</A>

xNAME

Value of user-defined script parameter "xNAME" (NAME is one or more letters/numbers) that you supply when calling the script. Uppercase/lowercase in the name does not matter. The letter "x" at the start of the parameter name indicates that this is a user-defined script parameter. For example, if the script is called with "xtitle=My+Favorites" (+ used for spaces), then the variable <!--xtitle--> will be replaced by the text My Favorites. If the Page Template contains a variable that was not specified when calling the script, then the value "(undefined variable: NAME)" is used. When the script substitutes in the value of a user-defined script parameter, the value is automatically HTML encoded ("<" becomes "&lt;", ">" becomes "&gt;", quotation mark becomes "&quot;", "&" becomes "&amp;").

Save your Page Template file as "ae.html" and upload it to the cgi-bin directory where the ae.pl script file is located.

If the script cannot find your Page Template file, it will use a built-in default template, which is:

<html>
  <head><title>{search}</title></head>
  <body bgcolor=white>
    <p><b>{search}</b></p>
    {results}
  </body>
</html>



Substitution Modifiers:

Depending upon where you are using a substitution variable in the HTML of your Page Template, it may be necessary for the substituted value to be modified slightly. For example, if you use use keywords in a URL, spaces would have to be replaced with + (plus signs).

To specify a substitution modifier, add the Modifier after the variable name. See the table below for a list of the Modifier and what they do. For example, {keywords+} is the modified version of {keywords}.

You can also limit the length of the value by adding a number after the Modifier. If the value has more characters than the number you specify, then words are removed from the end of the value until the length is less than or equal to the number you specify. If words were removed then "..." is appended to the end. For example, {keywords:32} limits the length to 32 characters.

The following two tables present the same information. Read whichever table you find easier to understand.

Modifier Description
^ Returns original value unmodified. Note: Length is not modified.
* Remove HTML tags and & encoding, and remove: &, ', and "
@ Same as * but keeps & encoding
+ Same as * and also remove: &, =, and ?. And convert spaces to +
- Same as * and also remove: &, =, and ?. And convert spaces to -
% Same as * and also remove: &, =, and ?. And convert spaces to %2B (%2B is the ASCII value of +)
: No change (typically followed by a length limiter NUMBER)

Modifier HTML Tags & Encoding & ' and " =and ? Spaces Length
^ No change No change No change No change No change No change No change
^NUMBER No change No change No change No change No change No change No change
* Removed Removed Removed Removed No change No change No change
*NUMBER Removed Removed Removed Removed No change No change Shortened
@ Removed No change Removed Removed No change No change No change
@NUMBER Removed No change Removed Removed No change No change Shortened
+ Removed Removed Removed Removed Removed Convert to + No change
+NUMBER Removed Removed Removed Removed Removed Convert to + Shortened
- Removed Removed Removed Removed Removed Convert to - No change
-NUMBER Removed Removed Removed Removed Removed Convert to - Shortened
% Removed Removed Removed Removed Removed Convert to %2B No change
%NUMBER Removed Removed Removed Removed Removed Convert to %2B Shortened
: No change No change No change No change No change No change No change
:NUMBER No change No change No change No change No change No change Shortened



Server-Side-Include (SSI) Statements:


Associate Engine v4.04.04 or higher :

Server-Side-Include (SSI) statements that are of the format <!--#include virtual="someurl"--> can be included in the page template and are processed directly by Associate Engine. The someurl can be relative to / such as /header.html or it can be absolute such as http://www.mydomain.com/header.html (an absolute URL can be for any domain, not just the one where Associate Engine is running on). Associate Engine fetches the HTML at the specified URL using the HTTP GET method. As an optimization, if the someurl is a local text file *.txt, such as /header.txt or /stuff/header.txt (inside some subdirectory), then Associate Engine reads the file directly rather than issuing a GET to the webserver.

Associate Engine v4.01.01 or less :

It is not possible to include Server-Side-Include (SSI) statements in page templates. For an alternative to SSI, see Alternative below. This limitation is because Apache web servers do not parse SSI statements that may be in any output of Associate Engine. This limitation applies to all cgi-bin scripts, not just to Associate Engine. Associate Engine ignores SSI statements.

Alternative:

As an alernative to using an SSI to include a HTML/text file, then you can do the equivalent by using the {include text} substitution variable to include the file ae-include/text.html. For example, {include header} would include the file ae-include/header.html



Useful amazon.com URL's:

The following links may be useful to include in your Page Templates or somewhere on your website. In these links, replace AMAZONID with your amazon.com affiliate ID.

For other useful links, log in to amazon.com's associates home page (associates.amazon.com) and select "Build Links" and then select "Text Links". In the "Link to Any Page at Amazon.com" section, enter any Amazon.com URL into the "Enter the URL" box and enter any text into the "Name Your Link" box and then click "Get HTML". Copy the HTML shown to your webpage.




< Previous Table of Contents Next >




Add this page to your Favorites

Yahoo! My Web Google Bookmarks Windows Live Favorites MySpace Facebook.com AskJeeves StumbleUpon Technorati Squidoo Earthlink myFavorites del.icio.us meneame.net

E.&O.E.
© Cusimano.Com Corporation
http://www.c3scripts.com/