This article gives some common examples of how to use short code for our Amazon WS content plugin to add product information to your Joomla articles.

How to display a single product

If there is a specific product that you want to display, use the product ASIN or ISBN, which you supply as the itemId parameter:-

Example code: {amazonWS:itemId=B000EEQ3TY}

How to display several specific products

You can display up to ten products at a time using the itemId parameter, with a comma separated list of product ASIN numbers. This is the best method if you want to display a diverse group of products, because it will fetch all the product information in a single request to the Amazon server, resulting in a reduced page load time.

Example code: {amazonWS:itemId=B000EEQ3TY,B009CARONK,B00HQDBLDO,B002021HIK}

If you view the results you will see a teddy bear, a packet of vegetable seeds, a camera and a violin.

You could also display these products individually:-

{amazonWS:itemId=B000EEQ3TY}

{amazonWS:itemId=B009CARONK}

{amazonWS:itemId=B00HQDBLDO}

{amazonWS:itemId=B002021HIK}

But this is not recommended for more than two products, because each time you use the short code it will result in a separate request to the Amazon server, and will increase your page load time. It is also possible that you will have problems with Amazon's "fair use" policy, which imposes a limit of one request per second. If that happens you will start to see blank results for some of the product information.

If instead you want to display a list of related products on a theme, for example books about motor racing, then a keyword search is probably a better choice:-

{amazonWS:keywords=motor,racing;searchIndex=Books}

It is generally not a good idea to use more than a couple of keywords, because Amazon will only return results that match all of your keywords; if you include too many there will be no products that match your search.

How to Show Products by a Specific Merchant

Use a keyword search for the merchant name, for example if you want to display products by a merchant called 'Perfect Pies', use

{amazonWS:keywords=Perfect Pies;searchIndex=GourmetFood}

Amazon also allow you to select only products that are sold directly by Amazon themselves by using the 'merchantId' parameter, you can use

merchantId=Amazon

This is the only valid value for this parameter, if you omit it then products from all merchants will be displayed (you can also set it in the plugin options if you prefer).

How to Display More than 10 Products

The short code above will display up to 10 products. The Amazon API will never return more than 10 results in a single request, but you can submit multiple requests by using multiple short codes within the same article (but see the discussion above about Amazon's "fair use" policy). To return the following 10 results for the keyword search you use the itemPage parameter:-

{amazonWS:keywords=Perfect Pies;searchIndex=GourmetFood; itemPage=2}

ItemPage can take values from 1 (the default) to 10, Amazon will not display results beyond page 10, if you find yourself needing results beyond page 10 they suggest that you refine your search instead.

How to Sort Product Results

By default, the product search results are sorted by "relevance", which depends on the number of times the keywords appear in the product title and description. Often this is a good choice, but you can choose a different sort order by using the sort parameter, for example:-

{amazonWS:keywords=Perfect Pies;searchIndex=Grocery; sort=salesrank}

which will supply the most popular first. Sort can take many values, depending on the search index and your locale. You cannot use the sort option with the searchIndex option omitted or set to 'All'.

Popular ones that are defined in most cases are:

• 'price' (low to high),
• '-price' (high to low),
• 'titlerank' (Alphabetical: A to Z),
• '-titlerank' (Alphabetical: Z to A)
• salesrank
• relevance (the default)

For example {amazonWS:keywords=Perfect Pies;searchIndex=Grocery; sort=price} gives the cheapest first.

You can see the complete list here: http://docs.aws.amazon.com/AWSECommerceService/latest/DG/localevalues.html

How to have some products display a cart button, while others link to Amazon

You can have some products that link directly to Amazon, and some that use the cart, it is actually fairly straightforward. In the Amazon plugin options, make sure that the shop mode is cart, this means that by default the products will use the remote shopping cart. Then when you want a product to link directly to Amazon, just use the option mode=simple in the plugin code, eg

{amazonWS:itemId=B000EEQ3TY;mode=simple}.

Or you could do it the other way around, and have the default option set to 'simple' in the plugin options, and use 'mode=cart' in the plugin code, whichever way suits you.

This of course only makes a difference if you are using the Amazon Shopping Cart Package, if you are using the content plugin alone, the mode is always set to 'simple'.

You can also force any links in the product display to link directly to Amazon, rather than to a page on your site, by including the option "linkType=external" in your plugin code. Eg

{amazonWS:itemId=B000EEQ3TY;linkType=external}

How to change the layout of results

The plugin has three options that control how results are displayed:-

• searchLayout - controls the display of search results
• articleLayout - controls the display of item lookup (single product) results when in Joomla article view
• blogLayout - controls the display of item lookup (single product) results when in Joomla blog view

You can set any layout you like for any of these options, or create your own layout, add it to the plugin tmpl folder, then set it as an option here. For example if you want to create your own custom layout for DVDs, you can create a dvd.php layout file, then put it in the tmpl folder. Then use code like this to select it:-

{amazonWS:itemId=B010BY2AQ6;articleLayout=dvd}

Suppose you want to display some item lookup results, but have them display like search results, with a link through to a product details page, you can use something like this:-

{amazonWS:itemId=B010BY2AQ6,B000EEQ3TY,B009CARONK;articleLayout=search;linkType=internal}

The linkType=internal option forces the product links to lead to a product details page on your site, rather than linking externally to the Amazon site.