|
Associate Engine : Page Templates | |
| Home > Associate Engine > Documentation > Page 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".
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.
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 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 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 templateThe 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 theae-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.
|
|
|
|
|
|
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.
|
|
|
|
|
|
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.).
|
|
To use the store templates, do the following steps:
Set the template.dir configuration variable in
ae-ini.txt toae-template/store In the .zip file, there is a
ae-template/ae-img directory. Upload theae-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 athttp://www.bime.com/ae-img/on.gif Note: If you want to use a different directory, then set the store.img.url configuration variable inae-ini.txt to the URL (default is/ae-img )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.
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:
If script parameter specified, use template defined in {format.template.script} formatting code.
If iframe parameter specified, use template defined in {format.template.iframe} formatting code.
If ssi parameter specified, use template defined in {format.template.ssi} formatting code.
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 causesae-template/myresults.html to be used if it exists.If mode parameter is specified and is a number NUMBER
(e.g.: 163357) and browse.NUMBER configuration variable is defined inae-ini.txt (e.g. browse.163357 = "comedy-dvds"), then use the template file specified in the variable(e.g.: ae-template/comedy-dvds.html). 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). 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 causesae-template/dvd.html to be used if it exists.If the template configuration variable in
ae-ini.txt is set, useae-template/TEMPLATE.html if it exists. TEMPLATE is specified by the template configuration variable inae-ini.txt . So setting template configuration variable inae-ini.txt to myresults causesae-template/myresults.html to be used if it exists.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, thenae-template/shop.html would be used if it exists.If
ae-template/default.html exists then use it.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 inae-ini.txt .
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:
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).
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).
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.
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).Upload your template file to
ae-template/default.html Note: You might want to rename the existingae-template/default.html file (e.g.: rename it toae-template/default-original.html ) so you still have the original file in case you want to use it later.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>.
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.gifURL'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").
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 |
| amazonID |
Your amazon.com associate ID. |
| asofDate |
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: " |
| 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 |
Today's date. Format is: "Weekday, Month Day, Year", such as "Wednesday, January 1, 2003". You can use this in text, such as: |
| 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 the include file
|
|
| includeasin |
Include the include file
|
|
Include the include file
|
|
| 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: |
| viewcart |
URL to display amazon.com shopping cart. You can use this substitution variable in the HREF of a link, such as: |
| 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 "<", ">" becomes ">", quotation mark becomes """, "&" becomes "&"). |
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>
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 | No change | |
| +NUMBER | Removed | Removed | Removed | Removed | Removed | Shortened | |
| - | Removed | Removed | Removed | Removed | Removed | No change | |
| -NUMBER | Removed | Removed | Removed | Removed | Removed | Shortened | |
| % | Removed | Removed | Removed | Removed | Removed | No change | |
| %NUMBER | Removed | Removed | Removed | Removed | Removed | 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 |
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 fileae-include/text.html . For example,{include header} would include the fileae-include/header.html
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.
Credit Card Protection
http://www.amazon.com/gp/redirect.html?ie=UTF8&location=http%3A%2F%2Fwww.amazon.com%2Fgp%2Fhelp%2Fcustomer%2Fdisplay.html%3FnodeId%3D518224&linkCode=ur2&camp=1789&creative=9325&tag=AMAZONIDamazon.com home page
http://www.amazon.com/exec/obidos/redirect-home/AMAZONIDFor 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 > |
E.&O.E.; © Cusimano.Com Corporation; www.c3scripts.com
