=== Amazon Link === Contributors: paulstuttard Donate link: http://www.houseindorset.co.uk/plugins Tags: Amazon, links, wishlist, recommend, shortcode, ip2nation, localise, images, media library, affiliate, product, template Requires at least: 3.1 Tested up to: 3.1.3 Stable tag: 2.0 Provides a facility to insert Amazon product links directly into your site's Pages, Posts and Widgets and Templates. == Description == This plugin is used to quickly add Amazon products to your Wordpress posts and pages. The products can be simple text links, thumbnail images, fullsize images, complex templates or full-blown Amazon flash widgets. The product links that the plugin generates can be for any of the Amazon domains ([www.amazon.co.uk](http://www.amazon.co.uk), [www.amazon.com](http://www.amazon.com), [www.amazon.ca](http://www.amazon.ca), [www.amazon.cn](http://www.amazon.cn), [www.amazon.de](http://www.amazon.de), [www.amazon.fr](http://www.amazon.fr), [www.amazon.it](http://www.amazon.it) and [www.amazon.jp](http://www.amazon.co.jp/)). The content of the products can be statically entered by the Author, when the link is created, or dynamically refreshed when displayed using the Amazon site that is most appropriate for the nationality of the reader. The products to be displayed can be specified when the link is created, using the built in Amazon search widget, or dynamically generated by searching the content of the site. All product links will contain the Amazon affiliate ID of the site author and will be the relevant one for that locale, allowing the author to collect commission on any products purchased through the links. = Key features = * [Search Tool](#search) to assist authors to create links in posts and pages * Simple `[amazon]` [shortcode](#shortcode) used to generate product links * [Localisation](#localise) of all links based on the nationality of the reader * Optional multinational popup to allow the reader to choose which Amazon site to visit * [Global options](#options) to update the behaviour of all the links on your site * Ability to locally override the global options using the [shortcode](#shortcode) content * Flexible [template facility](#templates) to enable the author to quickly create complex content quickly and consistently * Includes [built in templates](#defaults) for the major Amazon widgets (Carousel, My Favourites, etc.). = Quick Start = To quickly add a simple text link add the following lines into an entry (page, post or text widget): `[amazon asin=&text=]` Where ASIN Number is the unique amazon number used to identify products e.g. "1405235675". The Link Text is simply what you want to be shown for the link, e.g. "Mr. Good". To utilise one of the templates simply specify the template option with the name of the template to use. For example: `[amazon asin=&title=&template=thumbnail]`. To generate a list of products relevant to the content of your site use the 'cat' option, to specify where the plugin should search for Amazon product links. This option can be either 'local' to search the current content or a list of category ids to search specific sections of your site. For example I use this feature to provide friends and family some ideas for presents This feature is based on the Amazon Web Service API and uses the 'CartSimilarities' feature to generate the list of items. This is created by either putting the line `amazon_recommends(,)` in your template. Or putting the line `[amazon cat=&last=]` within a post or page. Where 'Category' is a list of category ids to search within (e.g. as expected by the 'cat' argument of [query_posts](http://codex.wordpress.org/Template_Tags/query_posts#Parameters) function. The 'last' parameter is the number of posts to search through. == Installation == Simply: 1. Download the [amazon-link plugin](http://wordpress.org/extend/plugins/amazon-link/) from the [Plugin Directory](http://wordpress.org/extend/plugins/). 1. Unzip the amazon-link.zip file into your Wordpress `/wp-content/plugins/` directory. 1. Activate the plugin through the 'Plugins' menu in WordPress. 1. Update the settings (at the very least change the default Affiliate Tag) 1. If you wish to use the Wishlist functionality, Search or Media Upload facilities or the live data option you must also set up an [Amazon Web Services](http://aws.amazon.com/) account. So that you can update the AWS Public and Private key settings. 1. Insert links and wishlists into your content using the [amazon] tag as described above, or using the Amazon Link box on the Page/Post edit pages. == Settings == The plugin has a settings page found under the Administrative Settings section, this is where the author can modify the behaviour of all the links embedded in their site. Note any changes here will affect all existing links that do not explicitly set these options via the [shortcode](#shortcode) content. These options can be viewed as the 'default' behaviour any of which can be overridden locally by adding the appropriate parameter to the shortcode. = Link Text = If you do not specify the 'text' argument in your [amazon] shortcode, then this text will be used by default. This option is equivalent to the 'text' shortcode argument, and the %TEXT% keyword in the template. = Image Class = Allows the author to change the default class used when the plugin inserts a thumbnail or image into a post. This option is equivalent to the 'image_class' shortcode argument, and the %IMAGE_CLASS% keyword in the template. = Wishlist Template = This is the default template used by the plugin when it auto generates a list of products using the wishlist facility. This option can be overridden in the shortcode by specifying a valid template using the 'template' argument. = Wishlist Length = This is the maximum number of items to display in a wishlist. This option can be overridden in the shortcode by specifying the 'wishlist_items' argument. Note: Amazon only returns a maximum of 5, for the 'Similar' type of list. = Wishlist Type = This sets the default type of wishlist to generate. A wishlist of type 'Similar' will show items similar to the ones found in the content. A wishlist of type 'Random' will show a random selection of the ones found. A wishlist of type 'Multi' simply lists the items in the order they were found. This option can be overridden in the shortcode by specifying the 'wishlist_type' argument. = Multinational Link = If this option is selected then the plugin will enable a small popup menu of country specific links whenever the user's mouse rolls over the Amazon link, enabling them to select the site they feel is most appropriate. = Localise Amazon Link = If this option is selected and the [ip2nation](http://www.ip2nation.com/) database has been installed then the plugin will attempt to use the most appropriate Amazon site when creating the link, currently supports [www.amazon.co.uk](http://www.amazon.co.uk), [www.amazon.com](http://www.amazon.com), [www.amazon.ca](http://www.amazon.ca), [www.amazon.cn](http://www.amazon.cn), [www.amazon.de](http://www.amazon.de), [www.amazon.fr](http://www.amazon.fr), [www.amazon.it](http://www.amazon.it) and [www.amazon.jp](http://www.amazon.co.jp/). Note when generating live product links the Italian and Chinese sites do not yet support this capability and will generate content from 'amazon.fr' and 'amazon.com' respectively. = Remote Images = If this option is selected then when generating shortcodes for image links, the plugin will point to ones hosted on Amazon, rather than ones in the media library. = Live Data = If this option is enabled then the plugin will attempt to retrieve up to date (and localised) information on the product when generating the product link. If not enabled then the plugin will only use the information included in the shortcode. This option can be overridden in the shortcode by specifying the 'live=1' or 'live=0' argument. Note this option also changes the behaviour of the Amazon Search Tool. When the tool is used to insert shortcodes into the post it will automatically prefill the keywords needed for the selected template. It will only do this if live data is not enabled. = New Window Link = If this option is enabled then when generating links, the plugin will ensure that if they are clicked on it will open it in a new browser window. This option is equivalent to the 'new_window=1' shortcode argument. = Default Country & Associate IDs = If localisation is not enabled, or has failed for some reason, then this is the default Amazon site to use for the link. The author must enter their Amazon Associate IDs for any countries they have an ID for in this section. This will ensure their Associate account is credited with any sales made through the links. = AWS Public Key = If you wish to use the wishlist/recommendations part of the plugin then you must have the appropriate AWS public and private key pair and enter them in these two settings. To get these keys simply register with the [Amazon Web Service](http://aws.amazon.com/) site and this will provide you with the appropriate strings. = AWS Private Key = See above. == Shortcode == The main arguments available when creating a shortcode are listed below, enter each argument separated by a '&'. It is also possible to override settings on the global options page, or elements used in the product templates: = text = The text used to generate the amazon link, Enter any plain string e.g. 'text=My Text'. = image_class = The css class used when displaying the image in the post. = asin = The unique Amazon product ID or IDs, of the form '1405235675,1234567890'. Enter as 'asin=1405235675,1234567890'. = cat = When creating a wishlist you must specify the post category(s) through which to search for other Amazon links. Enter as 'cat=4,7'. Alternatively enter 'cat=local' to search the content on the current page. = last = When creating a wishlist you can specify how many posts to search through for Amazon links. Enter as 'last=30'. = localise = Overides the 'Localise Amazon Link' setting. 0 to force the default country, 1 to force localisation. = multi_cc = Overides the 'Multinational Link' setting. 0 to disable the popup, 1 to enable the popup. = default_cc = Overides the 'Default Country' setting. Must be one of 'uk', 'us', 'ca', 'cn', 'de', 'fr', 'it' or 'jp'. = pub_key = Overides the 'AWS Public Key' setting. = priv_key = Overides the 'AWS Private Key' setting. = thumb - depreciated = The URL used to display an image thumbnail for the amazon link in the post, if '1' is used then the image stored in the Wordpress media library is used. = image - depreciated = The URL used to display a fulll size image for the amazon link in the post, if '1' is used then the fullsize image stored in the Wordpress media library is used. If both 'image' and 'thumbnail' are set then the shortcode will cause a thumbnail image to be displayed in the post which links to the fullsize image (rather than to the Amazon store). == Frequently Asked Questions == = I've tried the plugin and it doesn't do what I want, help? = If you think the plugin doesn't work, please try contacting me and I will endeavour to help. You can either start a forum topic on the [Wordpress site](http://wordpress.org/tags/amazon-link?forum_id=10) or leave a comment on my site on the plugin page [Amazon Link Page](http://www.houseindorset.co.uk/plugins/amazon-link). = How do I insert product links into my posts? = The plugin adds a helper tool to the Post and Page administrative pages of your Wordpress site that can be used to generate shortcodes easily and quickly. If you already know the ASIN then simply enter it into the ASIN input and click on 'Send To Editor'. If not then there is a facility to search Amazon, by Index, Product Title and or Product Author/Artist. Use this to find the product you wish to link to on your site, then select the appropriate template and other settings and press the 'Insert' button. This will insert the shortcode into your post, with all the settings required for the selected template pre-filled. If you are using 'live' data then it will only include keywords that must be provided by the author 'text', 'text1', etc. If you are using static data then it will also prefill the keywords with the product information retrieved from the Amazon site. There is also a facility to add cover images from the Amazon items into the local media library as attachments to the post (Press the 'Upload' button). The plugin will always use these local images in preference to ones fetched from the Amazon site. These images or the remote ones hosted on Amazon can be used to insert image or thumbnail links into your posts. = Can I create my own templates for product links? = On the plugin settings page there is a dedicated section to showing all the available templates. Use this to create, delete and copy templates. The template content is based on standard html with additional keywords that are surrounded by '%' characters. See the Template Help on the same page for a description of each of the keywords that can be used. Most of the keywords are self explanatory: `'%TITLE%'` will expand to be the product's title, `'%PRICE%'` the formatted product's price, etc. However links can be created by using the keyword pair `'%LINK_START%'` and `'%LINK_END%'` with the subject of the link being placed between them. For example `'%LINK_START%Amazon Product%LINK_END%'`. The link produced will comply with whatever settings you have used, i.e. localised to the users country, produce multinational popup, with the appropriate Amazon associate ID inserted. There are a number of other keywords that are also localised these include: `'%LINK_START%'` - as described above, `'%TLD%'` the Top Level Domain to be used '.co.uk', '.it', '.com', etc.; `'%MPLACE%'` - the Amazon Market place to use 'GB', 'IT', 'US', etc.; `'%CC%'` - the localised country code 'uk', 'it', 'us'; `'%TAG%'` - The amazon associate tag to use. By specifying the 'Live Data' setting either in the settings page or within the amazon shortcode the data used to fill the template can be generated when the link is displayed. Or if you prefer to use static data or override some of the template content the keywords can be specified in the shortcode. There are a number of keywords that are only used for static data, these are `'%TEXT%'`, `'%TEXT1%'`, `'%TEXT2%'`, `'%TEXT3%'`, `'%TEXT4%'`. The keyword `'%ASINS%'` can be used to indicate that this template will accept a string of comma separated ASINs to generate its output, for example the Amazon Carousel widget. Normally putting a list of ASINs in the shortcode will cause multiple links to be generated. Browse the default included templates to see some examples of how the keywords can be used. Note: the Amazon widgets are currently not supported in some locales (e.g. Canada). = What templates are included with the plugin? = The plugin contains a set of basic templates to show how the keywords can be used. The easiest way to create new ones is to copy one of the existing ones and update it to meet your needs. Most of these templates were created by using the Amazon Affiliate site, generating the widget or link required then copying the generated output into the 'Template Content' box. Then quickly replacing any of the static data with template keywords, e.g. the product ASIN, Title, etc. Currently the plugin has default templates for: * Thumbnail link * Image link * Amazon Iframe based Image link * Amazon Carousel Widget * Amazon My Favourites Widget * Amazon MP3 Clips Widget * Wishlist Template The 'Wishlist' template is the default template used for any lists created by shortcodes, as such it must exist. Deleting this template will cause the plugin to recreate any of the default templates that do not exist. This can be used to reset the templates back to their factory settings. = Can you provide a few examples of the shortcodes? = `[amazon asin=B001L4GBXY&text=Guns n' Roses CD]` Will produce a text link to an Amazon Product page: `[amazon asin=B001L4GBXY&title=Guns n' Roses CD&template=Thumbnail]` Will produce a thumbnail image link to an Amazon Product page. `[amazon asin=B001L4GBXY,B001L2EZNY,B001LR3576,B001KSJNWC,B001LWZCKY,B001GTPI7O,B001GTAGS0&template=Iframe Image]` Will produce 3 classic Amazon product links to the specified products. `[amazon asin=B001L4GBXY,B001L2EZNY,B001LR3576,B001KSJNWC,B001LWZCKY,B001GTPI7O,B001GTAGS0&template=Carousel]` Will produce a single Amazon Carousel widget containing all the specified products. `[amazon asin=B001L4GBXY,B001L2EZNY,B001LR3576&template=Wishlist&live=1]` Will produce a list of the 3 products using data from the reader's local Amazon site. `[amazon asin=1841498955&template=Wishlist_Post&product=Book&title=Surface Detail (Culture 9)&artist=Iain M. Banks&thumb=http://ecx.images-amazon.com/images/I/41n7sphvJpL._SL160_.jpg&image=http://ecx.images-amazon.com/images/I/41n7sphvJpL.jpg&price=£5.30]` Will produce a link using a custom template filled in with the data included in the shortcode. `[amazon asin=1841498955&template=Wishlist_Post&live=1&title=My Favourite Book]` Will produce a link using a custom template filled in with live data from the Amazon site, but with the title set by the data included in the shortcode. `[amazon text=Recipe Books&cat=3,4,5&last=30&wishlist_type=Random]` Produce a wishlist using the default template containing a random selection of products found in the posts in categories 3, 4 and 5. `[amazon cat=local&template=My Favourites&wishlist_type=similar&text=Some Related Products]` Produce an Amazon My Favourites widget containing a selection of related products to those already displayed on the current page. = Why doesn't the Wishlist function work? = For this to work you must have set up a working [Amazon Web Services](http://aws.amazon.com) account and set the AWS Public and Private key settings to those provided in the AWS->Security Credentials->Access Credentials section. You must also have inserted at least a few links to Amazon products using the tag for it to generate a list of related product suggestions. = Can I change the styling of the wishlist? = If you are using the default Wishlist template that came with the plugin then you can override the default styles. To do this add the file 'user_styles.css' to the plugins directory overriding the default stylesheet, the wishlist has the following style elements: * amazon_container - Encloses whole wishlist. * amazon_prod - Encloses each list item. * amazon_img_container - Encloses the item thumbnail (link+img) * amazon_pic - Class of the item thumbnail IMG element * amazon_text_container - Encloses the item description (Title paragraphs+link + Details paragraphs) * amazon_details - Encloses the item details part of the description * amazon_price - Spans the item's formatted price. = Are the links localised to match my visitor's country of origin? = The links that are generated can optionally be localised to the Amazon store most likely to be used by the visitor to your site, this is achieved by installing the [ip2nation](http://www.ip2nation.com/) database and enabling 'localise links' option in the plugin settings. Obviously the database is not perfect and some people browse through proxies or through their company's firewall so it may get the wrong country of origin. Additionally there are only 8 major Amazon sites (UK, France, Germany, US, Japan, Italy, China and Canada). So the plugin has to guess where a country's residents are most likely to shop on-line. An alternative is to enable the 'Multinational Link' option, this will enable a small popup for each link allowing the site visitor to choose the most appropriate site (based on locale or language). The plugin includes a tool to install and monitor the status of the ip2nation database. However the installation of the ip2nation database is not validated, it simply downloads the latest database file from ip2nation and zaps it into your wordpress mysql database. If the file is corrupted or maliciously changed then this operation could completely destroy your sites mysql database, if in doubt manually download the database from [ip2nation](http://www.ip2nation.com/) and check its content, currently it consists of 2 tables ip2nation and ip2nationCountries. == Technical: == The plugin relies upon the php script aws_signed_request kindly crafted by [Ulrich Mierendorff](http://mierendo.com/software/aws_signed_query/). The plugin has two utility classes that might be of use to other plugin designers. The first is one for generating the options page (as well as the 'Add Amazon Link' meta box). The second is an AJAX facility for performing Amazon product searches and returning an array of product details, including a facility to fill in a HTML template with various attributes of the product using the patterns %TITLE%, %PRICE%, %AUTHOR%, etc. See the plugin source files for more details on how to utilise them. == Translations == The plugin comes with translation support but as yet no translations are included, please refer to the WordPress Codex for more information about activating the translation. If you want to help to translate the plugin to your language, please have a look at the i18n/amazon-link.pot file which contains all definitions and may be used to create a language specific .po file, if you do then contact me and I will add it to the plugin ready for the next update. == Disclosure == Note: If you do not update the affiliate tags then I will earn the commission on any sales your links make! For which I would be very grateful, as soon as you change the settings this will ensure all links on your site will be credited to your affiliate account(s). == Future Updates == There are a number of things I want to update the plugin to do, some of which have already been done in other plugins, but not quite how I would like. I would like to bring it all together in one plugin. Features I will be adding to the plugin in the future: * Allow the wishlist to search for legacy amazon links not just ones embedded in the shortcode. == Changelog == = 2.0 = * Add template facility, with pre-designed templates for most Amazon widgets * Add ability to create multiple links from one shortcode * Add shortcode processing in widgets * Add an option to make the links open in a new window when clicked on by a reader. * Add an option to set the length of the wishlist displayed = 1.8.1 = Default to using .com for aws requests when user has configured Italian or Chinese as the default domain. Note requires Wordpress version 3.1 for this release. = 1.8 = Add support for images into the shortcode, as well as the ability to add images to the Wordpress media library. = 1.7 = Rework ip2nation download function = 1.6 = Add support for China and Canada Associates sites, fix ip2nation status check bug. = 1.5 = Change the multinational link to use less in-line javascript. = 1.4 = Added a simple widget to the post & page new/edit screen to assist in adding shortcodes to posts, providing a facility to search Amazon. = 1.3 = Add link localisation through IP address lookup, and support for all 6 amazon affiliate sites not just one via a image popup. = 1.2 = Improve options page processing. = 1.1 = Move options page into 'Options' section. Corrected stylesheet content, updated styles & provide facility to override the stylesheet. Add internationalisation hooks into plugin. = 1.0 = First Release == Upgrade Notice == = 2.0 = Upgrade to this release to enable Product Templates, multi-product links, product links in widgets and major code rework. = 1.8.1 = Upgrade if you want partial support for China and Italy for the product search widget. = 1.8 = Upgrade to this release to add support for image links, and downloading of cover images to the Wordpress media library. = 1.7 = Upgrade if you are having problems installing the ip2nation database = 1.6 = Upgrade to support the 2 new amazon associates site, and address ip2nation bug. = 1.5 = Upgrade if you are having problems with the javascript in the multinational link. = 1.4 = Upgrade to enable the metabox to allow easy insertion of the Amazon Links into Posts and Pages = 1.3 = Upgrade if you want multinational link support or link localisation. = 1.2 = Minor internal structural changes, add options link from plugin page. = 1.1 = Upgrade if you wish to have internationalisation (i18n) support. == Screenshots == 1. This is the example wishlist taken from [www.HouseInDorset.co.uk](http://www.houseindorset.co.uk/plugins/amazon-link) 2. This shows the multinational Amazon link popup. 3. This shows the Amazon Link Metabox that can be used to insert shortcode links into Posts or Pages. 4. This shows the Template editor available on the Plugin's Settings page.