Name	Amazon Web Services Plugin
Vendor	Bobsgear Project (Website)
Authors	Garnet R. Chaney
Homepage	http://www.bobsgear.com/display/bobsgear/Amazon+Web+Services+Plugin
Issue Tracking	http://developer.atlassian.com/jira/AWS
Categories	Affiliate program, content macro
Version	1.1.0
Availability	Confluence v2.2.9 to v2.5.2
State	Stable
License	Open Source (BSD)
Price	Free Postcard-ware
Release Docs	http://www.bobsgear.com/display/bobsgear/Amazon+Web+Services+Plugin
Java API Docs	n/a
Download Source	com.bobsgear.amazon.1.1.0.zip
Download JAR	http://plugins.bobsgear.com/plugins-lib/plugins-com.bobsgear.amazon.1.1.0.jar

Description/Features

Make money from Amazon while embedding colorful product pictures within your wiki pages by creating simple links to Amazon books, items, product searches, and wishlists.

Amazon product pictures are a free way to add some spice and pizzazz to your website,
and they help you make money at the same time.

This Confluence plugin was written as my entry into Atlassian's 2007 Codegeist contest. I think every Confluence wiki should run this plugin, because it has features that are of benefit to every wiki:

• It makes it easy to link to products, pictures and descriptions, relevant to your content
• The source code serves as a great example of how to write a plugin
• Product pictures are a free bandwidth way to add color to your wiki pages
• It will help you make money with your website
• It generates content in a way that should help you grow your wiki web traffic

It's free and open source. If you are interested in learning to write plugins, I hope it will serve as a good example of how to accomplish some tricky things, like making your own system level administration configuration pages, storing your configuration information in the database, properly setting what the breadcrumbs bar shows, and how to grab the title of the page that the macro is being renderd from.

It will also help you make some money from your wiki. I've spent years researching the use of wikis to generate organic search traffic, as well as how to turn those visitors into easy money with Amazon and other affiliate programs.

Every website owner, even if not focused on making money, would like to have more visitors. The output of these macros is designed to help your wiki generate more organic (free) search engine traffic. It's well known that search engines such as Google like quality content, and their algorithms also like to see that your web pages change regularly. So if you use these macros to display relevant products in combination with your own quality content, you should be well on your way to increasing the visitors to your wiki!

Free Postcard-ware

After you've tried this plugin, please send me an email, or a postcard, to let me know what you think of it. This will also help me keep in touch with you about enhancements, and consider including your ideas in the next version. I love to tinker with the code that runs my wiki as much as developing the wiki content, so expect to see more great features included in this plugin.

Setup

Download and install this macro using the plugins screen of the System Administration.

After the macro is installed, it adds a System Configuration option, "Amazon Key". Click on this link to go to the configuration screen to configure the plugin for your own Amazon developers key.

If you don't need the money from this plugin...

Of course, you could also support my development of this plugin by leaving this key field blank, in which case my key will be used to generate the content for your site, and I'll receive a few more commissions from Amazon. Unlike some free AWS solutions that force their own key onto your pages for 20% of your website's Amazon requests, my plugin does not do that. Your level of support is totally up to you.

Usage

This plugin includes three macros:

• {asin} for linking to books and items
• {amazonsearch} for showing the results of an Amazon product search.
• {amazonwishlist} for showing the items on an Amazon wishlist

It requires you to get an Amazon Developers Key. A system administration page is provided in the "Configuration" section to set the "Amazon Key". See the section on Setup for more information.

Important note about server load These macros request live product information from the Amazon Web Services database. Each product you display on your page causes a call to the Amazon Web Services API. An amazon search may cause several calls to Amazon's servers, once for the search, and once for every product shown in the results. All of the information has to be returned before your wiki page can be displayed. Including several product pictures on a page is not a problem, and even including one or two amazon searches or wishlists on a page shouldn't cause much delay. But you probably don't want to list more than a couple dozen products on a single page. If you use these macros like spice, and not the main meal, your content will taste good to users and search engines alike.

Examples

asin - Linking to an item

asin - Simple product links

• {asin:1861262337} - Link to a book with a 10 digit ISBN number
• {asin:9780470100875} - Link to a book with a 13 digit ISBN number
• {asin:B0001F2MUK} - Link to an Amazon item

{asin:1861262337}	{asin:9780470100875}	{asin:B0001F2MUK}
Mechanical and Quartz Watch Repair Mick Watters $45.00(USD) Mechanical and Quartz Watch Repair is targeted primarily at those who want to learn about watch repair, and features movements that are representative of those found in other watches. The easy to follow instructions are appropriate to both professional repairers and enthusiasts. Material covered includes the working environment, overhauling basic mechanical watches, automatics, stop watches, chronographs, some restoration, and basic quartz watches—both analog and liquid crystal display.	Make Money Teaching Online: How to Land Your First Academic Job, Build Credibility, and Earn a Six-Figure Salary Danielle Babb $24.95(USD) Did you know you could teach from home and earn a six-figure salary? Thousands of people make a great living teaching online courses from home, and the more classes they teach the more they earn! If you want into this exciting profession, this guide will show you how to get started, find great jobs, and earn more than you thought possible.	asin: null

I like to use these macros with the section and column macros to make a short list of recommended products on the right like this: {section} {column} some text goes here. Some more text goes her. {column} {column:width=150} Two or three recommended books: * {asin:1861262337} - Link to a book with a 10 digit ISBN number * {asin:9780470100875} - Link to a book with a 13 digit ISBN number * {asin:B0001F2MUK} - Link to an Amazon item {column} {section}

asin - Advanced functionality

The asin macro also supports more advanced functions:

Seeing the raw Amazon XML

• {asin:xmlinfo|1861262337} - Show the XML response from Amazon. Useful for debugging.
  

• {asin:searchdebug|index|search terms} - Shows raw information received from Amazon
  

Using asin to do searches and wishlists

• {asin:search|index|keywords} - Same as {amazonsearch:index|keywords}
  • Keywords can also be
    • ~title - Use the title of the current page as the search argument
    • ~randomfromtitle - Use several random words from the current page title
• {asin:wishlist|wishlistid}

To overload, or to makes extra macros?

I first developed all these extra functions within the original {asin} macro, and I have several hundred wiki pages that depend on these overloaded uses of the asin macro. Later I move these to their own classes so I could add each function as the separate macros that follow. The source code for each of these macros is now derived from my own base class that incorporates a lot of functionality common to all of them.

amazonsearch - Showing results of a search

{amazonsearch:index|keywords}
where,

• index is any of Books, All (Or other Amazon index)
• keywords is one or more space separated words. Or keywords can be either of:

Find books about Java:
{amazonsearch:Books|Java}

Amazon uses the following search indices to divide up all of the items for sale:

Note: These are case sensitive, although the plugin will capitalize the first letter if you forget.

You can also search from these blended indexes:

• All—Searches through all search indices. Only five pages of items can be returned where each page contains up to five items.
• Blended—Combines the following search indices: DVD, Electronics, Toys, [VideoGames], PCHardware, Tools, [SportingGoods], Books, Software, Music, [GourmetFood], Kitchen, and Apparel search indices
• Music—Combines Classical, [DigitalMusic], and [MusicTracks] search indices
• Video—Combines DVD and VHS search indices

  NOTE: This is index not yet supported:

• Merchants—Returns the items across all search indices for a merchant who is specified by a value for [MerchantId]. |

These search index combinations are helpful when you are not sure which search index to specify. The downside of using one of these combined search indices is that they might return quite a few items in the response. - Source

Advanced searches related to the title of your page

If you want to paste a product search macro onto many pages, and have them all show relevant product results, you could custom taylor each macro's search string for best results.

However, if you are lazy like me, and you're faced with 300 new wiki pages that you need some quick place holder content for, you can use either of these keywords to quickly generate relevant product results:

• ~title - Use the title of the current page as the search argument
• ~randomfromtitle - Use several random words from the current page title

For ths page, {amazonsearch:books|~title} would be the same as typing {amazonsearch:books|Amzon Web Services Plugin}

Since a search for that specific title isn't likely to find a lot of books, you might also try
{amazonsearch:books|~randomfromtitle}. With this, each time your wiki page is read, a new selection of products for a random subset of words from your page title is returned. For this page it could be strings like "Amazon Services" or "Web Services" or "Web Plugin".

• See some Examples of choosing random words from page title

If index is omitted, as in {amazonsearch:java}, the "All" index is assumed.

amazonwishlist - showing the products on an Amazon [WishList]

{amazonwishlist:27E0Z5NDGPYHO} wish show the items on the specified wishlist.

amazonlist - showing the products on other lists

Three kinds of lists are currently available through Amazon Web Services:

• {amazonlist:[WishList]|27E0Z5NDGPYHO} - Amazon [WishList]
• {amazonlist:Listmania|R2WF1NXQUR1AIJ} - Amazon Listmania
• {amazonlist:[WeddingRegistry]|NNC6HFBCFVAC} - Amazon [WeddingRegistry]
  Please note that the list specifier is case sensitive. Also, [BabyRegistry] lists are not currently available through Amazon Web Services.

Bonus - User macro to link to Amazon

If know the specific book, and it's ISBN number, that you'd like to link to, without calling Amazon web services, here is a user macro for that purpose. I've included it as a user macro, rather than in the core of the plugin, so that you can easily edit it for your own purposes. Go to the System Administration screen for User Macros. Create new user macro with these settings: Macroname: amazonpic Do not select "macro has body" Output: Macro generates html markup Body: <table><tr><td> <a href="http://www.amazon.com/exec/obidos/ASIN/$paramisbn/webmill0c32-20" target="books"><img src="http://images.amazon.com/images/P/$paramisbn.01.MZZZZZZZ.jpg" border="0" alt="Cover of ISBN $paramisbn"></a></td><td width=120><a href="http://www.amazon.com/exec/obidos/ASIN/$paramisbn/webmill0c32-20" target="books">$paramtitle</a></td></tr></table> Click save.

The Wiki Way

You can now use this macro like this:

{amazonpic:title=Double Billing|isbn=0688172229}

Using this macro sometimes, and the other macros other times, is a great way to create variety on your pages for your users, and for the search engines. You may want to add an 'align=right' to the table tag so that the output will automatically float to the right so your text can wrap around it. Unless you want to donate the commissions from your clickthroughs to me, be sure to get your own Amazon Associates ID to replace the webmill0c32-20 in the above macro. If you do donate, thanks in advance!

Version History

• 1.1.0 - May 28, 2007 - Added notation guide sections for the macros
  • • Added limit of 20 results for various search lists
    • Added {amazonlist} for [WeddingRegistry], and Listmania lists.
    • Setup jira area for this project
• 1.0.2 - May 25, 2007 - Added 1.0.1 to repository, found some changes that were needed:
  • • Change main directory name to com.bobsgear.amazon.1.0.2 so plugin gets that in the name.
    • Change plugin key from confluence.extra.amazon to com.bobsgear.confluence.extra.amazon
  • Include build.xml in the source package
  • Add this history.txt file
• 1.0.1 - May 13, 2007 - Add license.txt. Add blank developers key to cause default key to be restored.
• 1.0.0 - May 12, 2007 - Initial entry in the 2007 Codegeist contest.

Testing

• Amazon Web Services Plugin Testgroup 1
• Amazon Web Services Plugin Testgroup 2
• Amazon Web Services Plugin Testgroup 3
• [Amazon Web Services Plugin Testgroup 4]

Todo List

• Bugs
  **asin macro didn't work with dashes or spaces for 10-digit ISBN. for example, {asin: 0-7897-2688-2} {asin:0-7897-2688-2}
  
  asin: Error on line 8: Open quote is expected for attribute "width" associated with an element type "img".
  • amazonsearch gets null exceotion on page template page (http://www.bobsgear.com/pages/templates/viewpagetemplate.action?pageTemplateId=5242881)
• Basic
  • Limit number of search results (first n, random n) (search results, wishlists)
  • Limit length of product info (search results, wishlist, individual asin)
  • Products in a browsenode - Amazon info - Extra way to limit product searches, as well as list of related products.
    • While top level browse node values tend to remain the same, the values of others change often. Browse nodes are created and eliminated without notification. For that reason, it is advisable not to hard code browse node IDs into applications. More info about browsenode ids browsenodes
  • Products in other lists such as listmania, [WeddingRegistry], [BabyRegistry], lists Amazon lists
  • Accessories for an item
• Amazon Web Services Advanced Plugin - Planning

Screenshots