NAME

    Business::Associates - a library to handle the new XML interface for the
    Amazon.com Associates program.

SUMMARY

    This package replaces the Amazon Recommends (tm) links to provide a
    powerful and simple to use interface that allows you to embed complex,
    highly targeted ads on your web site (or other documents).

    This modules supports many new features that are not available with the
    standard interfaces. For example, multi-mode searches, i.e. the ability
    to search across multiple product categories (dvd+video+music+...) is
    fully supported.

    See also http://cybaea.com/Associates.html for more information and
    example screen shots.

    Currently, only the Amazon.com Associates program is supported.

OVERVIEW OF DOCUMENTATION

    The good news is that if you are new to this library, then you are
    reading the right document. Carry on!

    This document tells you everything you need to know to get started with
    the package. It takes you through including complex ads on your web site
    so you can start making money now.

    The Associates package uses a three-stage working model:

    1.  Retrieve data from the Associates program's XML interface. In the
        case of Amazon's program, that involves a HTTP request to the
        `rcm.amazon.com' server.

    2.  Transform the data into the desired output format. This is done
        using a technology known as XSLT and, in the examples included in
        this distribution, it converts the XML from the server into HTML
        that we can display as part of our web site.

    3.  Format the data visually. For the HTML output that we generate here,
        we use Cascading Style Sheets (CSS) which is the standard way to
        specify the formatting of a web site.

    This document, the Business::Associates manpage, provides an
    installation and quick-start guide, as well as an overview of the entire
    package. Read this first.

    The three stages are documented in three different overview documents:

    1.  Data retrieval is documented in the Business::Associates manpage
        (this document).

    2.  Data transformation is documented in detail in the
        Business::Associates::Stylesheet manpage.

    3.  Visual formatting is documented in detail in the
        Business::Associates::Formatting manpage.

    Additionally, for detailed programmer's references, see the
    Business::Associates::Data manpage, the Business::Associates::XML
    manpage, the Business::Associates::Cache manpage, the
    Business::Associates::Communication manpage, and the
    Business::Associates::Imgsize manpage. The order suggested here will
    minimize forward references, but I strongly suggest that you read the
    three documents above first.

INSTALLATION

    If you are reading this, then chances are that you have already
    installed the package. But here are the instructions again:

    Download the latest version of the package from
    http://cybaea.com/Associates.html. It will be in the form of a
    compressed archive with the name Business-Associates-x.yy.tar.gz where
    *x.yy* is the version number (e.g. 1.00). Unpack this archive and go to
    the newly created directory. On a Unix-like system, you would do

        $ gunzip -c Business-Associates-x.yy.tar.gz | tar xvf -
        $ cd Business-Associates-x.yy

    Then build and install the package in the usual perl way. Note that to
    install you probably have to be `root'.

        $ perl Makefile.PL
        $ make
        $ make test
        % make install

    For more information on this process, including how to install without
    being the superuser, see the ExtUtils::MakeMaker manpage.

  Copy demo files

    This is an optional step, but you will probably want to copy the files
    from the demo/ sub-directory: demo/Associates.css and
    demo/associates.shtml normally go to the document root of your web
    server, while demo/a.pl goes to your `cgi-bin' directory. For my server
    (Red Hat Linux), I do:

        $ cp demo/Associates.css demo/associates.shtml /var/www/html/
        $ cp demo/a.pl /var/www/cgi-bin/

    Your directories may vary. You should edit the a.pl file to include your
    Amazon.com Associates Id (instead of the default, which is mine). Find
    the line

        $Business::Associates::Data::Associates_Id = "allanengelhardt";

    and change `allanengelhardt' to your id.

    You'll probably want to incorporate (some form of) the cascading style
    sheet in your main style sheet. You can do this easily by adding

        @import url("/Associates.css");

    near the top of your style sheet (before any instructions).

    If your web server is already configured for server-side includes, and
    it is running, then you should now be able to do

        $ mozilla http://localhost/associates.shtml

    to see the results (requires an active internet connection). Substitute
    your web browser for `mozilla' above.

  Images

    The default scripts and style sheets provided with this package
    references a number of images from Amazon that are not provided in this
    download. You'll need an Amazon.com Associates account to download them
    from

     https://ssl-images.amazon.com/images/G/01/associates/logos2000/a150X75w.gif
     https://ssl-images.amazon.com/images/G/01/associates/logos2000/126X32-w-logo.gif
     https://ssl-images.amazon.com/images/G/01/associates/photo2000/cp_pic_88x31.gif

    The samples expect to find them in the amazon sub-directory from the web
    server's document root (typically something like /var/www/html/amazon/.

    See README.XSLT-STYLESHEETS for more information.

  Server Side Includes

    If your Apache server is not already configured for server-side
    includes, then enable it in httpd.conf by finding and un-commenting the
    lines

        #
        # To use server-parsed HTML files
        #
        AddType text/html .shtml
        AddHandler server-parsed .shtml

    See your Apache manual for details.

    For other web servers, please consult the manual.

  No Server Side Includes !?

    If your server is not configured for server-side includes, then you
    should still be able to test the package with a command like

        $ mozilla http://localhost/cgi-bin/a.pl?keywords=make+money+now

    though your browser may display the HTML source rather than rendering
    it. (Try saving as an .html file and then loading that, if this is the
    case.)

QUICK START

    Please read the the section on "INSTALLATION" first.

    I assume that you already have an Amazon Associates account. The Amazon
    Associates program provides for individual web sites to sell books and
    other items to their visitors through Amazon.com while earning a small
    commission, at the time of writing usually 5%. For more information
    please see http://associates.amazon.com/.

    The sections below cover HTML, CGI, and mod_perl interfaces to this
    package.

  Quick Start: HTML

    All that is needed to start using this package is *a single line* in
    your HTML page. If you are using Apache with server-side includes then
    that line could be as simple as:

     <!--#include virtual="/cgi-bin/p.pl?keywords=xml&width=3" -->

    This makes a simple banner three items wide with a logo (Amazon's or
    your own - it's your choice) to the left of the items. It does a keyword
    search for books (the default) on the string "xml" and displays the top
    three Amazon best sellers.

  Quick Start: CGI

    Below, we present a complete CGI program that uses this package. Apart
    from declarations, it is *only four lines long*.

        #!/usr/local/bin/perl -Tw

        use Business::Associates::Data();
        use Business::Associates::XML();
        $Business::Associates::Data::Associates_Id = "'allanengelhardt'";
    
        my %args = (
           associates_id => $Business::Associates::Data::Associates_Id,
           disable_img_size => "true()"
                    );
    
        my $what = "xml";               # Search string
        my $mode = "books";             # Product category
        my $ss_name = "Associates";
        my $type = "keywords";          # Or: browse
    
        my $data = Business::Associates::Data->$type ($what, $mode);
        my $xml  = new Business::Associates::XML ($data)
                   if defined $data->xml();
    
        my $s    = $xml->transform($ss_name, %args) if defined $xml;
        print "\n\n$s\n"                            if defined $s;

    You should change the value of *Associates_Id* from `allanengelhardt' to
    your own Amazon.com Associates Id. Note the extra quotes in that string.

    For the moment, treat *%args* as a magic argument. The *$what* variable
    is the search string for keyword searches, and you should separate
    keywords with the `+' character (e.g. `$what = "make+money+fast"'. If
    *$type* is `"browse"', then *$what* is the browse category (e.g.
    `"301668"' for popular music).

    Normally, you'd get these arguments from the CGI parameters, see
    demo/a.pl for an example of this, and see also the CGI manpage.

    See also demo/a.pl for an example that supports searches across multiple
    product categories.

    See the section on "CGI SCRIPT" for more details on options to the a.pl
    script.

  Quick Start: mod_perl

    The module is easy to use from any perl program and provides maximum
    performance from mod_perl (see next section). See the previous section
    for an example, and the individual package documentations for the
    complete API.

BACKGROUND

    The Amazon Associates program provides for individual web sites to sell
    books and other items to their visitors through Amazon.com while earning
    a small commission, at the time of writing usually 5%. For more
    information please see http://associates.amazon.com/.

    The Associates web site provides many tools for building links to
    products on Amazon.com, but in early 2002 a completely new interface was
    developed to allow web sites full control to build their links as they
    wanted.

    This new interface returns structured data about best selling items at
    Amazon. It is currently possible to retrieve this data for any of
    Amazon's product lines, including books, magazines, DVDs, etc. The data
    can be specified by keyword search (e.g. "garden+furniture") or by
    browse category, which is a classification of Amazon's items (e.g. `All
    Products / Camera & Photo / Brands / Canon / Film Cameras / SLR
    Cameras') that provide fine-grained control over the items returned.

    This structured data is provided as XML, which is a popular way to
    encode both data and the information about data. For more information on
    XML you can look at http://www.xml.org/ and http://www.xml.com/ for
    tutorials, tips, and further links. XML is an official standard of the
    World Wide Web consortium who you can find at http://www.w3.org/.

    Even though there are many and excellent tools for manipulating XML it
    can be a bit daunting. This package brings together all the tools for
    building efficient ads on your web site.

    Some of the benefits and design goals of this package are outlined in
    the subsections below.

  Performace

    On my middle-of-the-road Pentium machine running Linux, the conversion
    of the raw Amazon XML to the formatted HTML banner (about 3k of HTML)
    takes about 7 milliseconds. Conversion of the same XML to another HTML
    format (e.g. to sort by author or price instead of the default sales
    rank) takes only about 5 milliseconds. The parsed style sheets are
    cached in memory, saving 2 milliseconds on all but the very first call.

    To get anywhere near this performance you need to use mod_perl or some
    similar technique that avoids the overhead of creating a new process.

    The included CGI script run in just under 300 ms on my machine when
    retrieving the data from disk. A very large part of this is the overhead
    of starting a new process and loading perl: the core processing is less
    than 30 ms.

  Efficiency

    For efficiency and to reduce network load, this package automatically
    caches the results from Amazon for 24 hours. Next time your web server
    needs the results for a given keyword combination of browse category it
    is retrieved from your disk, not from the network. This greatly improves
    the performance of your system.

    Amazon only updates the bestseller list every 24 hours, so you are not
    loosing information by this.

    The caching is also a condition for using the Amazon XML interface.

  Separation of Code, Data, and Presentation

    The design of this package separates code, data, and presentation to
    simplify maintenance of complex web sites.

    The code is written in pure perl, and should run on practically any
    machine regardless of architecture. It is responsible for the result
    caching and network communication, and for orchestrating the whole
    effort.

    Data transformation is done using XSLT which is a standard for
    transforming XML. This is a very powerful transformation language with
    excellent support of development tools. This package includes a powerful
    default transformation as well ans several well-documented examples on
    how to extend or modify this.

    The presentation is managed using standard cascading style sheets. All
    HTML (or xhtml) elements are clearly and uniquely identified , allowing
    precise control over the look of the finished result. It is possible to
    have different visual formatting for different result categories (e.g.
    Books can look different from Electronics).

  Portable

    The package is developed in perl, and should work on any platform with a
    functioning perl installation.

    The package uses libxml2 and libxslt, two excellent libraries from the
    Gnome project (http://www.gnome.org). These are pure C libraries and
    should provide maximum portability (and performance, see the Performance
    entry elsewhere in this document).

DESCRIPTION

    This package offers the ability to create ads and other information in
    conjunction with an Associates program.

    An *Associates program* is a service provided by an online retailer
    whereby affiliates are rewarded for referrals to the retailer.
    Typically, the reward is a percentage of the sales price. The best known
    of these programs, and the only one currently supported by this package,
    is the Amazon.com Associates program. For more information, and to sign
    up, please visit http://associates.amazon.com/.

    This package works with an Associates program that provide an XML
    interface to their search engines. In the example of the Amazon.com
    interface, it is possible to obtain their bestseller lists for any
    category of product (books, DVDs, software...) for specific keywords
    (e.g. Jennifer+Lopez) or for a specific "browse category" (e.g. Canon
    brand 35mm SLR film cameras).

    XML is a standard way of encoding data and information about the data
    (e.g. "this is a title", "this is a price"...) that is very popular and
    has good tool support. However, XML is not usually intended to be viewed
    directly by the end-user, instead it is an intermediate format that
    should be converted, for example to HTML.

    The Associates package uses a three-stage processing model:

    1.  Data retrieval. The raw XML data is retrieved from the Associates
        program's XML server, using keywords or browse categories. For
        efficiency, the XML data is cached locally, reducing the network
        load of your web server.

    2.  Data transformation. The raw XML data is then transformed to the
        target data format, usually HTML which allows your web server to
        display banner ads and the like.

    3.  Visual formatting. The transformed data needs to be formatted
        visually. This includes setting font sizes, deciding on image
        displays, etc.

    These are separate stages to support separation of code and data, to
    allow maximum scalability of your web site, and to allow for other
    formats (e.g. different ads for WAP or iMode devices).

  CGI SCRIPT

    The provided CGI script, a.pl, is, with server-side includes, the
    easiest way to get started with this package. The script accepts a
    number of arguments. Many of them are shown in the associates.shtml file
    in the demo/ sub-directory, and in the following we briefly summarize
    the main options.

    *type* [Default: keywords]
      Must be one of "browse" or "keywords" for browse category or keyword
      searches, respectively. Defaults to "keywords".

      Examples:

       <!--#include 
           virtual="/cgi-bin/a.pl?type=keywords&keywords=canon+slr&mode=photo" -->

       <!--#include
           virtual="/cgi-bin/a.pl?type=browse&keywords=163306&mode=dvd" -->

    *keywords* [Required]
    *browse* [Required]
      This is a string that indicates the keywords (for keyword searches) or
      the browse category (for browse searches) for which the bestseller
      list should be retrieved. The two forms, *keywords* and *browse* are
      synonyms. This is the only required argument. Separate multiple
      arguments with a `+', and be sure to encode any arguments that are not
      valid in a URL with the `%xx' notation (see also the URI::Escape
      manpage or the Apache::Util manpage).

      Examples

       <!--#include 
           virtual="/cgi-bin/a.pl?keywords=xml+xslt&mode=books" -->

      Keyword search for books on XML and XSLT.

       <!--#include
           virtual="/cgi-bin/a.pl?type=browse&browse=163306&mode=dvd" -->

      Browse category search.

    *mode* [Default: books+music+dvd]
      The so-called *mode* or product category to search. Separate
      categories with a `+' sign.

      Valid modes for the Amazon.com Associates program includes: `books
      magazines music classical-music vhs dvd toys baby videogames
      electronics software universal garden kitchen photo pc-hardware'.

      Note that multi-mode searches can take some time when the data is not
      cached.

    *width* [Default: '3']
      The output of the default data transformation style sheets is a box of
      items. This parameter specifies the width of that box, in number of
      items. See also *height* below.

    *height* [Default: '1']
      The output of the default data transformation style sheets is a box of
      items. This parameter specifies the height of that box, in number of
      items. See also *width* above.

      Example:

        <!--#include
            virtual="/cgi-bin/a.pl?keywords=xml&width='3'&height='1'" -->

      The quotes are optional, but recommended (the parameters are
      technically XPath specifications).

    *ss* [Default: Associates.xslt]
      Specifies the style sheet that is responsible for the data
      transformation stage of the processing. For example, to sort items by
      artist (instead of the default sales rank), use

       <!--#include virtual="/cgi-bin/a.pl?keywords=adams+douglas&ss=AssociatesArtist&width=5&height=3&images='none'" -->

    *images* [Default: 'auto']
      The Associates package has the ability to display images on any of the
      four sides of the advertisement. Use any combination of `'auto'',
      `'top'', `'left'', `'right'', and `'bottom'' separated by spaces, or
      `'none''. The value `'auto'' puts an image on the top if `width <=
      height' and on the left if `width > height'.

       <!--#include virtual="/cgi-bin/a.pl?keywords=apache+web+server&img_src_top='/amazon/126X32-w-logo.gif'&images='bottom'" -->

      Note the extra quotes (this is an XPath parameter).

    *img_src_(top|left|right|bottom)*
      This is the source (`SRC' attribute of the HTML `IMG' tag) of the
      images (see *images* above). The default is `'/amazon/a150X75w.gif''.
      Note the extra quotes. See example in the previous item.

    *class* [Default: 'A_catalog']
      The default transformation style sheets produces a HTML `table'
      containing the ad. This specifies the `class' attribute of the `table'
      entity. See also the Associates::Formatting manpage.

       <!--#include virtual="/cgi-bin/a.pl?class='right_float'&keywords=apache+web+server&mode=books&ss=Associates&width=1&height=1&img_src_top='/amazon/126X32-w-logo.gif'&images='bottom'" -->

    *coversize* [Default: 'T']
      Specifies the size of the image used for the cover. Valid values
      include 'T', 'M', and 'L' for thumbnails, medium, and large images,
      respectively. Note the extra quotes.

TO DO

    Upload to CPAN.

    More XSLT examples.

    More tests in the install scripts.

SEE ALSO

    Data transformation is documented in detail in the
    Business::Associates::Stylesheet manpage.

    Visual formatting is documented in detail in the
    Business::Associates::Formatting manpage.

    Additionally, for detailed programmer's references, see the
    Business::Associates::Data manpage, the Business::Associates::XML
    manpage, the Business::Associates::Cache manpage, the
    Business::Associates::Communication manpage, and the
    Business::Associates::Imgsize manpage. The order suggested here will
    minimize forward references.

    See also the CPAN manpage, http://www.perl.com/CPAN, the httpd manpage,
    http://www.apache.org/, the XML::LibXML manpage, the XML::LibXSLT
    manpage, the libxml manpage, http://www.gnome.org/, the Cache::Cache
    manpage, the File::Spec manpage, the HTTP::Request manpage, the
    LWP::UserAgent manpage

TRADEMARKS

    Amazon, Amazon.com, and other names used in this document may be the
    registered trademark of Amazon in the United States of America and other
    jurisdictions. Please see http://www.amazon.com/ for more information.

    Other names may be trademarks of their respective owners.

AUTHOR

    This package was written by Allan Engelhardt <allane@cybaea.com>

COPYING

    Copyright (c) 2002 Allan Engelhardt <allane@cybaea.com>

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

