Amazon Products Feed - Advanced Guide

[an error occurred while processing this directive]

This guide is meant to compliment the Amazon Products Feed - Beginners guide. If you have not done so, please browse through it first to get a feel for the script. If you have the Amazon Products Feed installed, configured, and working on your server, and are ready to see how to customize the script further...then this is the guide for you. You should always check the Amazon Products Feed page for updated information and MrRat's Script Support forum for help. For other scripts by MrRat, click here.

    Choose a section or scroll down:
  1. Templates Results
    1. Variables
    2. Page Template
    3. Products Template
    4. Item Template
    5. Other Templates
    6. FrontPage Users
  2. Results
    1. Categories
    2. Search Box
  3. Including search results into your web pages
    1. SSI Include
    2. PHP Include
  4. Advanced Options
    1. APF options
    2. Nav Menu
  5. Change Languages

Templates

Amazon Products Feed utilizes templates to display the products into a browser, there are several templates, but the most important are the Page, Products, & Item Templates. To use custom templates, you need to tell the script where they are located, if it doesn't find one it uses the embedded templates already created within the script. You do not need to customize a template if you are happy with how it displays. For example, if you are happy how the item template displays the item, then you do not need to make your own item template. You can also use different sets of templates to match different sections of your website, or if you desire a different look. That's why it's important to number your templates. It's not necessary, but it helps to keep you organized.

These would be your first template set:
page_1.template, products_1.template, item_1.template...

These would be your second template set:
page_2.template, products_2.template, item_2.template...

To specify template locations, open the script in your text editor, and find the line that says ...
# templates are comma separated lists, and if blank or non-existent will use embedded HTML

after that is where you change what you need.
@page_templates = ("page_1.template", "page_2.template");
@products_templates = ("products_1.template", "products_2.template");

Change each line for each template that you modify, you can use paths to other directories on your server as well.
@page_templates = ("page.template", "/you/can/even/supply/full/path/to_another.template");

Once you specified your templates in the script, re-upload your script in ASCII mode (you shouldn't have to CHMOD it again, but if you have problems, that's the first place to look). Then upload any templates that you have created to the same folder (unless you specified a different location in the script).


Variables

These templates use variables to display certain content, which makes it easy to design. Decide where you want the item's picture to go and place the variable there in the HTML. When making these templates, it's easiest to look at the sample template to get an idea of how each variable works. For a list of all the variables that you can use, click here. One important thing to remember when using these variables, they must have the correct format or the script will ignore them.

Always use %%variable_name%%, and remember that these are case sensitive
%%Item_URL%% is not the same as %%item_url%%.

Always look here for a complete list of variables, this is just meant to explain how the most common variables work and get you started using variables. To use these variables effectively, simply make the HTML for your page and just plug in the variable where you want the information to appear.

The most important variable is:
%%products_html%%
Your page template must have this in order to display products. This variable simply plugs any results of the script into this spot.

Other common variables for your page template are:
%%header%%
Displays either "store : subject" or the linked browse path (i.e. Bestsellers > store > subject) when applicable
%%search_box%%
Displays the Search Box for APF
%%see_next%%    %%see_prev%%
Displays next and previous page buttons

Some common variables for your products template
%%ProductName%%
Displays the name of the product results
%%my_prices%%
Displays List Price, Amazon's Price, & Savings
%%item_url%%
URL to the current product (use this for linking)


Page Template

The page template is the basic HTML design of the webpage that the script results will display in. The most important variable you need on this page is %%products_html%%. This is where the script will place the resutlts that the user searches for (the products). You must have this on your page template or it will not work. When you save your templates, it's important to number each one so that they're easier to refer to them, and you should use the ".template" extension. Ex. page_1.template, page_2.template, etc...

Here is a sample page template:

<HTML><HEAD>
<TITLE>%%store%% : %%subject%%</TITLE>
</HEAD><BODY>
<TABLE Valign="middle" Width="100%">
<TR>
<TD Align="center">
<H1>%%header%%</H1>
<A Href="http://www.amazon.com/exec/obidos/redirect-home/%%associate_id%%"><FONT Size="2"> %%association_text1%% </FONT></A>
<BR>
%%search_box%%
%%chat_link%%
</TD>
</TR>
</TABLE>
<TABLE Bgcolor="#00659C" Cellpadding="0" Cellspacing="0" Width="100%">
<TR>
<TD><DIV Style="font-size: 6pt"> </DIV>
</TD>
</TR>
</TABLE>
<BR>
<CENTER>%%sort_box%%</CENTER>
%%products_html%%
<TABLE Width="100%"><TR>
<TD Align="left" Width="33%"> %%see_prev%% </TD>
<TD Align="center" Width="34%"><FONT Size="-1"> %%see_total%% </FONT></TD>
<TD Align="right" Width="33%"> %%see_next%% </TD>
</TR></TABLE>
<BR>
<TABLE Bgcolor="#00659C" Cellpadding="0" Cellspacing="0" Width="100%"><TR><TD><DIV Style="font-size: 6pt"> </DIV></TD></TR></TABLE>
</BODY></HTML>

One of the easiest ways to make the script results match your site is to copy the HTML from one of your pages, then build a table where you want the results to appear then add the variables like above.

Now that you have the page template done, you're ready to modify how the products look.


Products Template

The products template specifies exactly how each product will appear within the page template. The contents of this template are automatically repeated for each product displayed on a page.

Here is a sample products template:

<TABLE Bgcolor="#FFFFFF" Border="6" Cellpadding="10" Width="100%">
<TR>
<TD Valign="middle">
<A Href="%%item_url%%"><IMG Align="left" Alt= %%store%% : %%ProductName%%"
Border="0" Src="%%ImageUrlSmall%%"></A>
<A Href="%%item_url%%"><B>%%ProductName%%</B></A><BR>
%%my_artists%%<BR>
%%ReleaseDate%%<BR>
</TD>
<TD Align="center" Valign="middle" Width="195">
%%my_prices%%
</TD>
</TR>
</TABLE><BR>


Item Template

The item template specifies how the item information will look when you click on an individual item from the products results page. It utilizes the page template for the main HTML of the page.

Here is a sample item template:

<TABLE Width="100%">
<TR><TD Align="center" Colspan="3" %%my_artists%%</TD></TR>
<TR><TD><BR></TD></TR>
<TR>
<TD Align="center" Valign="top">
<A Href="%%my_large_image_url%%"><IMG Alt="%%store%% : %%ProductName%%" Border="0" Src="%%ImageUrlMedium%%">
<BR><FONT Size="2">%%see_larger_image_text1%%</FONT></A>
</TD>
<TD Valign="top">
%%my_prices%%<BR>
<FONT Size="-1">%%my_used%% %%my_collectible%% %%my_thirdpartynew%% %%my_refurbished%%</FONT>
<BR>
<B>%%availability_text1%%</B> %%Availability%%<BR>
</TD>
<TD Align="center" Valign="middle">
%%oneclick_button%%
</TD>
</TR>
<TR><TD><BR></TD></TR>
<TR><TD Colspan="3">
%%my_descriptors%%
%%my_features%%
%%my_accessories%%
%%my_browse_list%%
%%my_similar_products%%
</TD></TR>
<TR><TD><BR></TD></TR>
<TR Bgcolor="#00659C">
<TD Align="center" Colspan="3">
<B><FONT Color="#FFFFFF" Face="Arial, Helvetica, sans-serif"> %%customer_reviews_text1%% </FONT></B>
</TD>
</TR>
<TR><TD Colspan="3">
<CENTER>%%average_rating_text1%% %%my_avg_rating_display%%</CENTER><BR>
%%my_comments%%
</TD></TR>
</TABLE></CENTER>


Other Templates

There are several other templates that you can use, if you've mastered the page, product, and item templates, you'll have no problem modifying these.

The next few templates are used to display the used and third-party products
  • sellersearch_templates - the HTML to display SellerSearch results - sample
  • sellerprofile_templates - the HTML to display seller profile - sample
  • thirdparty_products_templates - the HTML to display third-party products - sample

FrontPage Users

If you use FrontPage or a similar program to design and manage your site, you can use it to generate a page template. You do have to make a few modifications that are fairly simple. Make a new web page inside FrontPage with the design of your site but the content area blank (easiest way is to copy and paste a web page that has the look you want, then delete the content). Find the spot where you would like the script content to appear and type %%products_html%%. Save this file to your desktop and name it page_1.template. It's important to note how FrontPage writes hyperlinks and images to HTML. Since FrontPage saves all files/images to the same folder, it doesn't specify the directory, but this template will reside in a different directory than your pages and images, so you need to modify a bit.

Open the page in a text editor (notepad is fine) and use the search feature. Search for "href" this will highlight all of the hyperlinks in your page one at a time. If it is a hyperlink that has a full URL already, don't modify it.
By default FrontPage saves them as:
<a href="page.htm">
You simply need to specify the URL, change this to
<a href="http://www.yoursite.com/page.htm">

Same idea for your images, search for "src", and change
<img src="image.jpg">
To:
<img src="http://www.yoursite.com/image.jpg">

If you use background images anywhere in your site, search for "background" and change:
background="background.jpg"
To:
background="http://www.yoursite.com/background.jpg"

As soon as your done, save the file, then FTP it to the same folder that the script resides in (/cgi-bin/amazon/)



Results

To modify the results that the script produces, you can specify it in the URL
You take the initial URL of the script
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi
and add the variables after it with the first variable preceded by a ? -
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi?mode=books
More variables can be added with all of them preceded by a & -
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi?mode=books&templates=3

The most commonly used URL options are

    mode - the mode or category that you are browsing in (Books, Computers, Video, Software, etc…)
    node - the number of the category to browse (sub-categories of modes)
To use these 2 options, take the initial URL of the script
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi
Then let's say you want to browse in books (mode=books)
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi?mode=books
Then we want to look at Computer & Internet books (id=5)
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi?mode=books&node=5
    templates - which set of templates to use
By default, the script will use your first set of templates, you can use the URL to switch to another template
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi?mode=books&node=5&templates=2
    input_string - the search subject
To use the search feature with the URL:
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi/amazon_products_feed.cgi?mode=books&input_string=Web+Services
    link_templates - which set of templates to use for all subsequent pages
By using link_templates, you can display your products using one set of templates, but make all of those templates link to another set of templates. Very handy if you are using SSI Includes to display products on your pages. http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi?mode=books&node=5&link_templates=3
    language - which language file to use see languages

    page - which page of results - Amazon sends 10 results for page 1, 10 for page 2, etc.
The script automatically returns the first 10 results which is the first page, to link to other pages:
http://www.yoursite.com/cgi- bin/amazon_products_feed.cgi?mode=books&node=5&page_num=2
    item - specific product(s) to display by ASIN (for books ASIN = ISBN)
    search_type - type of search
    ... for all values for search_type click here
To link to a specific product:
http://www.mrrat.com/cgi-bin/amazon_products_feed.cgi?item_id=0060523794&search_type=AsinSearch
    sort - changes the order of the results, by default the script displays by bestsellers
    ...for all values for sort click here
Let's say you want to change them to alphabetically:
http://www.mrrat.com/cgi-bin/amazon_products_feed.cgi?mode=books&node=5&sort=+titlerank

All available URL options are listed here.


Categories

Amazon Products feed uses categories to browse through Amazon.com's product database. You can only browse/search inside of a specified category. With Amazon Web Services, it's not currently possible to search all of Amazon's products.

To display a specific category of bestsellers:
node - this is the category number that you wish to display the bestsellers of.

For information on how to find category numbers that work with Web Services click here.

The node numbers that the script already knows and uses for browsing are listed here


Search Box

To add a search box to other pages of your site, simply cut-n-paste the code below:

<FORM Method="get" Action="/cgi-bin/amazon_products_feed.cgi">
    <INPUT Type="text" Name="input_string" Size="20">
    <SELECT Name="mode"><OPTION Value="baby">Baby
    <OPTION Value="books" Selected>Books
    <OPTION Value="photo">Camera & Photo
    <OPTION Value="classical">Classical Music
    <OPTION Value="videogames">Computer & Video Games
    <OPTION Value="pc_hardware">Computers
    <OPTION Value="dvd">DVD
    <OPTION Value="electronics">Electronics
    <OPTION Value="kitchen">Kitchen & Housewares
    <OPTION Value="magazines">Magazines
    <OPTION Value="garden">Outdoor Living
    <OPTION Value="music">Popular Music
    <OPTION Value="software">Software
    <OPTION Value="universal">Tools & Hardware
    <OPTION Value="toys">Toys & Games
    <OPTION Value="vhs">Video</SELECT>
<INPUT Style="background-color:#FFCC68;color:#000068;font-weight:bold" Type="submit" Value="Search">
</FORM>



Inserting Search Results Into Your Web Pages

You can insert search results into any of your web pages using a couple of ways. Search engines will even index these as part of your web page.


SSI Include

This stands for server-side includes, which means that when the page is requested by the users browser, your server combines this with the rest of the HTML. To do this, most hosting companies require that your pages have .shtml extensions. You can try to use these with .htm extensions to see if it will work, and some hosting companies let you specify .htm pages to utilize SSI Includes. But you need to contact your hosting for details on that.

To use an SSI Include, it's very simple, let's say you want to display the top selling video games, like here:

here's your URL:
http://www.yoursite.com/cgi-bin/amazon_products_feed.cgi?mode=videogames&node=471280

To include these results, remove the domain name from the URL and use this
<!--#include virtual="/cgi-bin/amazon_products_feed.cgi?mode=videogames&node=471280" -->

Now one roadblock to this, is it will display all of the content from your page template as well. So you should modify your page and products template to get the results you want. Basically a page template with just %%products_html%% will work, since you don't need the <HEAD><TITLE> elements. And maybe a simpler products template so it won't take up as much room.


PHP Include

You should only use a php inlcude if your pages are coded in php because they require the .php extension to run properly. If your pages are not php, use the SSI include above.

To do the same example as above with php use:
<?php
include_once("http://www.mrrat.com/cgi-bin/amazon_products_feed.cgi? mode=videogames&node=471280");
?>



APF Options

APF options were designed so you can customize your templates even further than standard HTML.
The options and the HTML they effect are enclosed in a special comment tag.
<!--apf &option1=value&option2=value! HTML here !-->

Notice the exclamation points, they separate the different parts of the command. <!--apf tells the script that options will follow. All options must be proceeded by an & to separate them and the last option is indicated by following it with an !. Anything following that ! through !--> is considered the HTML you want to control. If the option doesn't contain HTML, like for including a text file, the exclamation points still need to be there. The examples below will show how these options can be used.

    apf_start - product to start using the HTML at
    This is optional if it is not specified the HTML starts with the first product.
    apf_end - last product to use HTML at
    You can use the word last to specify the last product. And this option will always add the HTML to the end product, which is necessary to close off any open <TR>s.
    apf_repeat - how often to repeat the HTML
    If 1 use with every product, 2 every other product, 3 every third, etc.
    apf_include - include a text file or nav_menu. If you have HTML that you use on many pages (like the menu links at the bottom of all of my pages) you can use this option to include that file in the template. See example 3 below to better understand this feature. See Nav Menu to understand how to include the Navigation Menu

Example 1:
If you look at this page. The product tables have alternating colors. This isn't possible with standard HTML inside the templates, but it is with APF options. To alternate colors for every other table, use this in the top of your products template: This would replace the normal <TABLE> tags in your products template, after this you would use the <TD> tags and any other HTML that will be the same for every product.

the first <!--apf tag tells it to repeat this HTML for every other result (apf_repeat=2)
the second <!--apf tag tells it to start at the second result (apf_start=2) then repeat this for every other result (apf_repeat=2)
<!--apf &apf_repeat=2!
<TABLE Bgcolor="#CCFFFF" Border="6" Cellpadding="10" Width="100%"><TR>
!-->
<!--apf &apf_start=2&apf_repeat=2!
<TABLE Bgcolor="#FFFFFF" Border="6" Cellpadding="10" Width="100%"><TR>
!-->

So what you get as a result:
Product #1
Product#2
Product#3
Product#4

Example 2:
The next example will build your products into rows with 2 products on each row.

The first <!--apf tag starts the row (<TR>) and repeats it for every other product (apf_repeat=2)
The second <!--apf tag closes the row (</TR>) starting with the second product result (apf_start=2) repeats it for every other result (&apf_repeat=2) then finally adds the closing tag to the end of the results (apf_end=last).
Click here to see how these results look when finished

<!--apf &apf_repeat=2!
<TR>
!-->
<!--apf &apf_start=2&apf_end=last&apf_repeat=2!
</TR>
!-->

So as a result you get
Product #1 Product #2
Product #3 Product #4

Example 3:
APF can also be used to include a text file into a template, similar to how an SSI Include would work.
<!--apf &apf_include=../footer.html!!-->
This will look for a file called "footer.html" and plop it in the spot. If you use navigation or footers on your other pages and include them with SSI, you can use this to do the same in a template.


Navigatin Menu

If you look at this page, you may notice a navigation menu on the left of the products, this menu changes as you choose different categories. It will display the different sub-categories for whatever category you are in. You can change how this looks by modifying the nav_menu template. To use this in your page use the following tag in your page template above your %%products_html%% as in this sample page template. This utilizes the APF Options described above.

<!--apf &apf_include=nav_menu!
<TD Align="left" Valign="top" Width="160"><TABLE Bgcolor="#FFDC91" Width="100%"> %%nav_menu_html%%</TABLE></TD>
!-->

the Navigation menu uses the nav_menu template. To use one other than the default, upload it to your server and specify it in the script:
@nav_menu_templates = ("nav_menu_1.template", "nav_menu_2.template");


Change Languages

Languages work like the templates. Simple text files of all the variables that contain the text the script displays that does not come from Amazon. If you wish to create your own language file please use the sample English file as a starting point and be sure and send me a copy so we can share it with others. I would like to provide as many different languages as possible.

@language_templates should point to a file (or files) that contains the language you wish to display. If blank or non-existent will use embedded English. Language files:
@language_templates = ("apf_english.language", "apf_dutch.language");
English - example file

You specify which language to use in the URL with language.
http://www.mrrat.com/cgi-bin/amazon_products_feed.cgi?mode=books&language=1

If you have a file named apf_de.language in the same directory as the script it will automatically be loaded when you use locale=de to provide support for Amazon.de.

To display multiple languages in HTML there is a special charset (character set) called Unicode. This is the format that Amazon sends their results in and so it is what my script uses. To use accented characters in the language files you must use Unicode entities. Entities are just &#(a number);. I wrote a script to display the characters and show the entity for each so you can use them in your language file - Unicode Generator.




This documentation was provided by OneClickDesigns.com if there are any errors please contact us

[an error occurred while processing this directive]