Welcome to CG-Amazon (CGA for short)

A system for implementing an Amazon product library for your website. - Sidebar links to your favorite products - Sidebar links of your "Now Reading" or "Listening To" products - Sidebar links directly from your Amazon Wishlist - Sidebar links from keyword-based live lookups - Integrates with CG-Inline to provide in-post product links. - Integrates with CG-WhatTunes to provide the Album you are listening to.

Please read and understand the license terms before use.
We randomly assign the CHAITGEAR ID on 20% of generated links, to support development,
BUT EVEN SO we really need DONATIONS in order to support the CG Plugins!

PLEASE Help CHAITGEAR

If you find this code useful, please help out CHAITGEAR in return. Go to the How to Help CHAITGEAR page,
and donate money, time, or links back. Our 20% link-tagging doesn't generate nearly enough...

Thanks!

Note that while CGA was implemented around WordPress, I've abstracted all
key interface points so that it should be easy to implement for other web
solutions, so long as they are PHP-based. Feel free to contact me if
you'd like to discuss integration into other platforms.
UPDATE: CGA now ships with a two sample files for using it
with ANY php-based website. The sample file is non-wp-cga.example.php
which uses non-wp-cga-config.php for proper non-wp configs.

Also note that this is using the US interfaces at the moment. I've just
implemented basic locale support, though currently undoc'd, and I'd love to
have some people help me test it out further.

Finally, I should point out that I've gone to great lengths to try to ensure
this application in within the terms of the Amazon Web Services license, which
specifies restrictions on how long an application may use cached product data
before requiring a refresh, and how frequently an application should query
Amazon for data. I reserve the right to revoke your use of CG-Amazon if
you have modified the code such that it no longer follows AWS rules.

Let's get on with it!

Initial Installation
Adding Products to CGA
Display Products on Your Site
Configuration Options
For More Info

INITIAL INSTALLATION

Installation is a reasonably simple process, but there's a number of steps
to get it up and running. This assumes that you have a local directory
that you FTP up to a server -- i.e., you keep a local 'mirror' of your site
on your local machine. It also assumes that you've got the /plugins and
/plugins/cg-plugins additions in place already... ;)

Copy the files cgaindex.php and cg-amazon.css files from the {amazon-extra-stuff}
folder up to your WP root. cgaindex.php provides the 'Product Listing' page functions.
cg-amazon.css provides a STARTER SET of CSS styling of Amazon results -- PLEASE, feel free
to modify/extend for your site and theme as you wish! ;)

The folder cg-plugins/cache_amazon/ starts off empty. When uploaded to the server,
you should give it full read/write permission (666) to create and modify the
contents. You'll get errors otherwise.

This folder is where cached Amazon data is stored at the moment. I am working
on methods that will cache direct to the database, for users showing a more
fixed, small selection of items on a page, and not needing complex item data.

Pre-login to your wp if not already, so that following steps won't need
you to do that... ;) Then upload the extra CGA files to your server if you.
haven't already... ;)

Now, if all is working properly, you should have a "CGA" item in the
panel list. Click to select the CG-Amazon admin screen. You should get an error
notice of trying to access the (not yet created) table, and a button to create
the table. Click the button. That was easy! ;)

That created the new table, and should leave you in the CGA admin interface with
a message TABLE_CREATED at the top.

Initial setup of the system should now be complete.

ADDING PRODUCTS TO CGA

Next, you'll want to add some test items to your database. From the CGA panel
in the Admin interface, you'll see a new-entry block. Enter the amazon ASIN
for a product you want added. For people unfamiliar with ASINs, it is the
10-character string used to uniquely identify products on Amazon. It is
almost always in the URL of an actual product page when browsing Amazon.
For instance, take the URL:

http://www.amazon.com/exec/obidos/ASIN/0553564943/qid=1084230290/sr=2-1

You'll see the "/ASIN/" in the URL, followed by the 10-character string. In
this case, the product is a book, and Amazon seems to use the ISBN code as the
product's ASIN directly (0553564943). Most Asins seem to start with a 'B'.

On most product pages, either the ASIN will be listed for the product, or an
alternate format (ISBN) will be available. Books seems to have the ISBN code,
while most other areas (DVD, apparel, electronics, housewares, etc.) look to
have the ASIN on the page. Again, the ASIN will most typically be in the URL
as well, even if the word ASIN doesn't appear, like:

http://www.amazon.com/exec/obidos/tg/detail/-/B00006LS6M/qid=/br=1-6

Note the "/-/", followed by the 10-character ASIN code (B00006LS6M).

So, the best way to do this is to open a second browser/tab to Amazon, with your
first browser open to the CGA admin screen, find a product, switch over and add it
into the CGA list.

You will also see the Search For Items section, which lets you easily
browse for random items for your database. Enter text keywords in the
"Look for" box, and which 'Catalog' of Amazon to search for possible matches.
Note that special characters (quotes, hyphens, commas, periods, etc.) are ALL
stripped from the query before sending it to Amazon, so don't bother with them.
Click Find, and CG-Amazon will go and find the top ten matching items to your
search and display them. To return back from the results, just click the Cancel
button at the top of the panel. To add items to your database, click any of the
checkboxes next to items listed, then click the Add button at the top of the column,
and all the selected items will be added in one shot.

Newly entered items should always show up at the top of the list. If the item
didn't show up, either the ASIN was wrong, or there's a duplicate already in the
database. At some point I'll get around to telling users what the 'error' was.

When you add an item to the CGA list, a whole bunch of data is retrieve from
Amazon's database. Things like the product name, 'creator', URL, image URL,
comments, ranking, etc., all are retrieved and cached -- some are stored in
the database table itself, others are stored in a raw XML cache file in the
cache_amazon directory for faster retrieval of data for display in your
main website.

The two optional elements you can set are a categorization of your choosing
(you might group things by genre, or 'liked' and 'disliked', or whatever
makes it easier for you to later 'retrieve' items from a subset of the
list...). You don't have to choose a categorization -- you can leave it
blank ("0: None" in the dropdown list). If you've already added items with
categories to the table, the dropdown list will show the available ones.
If you want to add a new category, type it in the entry box below the
dropdown.

The second optional element is a 'meta note'. This is any text/html you
want displayed with the item. Default layout will show it after the item
in a sidebar/menu, or at the start of the item information when you go
to a per-item page in the cgaindex.php gallery listing code (cgaindex
is a gallery of your items -- if you don't want it accessible, it can be
deleted/renamed, and there's one option to turn off in the code... which
I'll detail at a later time).

After you have added an item to your database, you can remove it (without
a confirmation at the moment...) by clicking the X on the far right of the
Actions list, or you can update the timestamp to make it 'look more recent'
by clicking Time. Clicking the @ will refresh data from Amazon (not usually
needed...). Clicking Edit will let you change the Category you've tagged an
item with, or add Note annotations to an item.

DISPLAY PRODUCTS ON YOUR SITE

There are a number of ways to generate output, though I'll admit the
level of customizability isn't quite there yet. I'll detail the simple
interface(s) to display CGA data on your site.

To display a random product from CGA in your template, you need to add
something into say your menu structure. Taking the average WP 1.5 template
as a starting point, anywhere in the sidebar.php (if exists, else the
sidebar/menu area of index.php, etc.) you can add something like:


<li id="amazon-product"><?php _e('Amazon:'); ?>

<?php show_amazon_items(); ?>

</li>

Boy, that was pretty easy! ;) That function/tag is my newer simplified way
to display items from the database. When called without any parameters, it
defaults to showing ONE random item from the local CGA database of items.

THIS IS SOMEWHAT OUTDATED!!! TBD! MIGHT INCLUDE A MODDED SIDEBAR.PHP WITH CGPP! Let's look at some alternative ways to call show_amazon_items. It takes
the following parameters:


function show_amazon_items($count=1, $mode='rand', $image=true, $wpCat='', $amCat='', $show=true)

$count is how many items to display.

$mode is 'rand' for completely random, 'time' for latest additions.

$image is whether to show product pictures (false to turn off).
Pass $image as 'Medium' or 'Large' to get bigger images.

$wpCat is a string of one or more of the category names you came up with
when entering items. It could be something like 'Blues', or 'Blues,Jazz'
for multiple category lookups. If an empty string (''), it won't filter
based on your categories. Otherwise, it will restrict itself to random
or latest items within the given category.

$amCat is a string of the Amazon catalog name you want to pull from. At
the moment, this can only be ONE catalog and not a list of them (that may
be added in a future release). Something like "DVD" or "Music" or even
"Lawn & Patio". Use the EXACT strings listed in the CGA admin interface
in the AmazCat column.

NOTE that only one of $wpCat and $amCat can be set to a non-empty string
in a given call. If both are set, $wpCat is used and $amCat is ignored.

$show is whether to show/echo the results immediately, or not show them
and just return the HTML to output as a string.

Quick examples:

Show TWO random items:


<?php show_amazon_items(2); ?>

Show THREE most recently added/'touched' items, no images:


<?php show_amazon_items(3, 'time', false); ?>

Show TWO random things that are Amazon's DVD catalog:


<?php show_amazon_items(2, 'rand', true, '', 'DVD'); ?>

Now, using the ability in the Admin screen to 'categorize' the products
you've added locally, you can make a "now reading" list with ease! Just edit
the items you are reading and set the category to something like NowReading
(you'll need to type it in the very first use, but then further items you'll
see it in the dropdown list...).
Then, to show a random item that's on your NowReading list, do:


<?php show_amazon_items(3, 'rand', true, "NowReading"); ?>

New Function to show random items from a particular Wishlist.


function show_wishlist_items($listID='', $count=1, $image=true, $show=true)

Should be self explanatory, but this example shows THREE items, with no images,
assuming you've set $myAmazonWishlist in cga-config.php to your wishlist ID.
(Otherwise, put your wishlist ID between the empty ''...)


<?php show_wishlist_items('', 3, false); ?>

Also, somewhere in your page, you need to put a disclaimer if you are presenting
pricing information. We have an automatic function with an English string for people
who don't want to create their own:
<?php show_amazon_disclaimers(); ?>

MORE COMPLEX CASES

This section needs to be expanded further... ;)

For the moment, the following is a snippet of code that will print out related items to
the very last item that was output. Taken from cgaindex.php. It first tries
to generate accessories for the last item, and if there are none it tries to perform a
Similarity query for similar items at Amazon.

if ($lastAmazonASIN) // try similar search...
{
	$qresults = null;
	if ($lastAmazonAccessories && $wasReviewPost)
	{
		// we need to convert to asin array...
		$asinList = array();
		foreach($lastAmazonAccessories as $accessory)
			$asinList[] = $accessory['ASIN'];
		
		dbglog("Amazon block [Accessories]");
		if ($AmazonDebug>1) dbglog(serialize($asinList));
		$randAcc = 3; // so we don't exceed block limits...
		$maxAcc = 8; // for a LITTLE variety without re-caching...
		$qresults = query_amazon($asinList, '', true, $defaultAmazonImage, true, $randAcc, true, 'Asin', $maxAcc);
		if (!empty($qresults))
		{
			showed_amazon_product();
			start_block("Accessories", "picks-accessories");
				echo $qresults;
			end_block();
			$showedSomeProducts = true;
		}
	}

	if (empty($qresults))
	{
		dbg_log("Amazon block [Other Gear]");
		$randSimilar = 3; // so we don't exceed block limits...
		$maxSimilar = 8; // for a LITTLE variety without re-caching...
		$qresults = query_amazon($lastAmazonASIN, '', true, $defaultAmazonImage, true, $randSimilar, true, 'Similar', $maxSimilar, $lastAmazonCategory);
		if (!empty($qresults))
		{
			showed_amazon_product();
			start_block("Similar Gear", "picks-similar");
				echo $qresults;
			end_block();
			$showedSomeProducts = true;
		}
	}
	
	// if empty
	if ($lastAmazonAccessories && empty($qresults)) // okay, I give up, try accessories
	{
		dbg_log("Amazon block [Accessories]");
		$randAcc = 3; // so we don't exceed block limits...
		$maxAcc = 8; // for a LITTLE variety without re-caching...
		$qresults = query_amazon($lastAmazonAccessories, '', true, $defaultAmazonImage, true, $randAcc, true, 'Asin', $maxAcc);
		if (!empty($qresults))
		{
			showed_amazon_product();
			start_block("Accessories", "picks-accessories");
				echo $qresults;
			end_block();
			$showedSomeProducts = true;
		}
	}
}

CONFIGURATION OPTIONS

The file cga-config.php has a number of options that you can configure for how
product information is displayed/output. It has documentation on each option in the
file already, so I won't duplicate effort here (at least not for the moment...).

FOR MORE INFO

You can contact me at cgcode@chait.net.

And thanks for trying out CG-AMAZON!

- David Chait