WordPress.org

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 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 database has been installed then the plugin will attempt to use the most appropriate Amazon site when creating the link, currently supports http://www.amazon.co.uk, http://www.amazon.com, http://www.amazon.ca, http://www.amazon.cn, http://www.amazon.de, http://www.amazon.es, http://www.amazon.fr, http://www.amazon.it and http://www.amazon.jp.

Create Search Links

If localisation or the Multinational popup are enabled then the plugin will create links to Amazon sites other than your default locale. Sometimes these links either do not work - for example that exact product ASIN is not available in that country. Or is not suitable - for example it is an incorrect region DVD or a book in the wrong language.

Selecting this option will force the plugin to generate links to non-local Amazon sites that search for your product rather than an exact ASIN link. The exact terms of the search are determined by the next option.

This option can be overridden in the shortcode by specifying the 'search_link=1' or 'search_link=0' argument.

Default Search String

If the 'Create Search Links' option is enabled then this string determines what keywords are used to create the search link. Any of the keywords used in the Templates can be used to generate the term, for example the keyword '%ARTIST%' will be expanded by the plugin to the Author/Artist/Director of the linked item.

This option can be overridden in the shortcode by specifying the 'search_text=Specific Search String' argument.

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. For this to work the AWS Access keys in the global settings must be configured with valid keys. 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

If localisation is not enabled, or has failed for some reason, then this is the default Amazon site to use for the link.

AWS Public Key

There are a number of features of the plugin that require access to Amazon Web Services (AWS). These include the generation of live data when displaying the links, providing a product search facility on the post/page edit admin screen, and the ability to generate product wishlists & reccomendations.

If you wish to use any of these features then you must have the appropriate AWS Access IDs and enter them in these two settings. To get these keys simply register with the Amazon Web Service site and this will provide you with the appropriate strings.

AWS Private Key

See above.

Debug

If you are having problems with the plugin and need to contact me, it may be helpful if you could enable this option briefly. It causes the plugin to put extra hidden output in your sites pages that are displaying amazon links, which I can use to diagnose any problems.

It is not recommended that this option is enabled for any length of time as it will show your AWS access keys in the page html source.

Template ASINs

This setting only affects the Template Previews in the Template Manager section of the Amazon Link Settings page. Change this list of ASINs to change which ASIN(s) are used to generate the Template Previews.

Associate IDs & Channels

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.

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'. It is also possible to specify different ASINs per local using the form 'asin=1405235675,1234567890&asin=1840347839,0123456789'.

chan

It is possible to manually select which set of tracking IDs the link uses by specifying the 'chan=channel_id' option. This will override the user specific affiliate ids.

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.

search_link

Overrides the 'Create Search Links' setting. 0 to force direct links by ASIN, 1 to force search based links.

search_text

Overrides the 'Default Search String' setting. A more specific search string can be used to generate the links.

default_cc

Overrides the 'Default Country' setting. Must be one of 'uk', 'us', 'ca', 'cn', 'de', 'es', 'fr', 'it' or 'jp'.

pub_key

Overides the 'AWS Public Key' setting.

priv_key

Overides the 'AWS Private Key' setting.

Technical

AWS Requests

The plugin relies upon the php script aws_signed_request kindly crafted by Ulrich Mierendorff.

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.

Filters

The plugin exposes three filters that can be accessed via the standard WordPress Filter API:

• amazon_link_keywords
• amazon_link_opts_list
• amazon_link_default_templates

amazon_link_keywords

This filter allows developers the ability to change the template keywords used by the plugin, it passes an array with a entry for each keyword. This allows developers to add new keywords, change existing ones or remove unwanted keywords.

Each keyword has the following elements:

keyword This is the index in the keywords array and is used to identify the keyword and is what is searched for in the template. Must be lower case.

Description This is the textual description that is displayed in the Template Help section.

User This indicates that this is a text field that the user can populate.

Live This is set if the keyword is retrieved from the Amazon Web Service API.

The following elements are only required for 'Live' items.

Position This is an array of arrays (in order of preference) determining how to traverse the AWS Item to get the the AWS information.

Group This is a comma separated list of the AWS Response Group(s) needed to return this item's details in the AWS data.

Default This is the default value if no data is returned from the AWS query.

Filter This is any filter that should be applied to the returned AWS data before storing in the cache and being used in the template. See the 'amazon_link_editorial' example below.

Example:

function my_keywords_filter($keywords) { $keywords = array('Description' => 'Item's Author, Artist or Creator', 'live' => '1', 'Group' => 'Small', 'Default' => '-', 'Position' => array( array('ItemAttributes','Artist'), array('ItemAttributes','Author'), array('ItemAttributes','Director'), array('ItemAttributes','Creator'), array('ItemAttributes','Brand'))) return $keywords; } add_filter('amazon_link_keywords', 'my_keywords_filter', 1);

If you add any filters of your own you must flush the Plugin's Product Cache to remove stale data.

amazon_link_option_list

This filter allows developers the ability to change the options used by the plugin, it passes an array with a entry for each option. This allows developers to add new options (or even change existing ones or remove unwanted options - not recommended!).

Each option has the following elements:

Name Name of the Option. Description Short Description of the option. Hint Hint that is shown if the user hovers the mouse over this option (e.g. on a selection option). Default The default value this option has if it is not set. Type What type of option is this. Can be one of:

• text
• checkbox
• selection
• hidden
• title
• textbox
• radio

Class Class of the option as displayed on the options page. Options An array of options for the 'selection' and 'radio' type of option. Length Length of the 'text' option type. Rows Number of rows in the 'textbox' option type. Read_Only Set to 1 if this option can not be modified by the user.

amazon_link_default_templates

If you have built up a library of templates you can use this filter to add those templates to the defaults the Amazon Link plugin provides. If you do a new install or have multiple sites it provides a way to keep the same templates on all sites.

The filter is passed the default templates array in the form:

'image' => array ( 'Name' => 'Image', 'Description' => 'Localised Image Link', 'Content' => $image_template, 'Type' => 'Product', 'Version' => '2', 'Notice' => 'Add impression tracking', 'Preview_Off' => 0 ), 'mp3 clips' => array ( 'Name' => 'MP3 Clips', 'Description' => 'Amazon MP3 Clips Widget (limited locales)', 'Content' => $mp3_clips_template, 'Version' => '1', 'Notice' => '', 'Type' => 'Multi', 'Preview_Off' => 0 )

Use the filter to change the defaults or add your own default templates. Each template has the following elements:

Name The name of the template usually matches the template ID used in the index. Description A short description of the template. Content The actual template content it is recommend that it is run through the 'htmlspecialchars' function to ensure any odd characters are escaped properly. Version The current version of this template, should be a number, e.g. '2.1'. Notice An upgrade notice, what has changed since the last version. Type The type of the template usually 'Product', can be:

• Product
• No ASIN
• Multi

Preview_Off If this template should not be previewed on the Options page, e.g. it is javascript.

amazon_link_editorial

This is an example filter that is installed when the 'amzon-link-extra-editorial' plugin is installed and provides an example of how to process the data returned from Amazon.

This filter passes the editorial content as returned by the Amazon Web Services API, currently this is in the form of an array either of the form:

Multiple Editorial Content:

=> 'Source 1',  => 'Content 1'

or

One Editorial Content:

=> 'Source 1',  => 'Content 1'

The Amazon Link Plugin has a filter of priority 5, adding your own filter of higher priority will override the default plugin action.

e.g. Adding something like:

add_filter('amazon_link_editorial', 'my_editorial_filter', 1, 2);

function my_editorial_filter($editorial, $settings) { $editorial = do_stuff($editorial); return $editorial; }

Disclosure

Amazon requires that all access to the AWS system contain a valid affiliate tag. If you don't not have an affiliate account for all locales do not worry. If the setting is empty the plugin will automatically insert a valid one by default. However it is recommended that you enrol in the Amazon Affiliate program for all countries that your site targets.

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.