Amazon Web Services Plugin

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

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}
  
  Unknown macro: {asin}
  • 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

Screenshots