Associate Engine : Format Templates  
Home > Associate Engine > Documentation > Format Templates

Format Templates

Browse Format Templates
   

Format Templates

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.

Format Templates vs. Page Templates

Associate Engine supports two types of templates: Format Templates (described below) and Page Templates.Format Templates control the micro "small picture". Page Templates control the macro "big 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.


TOP

Formatting Codes

Format templates let you specify the HTML you want to include for each product. And in that HTML you can refer to data fields from amazon.com's XML datafeed.

A Format Template file contains formatting codes that are a mixture of:

Associate Engine uses pre-defined formatting codes to format results. You can view the pre-defined formatting codes by opening the file ae-format/library.fmt using a text editor such as Notepad or Wordpad (Note: The format.library configuration variable sets the name of this file). You can override any of the pre-defined formatting codes or define your own. For example, the following table shows the format.list1.cell formatting code which is used to generate each product result in the default format:

<!--format.list1.cell--> 
<table width="100%" cellspacing=2 cellpadding=3 border=0>
  <tr><td colspan=4><hr noshade size=1></td></tr>
  <tr>
    <td align=right width=32 nowrap=nowrap><font face=Verdana><b>{details.ranking}.</b></font></td>
    <td align=center width=100 nowrap=nowrap>{format.image.thumb}</td>
    <td valign=top width="60%">
      <font face=Verdana size=-1><b><a href="{details.url}"{format.newWindow}>{details.ProductName}</a></b><br>
      {if details.artists.artist-1}by {details.artists.artist-1}<br>{endif}
      {if !details.artists.artist-1}{if details.manufacturer}from {details.manufacturer}<br>{endif}{endif}
      {if cfg.showprices}{if details.ourprice}Price: <font color="#990000">{details.ourprice}</font><br>{endif}{endif}
      {if cfg.showreviews}
        {if details.reviews.customerreview-1.comment}<br><b>Customer Review:</b>
          {if details.reviews.customerreview-1.rating.image}<nobr>{details.reviews.customerreview-1.rating.image}</nobr>
          {endif}
          <br>{details.reviews.customerreview-1.comment:300}
        {endif}
      {endif}
      </font>
    </td>
    <td valign=top width="25%"><p><font face=Verdana size=-1>
      {if details.reviews.AvgCustomerRating}Customer Rating:<br>{details.reviews.AvgCustomerRating} / 5.0<br>
          {details.reviews.AvgCustomerRating.image}<br><br>
      {endif}
      <a href="{details.url}"{format.newWindow}>Click here for more information</a></font></p>
      {if cfg.addto.buy}
        {details.addto.cart}
        {if cfg.amazonid.*}
          <p><font face=Verdana size=-2>Buy from:
          {if cfg.amazonid.ca}<a href="{details.url.ca}"{format.newWindow}>Canada</a>{endif}
          {if cfg.amazonid.de}<a href="{details.url.de}"{format.newWindow}>Germany</a>{endif}
          {if cfg.amazonid.fr}<a href="{details.url.fr}"{format.newWindow}>France</a>{endif}
          {if cfg.amazonid.jp}<a href="{details.url.jp}"{format.newWindow}>Japan</a>{endif}
          {if cfg.amazonid.uk}<a href="{details.url.uk}"{format.newWindow}><nobr>United Kingdom</nobr></a>{endif}
          </font></p>
        {endif}
      {endif}
    </td>
  </tr>
</table>

In the above formatting code, you can see HTML intermixed with substitution variables {VARIABLENAME} and "if" statements {IF CONDITION}...{ENDIF}. The above formatting code generates HTML for one product and looks something like the following example which was generated via:

<script src="/cgi-bin/ae.pl?type=best&mode=dvd&pagesize=1&script">



TOP

Formatting Library

The pre-defined formatting codes (referred to collectively as the "formatting library") that Associate Engine uses to format results can be overridden. The format.library configuration variable sets the name of the formatting library file. If this variable is set to "" then the formatting library built into the ae.pl file is used. See also: contents of ae-format/library.fmt file.

To override any or all of the formatting library, do the following steps:

  1. Make a copy of ae-format/library.fmt and copy it to ae-format/mylibrary.txt (you can use any filename you prefer; here, mylibrary is used merely to distinquish it from the original, and .txt is used so you can open it in a text editor such as Windows Notepad).

  2. Edit ae-ini.txt and set the format.library configuration variable to mylibrary (do not include the directory name or the filename ending).

    format.library "mylibrary"

  3. Edit the ae-format/mylibrary.txt file that you created in step 1 above.

    Optional: You can delete all the formatting codes that you did not modify since those formatting codes will be defined by the built-in formatting library. The advantage of doing this is that your changes will remain intact if in the future a new formatting library is released. Otherwise you would have to reapply your changes to the new formatting library.

  4. Upload the ae-format/mylibrary.txt file to your webserver in your ae-format directory.

For example, if you want the links in results to go to something like /cgi-bin/myclicktracker.pl?ASIN then modify the format.url formatting code from:

<!--format.url nocrlf removeQuotes-->
...formatting codes to generate URL...
<!--/format.url-->

to:

<!--format.url nocrlf removeQuotes-->
/cgi-bin/myclicktracker.pl?{details.asin}
<!--/format.url-->


TOP

Substitution Variables: {VARIABLENAME}

Just like a form letter in a word processor uses fields to indicate what values are to be substituted in (such as: Dear <<NAME>>), formatting codes use substitution variables {VARIABLENAME} to indicate what values are to be substituted in.

There are quite a few substitution variables available for use. To make it easier to refer to them all, they are organized into four groups as outlined in the following table. The first part of the variable name indicates what group the substitution variable is in. For example {details.ourprice} is the "Our Price" field of a product's details.

Variable Meaning
{cfg.VARIABLENAME}

Configuration variables. For example, {cfg.showReviews} is the value of the showReviews configuration variable set in the ae-ini.txt configuration file.
{details.FIELDNAME}

Product details. For example, {details.ProductName} is the product's name.
{format.FORMATNAME}

Other formatting codes. Formatting codes can be used like a macro. For example, {format.image.thumb} is pre-defined to be a block of formatting codes that expands to be a linked <IMG> tag with the image's SRC set as the product's thumbnail image.
{form.PARAMETERNAME}

Script parameters (either passed in a URL or as part of a submitted form). For example, {form.type} is the value of the "type" script parameter.
{VARIABLENAME}

Some non-product related Page Template substitution variables are also available for use in Format Templates. Such as, "{amazonID}" for your amazon.com associate ID. See Page Template Substitution Variables.


{cfg.VARIABLENAME}

To see what {cfg.VARIABLENAME} substitution variables are available, view your ae-ini.txt configuration file and see the Configuration Variables page.

{details.FIELDNAME}

To see what {details.FIELDNAME} substitution variables are available, add the "data" script parameter to any Associate Engine URL, such as: https://www.c3scripts.com/cgi-bin/ae.pl?type=best&mode=dvd&data or https://www.c3scripts.com/amazon/type_best/mode_dvd/data

If you scroll that page down, you should see something like:

<OurPrice>$51.99</OurPrice>

Thus {details.ourprice} would reference this <OurPrice> field. Uppercase/lowercase in the field name does not matter so {details.OurPrice} is the same as {details.ourprice}

Note: Some fields are present in the XML datafeed only for certain types of products. For example, {details.isbn} only shows up for books (it is the book's ISBN #). To test if a field is present, use an "if/endif" statement, such as:

{if details.isbn}ISBN: {details.isbn}{endif}
{if !details.isbn}ISBN: N/A{endif}

If you understand XML, see amazon.com's XML schema document at http://xml.amazon.com/schemas3/dev-heavy.xsd

{format.FORMATNAME}

To see what {format.FORMATNAME} substitution variables are available, open the file ae-format/library.fmt using a text editor such as Notepad or Wordpad. Note: The format.library configuration variable sets the name of this file.

{form.PARAMETERNAME}

To see what {form.PARAMETERNAME} substitution variables are available, see the Script Parameters page. Basically, any parameter you specify as part of the Associate Engine URL is available as {form.PARAMETERNAME}


TOP

"if/endif" Statements: {if CONDITION}...{endif}

Blocks of HTML can be included/excluded by using "if/endif" statements. For example, the following formatting codes could be used to display a product's ISBN # if the product has an ISBN # , otherwise "N/A" is shown:

{if details.isbn}ISBN: {details.isbn}{endif}
{if !details.isbn}ISBN: N/A{endif}

As an other example of "if/endif", you could add the following lines to your format template to display a "Listen to samples" link for music products. The link goes to amazon.com's "Listen to samples" page that lists the tracks of the specified product with "listen" links.

<!--if details.tracks.track-1-->
<A HREF="http://www.amazon.com/exec/obidos/redirect?tag={amazonid}&path=tg/detail/-/{details.asin}%3Fvi%3Dsamples" >Listen to samples</A>
<!--endif-->

Note: In the above HTML, the HREF value may appear on your screen as two separate lines because it is so long. Type it in as one line without carriage returns.

For more information on "if/endif" statements, see the Introduction to "if/endif" statements.


TOP

Sample Format Templates

Several sample Format Templates are included with the Associate Engine script as indicated in the following table. Some of the Format Templates are designed to display a list or grid of products, while other Format Templates are designed to display a single product's details.

The following Format Templates are located in the ae-format directory.

Filename Designed For Layout
c3.fmt Grid

Displays results in a 3-column grid. Note: This is not the same as using the grid parameter. This layout is similar to what the amazon.com website uses to show products in a 4-column grid. E.g.: Compare browse node 594696 at amazon.com with Associate Engine results.
c4.fmt Grid

Displays results in a 4-column grid. Note: This is not the same as using the grid parameter. This layout is similar to what the amazon.com website uses to show products in a 4-column grid. E.g.: Compare browse node 594696 at amazon.com with Associate Engine results.
column.html Column Displays results in a 1-column grid suitable for use in a sidebar column. This format template is used by the "store" Page Templates to show the "Top Selling" column in the left margin. E.g.: See "Top Selling Toys" column at this "Harry Potter" LEGO page.
details.html
details1.html
details2.html
details3.html
details4.html
details5.html
details6.html
details7.html		 Details

Displays results with extensive product details. These Format Templates format the product details in a layout that is best suited for showing a single product (e.g.: product details page).

See the Sample "Details" Format Templates page for examples.
library.fmt List / Grid

This file contains the pre-defined formatting codes. It defines the default list format as well as the formatting codes used by the grid parameter.
list1.html
list2.html
list3.html
list4.html
list5.html
list6.html
list7.html
list8.html		 List

Displays results as a summary of product details. These Format Templates format the product details in a layout that is best suited for showing several products in a sequence (e.g.: search results).

See the Sample "List" Format Templates page for examples.
listol.html Numbered list

Displays results in a numbered list (using <OL> HTML tag). E.g.: 100 Top selling Harry Potter books.
listul.html Bullet list

Displays results in a bullet list (using <UL> HTML tag). E.g.: 100 Top selling Harry Potter books.

Note: There is no technical difference between "List" and "Details" format templates. The "List" Format Templates layout product details in a format that is best suited for showing several products in a sequence (e.g.: search results). The "Details" Format Templates layout the product details in a format that is best suited for showing a single product (e.g.: product details page).


TOP

Format Template File Structure

Open any of the ae-format/*.html files, such as the ae-format/details.html file, in your HTML editor (or a text editor such as Windows Notepad) and you'll see that various portions of the HTML have matching open/close format tags such as:

<!--format.cell-->
...some HTML to show the products details...
<!--/format.cell-->

This defines the format.cell formatting code to be whatever text/HTML is between the open/close format tags. The open/close format tags are really just HTML comments.

Anything in details.html that is not between a pair of matching open/close format tags is ignored.

The details.html file also contains definitions for some other formatting codes used to format the results:

<!--format.header--> ... <!--/format.header-->
<!--format.footer--> ... <!--/format.footer-->
<!--format.moreInfo--> ... <!--/format.moreInfo-->
<!--format.noResults--> ... <!--/format.noResults-->


TOP

Format Template Filenames

Format Templates are located in the ae-format directory.

Formatting files can have .html or .htm or .fmt (short for "format") or .txt filename endings; the ending does not matter. When using the format parameter to specify what Format Template to use, do not include the filename ending, such as: format=list1

The .html files in ae-format directory can be opened in HTML editors, whereas the .fmt files typically cannot because the HTML editor might complain that they are not "valid" HTML (because of the way formatting codes are defined) -- open those in Windows Notepad instead.


TOP




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