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.
Extras
On the Amazon Link Extras Settings page you can manage plugins that add extra functionality to the main Amazon Link plugin. These plugins are either user provided or have been requested by users of the Amazon Link plugin. However although useful they may come with some performance or database impact. As such they are not built into the Amazon Link plugin by default.
The plugins use the filters and action hooks built into the main Amazon Link plugin to modify its behaviour (see the ‘Filters’ section), any changes made on this page will cause the Amazon Link Cache to be emptied.
It is recommended that if you wish to modify the behaviour of Amazon Link plugin then create your own plugins (using the provided ones as a template). They are independent of the main plugin and so will survive any upgrades to the main plugin.
Currently there are a handful of Amazon Link Extra plugins:
- Convert Links – A BETA release of a utility to convert all amazon-link shortcodes into another format, e.g. static content or hidden html.
- Editorial Content – Grab the Editorial content from Amazon and use it to populate the %EDITORIAL% keyword, can be a large amount of data to download and store in the cache.
- Images – Grab all available images from Amazon, enable dynamic sizing of Thumbnails and Images and provide a method of displaying all the images in a template using the keywords %IMAGES% and %THUMBS%.
- Redirect Links – A BETA release of a plugin that creates links of the form http://www.example.com/al/0123456789 that will redirect to the appropriate Amazon web page.
- References – A BETA release of a plugin that allows you to create predefined shortcodes (e.g. for links that located on multiple pages) and add them to pages using a ‘reference’ keyword.
- Spoof Locale – Allows you to view the site as if visiting from another locale to check localisation is working for your site.
Filters
The plugin exposes a number of filters that can be accessed via the standard WordPress Filter API:
- amazon_link_keywords
- amazon_link_option_list
- amazon_link_user_option_list
- amazon_link_default_templates
- amazon_link_admin_menus
- amazon_link_regex
- amazon_link_url
- amazon_link_process_args
- amazon_link_save_channel_rule
- amazon_link_get_channel
- amazon_link_template_get_%KEYWORD%
- amazon_link_template_process_%KEYWORD
It is also possible to add your own filters to process individual data items returned via Amazon by adding a ‘Filter’ item using the ‘amazon_link_keywords’ filter. See the ‘Editorial Content’ plugin for an example of how to do this.
The plugin exposes one action hook that can be used via the standard WordPress Action API:
- amazon_link_init($settings)
Keywords Filter
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.
Default
This is the default value if no data is entered by the user or populated by the AWS query.
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.
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['artist'] = 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.
Options Filters
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!).
amazon_link_user_option_list – This filter allows the developer to change the options displayed on the User’s profile page.
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.
Templates Filter
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.
Admin Menu Filter
amazon_link_admin_menus – Use this filter to add a new Administrative Settings Sub-Menu to the Amazon Link Menu.
The filter is passed the default Sub-Menu structure in the form of an array one entry per sub-menu:
'amazon-link-channels' => array( 'Slug' => 'amazon-link-channels',
'Help' => 'help/channels.php',
'Description' => 'Short Description of Settings Page.',
'Title' =>'Manage Amazon Associate IDs',
'Label' => 'Associate IDs',
'Icon' => 'plugins',
'Capability' => 'manage_options',
'Metaboxes' => array( 'alBox1' => array( 'Title' => 'Title',
'Callback' => array (&$this, 'show_box1' ),
'Context' => 'normal',
'Priority' => 'core')))
Content Filter
amazon_link_regex – Use this filter to change the regular expression that the plugin uses to find the Amazon Link shortcodes. See the PHP documentation on Regular Expressions for more info.
The regular expression must return named items for the key elements of the ‘shortcode’. The default Regular Expression ‘/\[amazon +(?<args>(?:[^\[\]]*(?:\[[a-z]*\]){0,1})*)\]/‘ returns the shortcode ‘args’ as a named item.
All other named items are passed as extra arguments as if they are part of the shortcode:
args – The shortcode arguments in the form of setting=value&setting=value…
Link URL Filter
amazon_link_url – Use this filter to change the way in which the actual Links to the Amazon pages are created.
This filter is passed 6 arguments to help create the Links:
URL – The current URL to be used.
Type – The type of link required – ‘A’ = product, ‘S’ = search or ‘R’ = review.
Data – The product datain the form of a country specific array e.g. (‘us’ => (‘ASIN’,’Title’,…) ‘uk’ => (‘ASIN’, ‘Title’,…).
search [depreciated] – Search string to use if this is a search link.
Country – The Localised Country Code (‘us’, ‘uk’, ‘ca’, etc.)
settings – The Amazon Link settings incorporating any shortcode arguments.
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:
[0] => [Source] => 'Source 1', [Content] => 'Content 1',
[1] => [Source] => 'Source 2', [Content] => 'Content 2'
or
One Editorial Content:
[Source] => 'Source 1', [Content] => '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;
}
Advanced Filters
amazon_link_process_args – Use this filter to arguments passed in via the shortcode, is passed two arguments: $arguments and $amazon_link.
The $arguments is an associative array reflecting the parsed shortcode arguments, e.g. Amazon will create an array ( ‘asin’ => ‘0123456789’, ‘title’ => ‘Title’ ).
The $amazon_link is the amazon link class instance, to allow access to internal functions.
amazon_link_save_channel_rule – This filter provides access to the processing of the Channel ‘Rules’, where the content of the ‘Filter’ textbox entered by the user is converted into ‘Rules’. The filter is passed 4 arguments: $rules, $channel, $channel_data, $amazon_link.
$rules is an array of rules to be tested in the amazon_link_get_channel filters.
$channel is the name of the channel being processed.
$channel_data is the options associated with the channel, one of which is the Filter ($channel_data[‘Filter’]).
$amazon_link is the amazon link class instance, to allow access to internal functions.
amazon_link_get_channel – Is the filter used to help select which channel should be used for a particular shortcode. Is passed 4 arguments: $selected_channel_data, $channels, $post, $settings, $amazon_link.
amazon_link_template_get_%KEYWORD% & amazon_link_template_process_%KEYWORD% – These filters are applied to every instance of a keyword as it is encountered in the template. The ‘get’ filter is applied before any data is retrieved from Amazon or the product Cache, the ‘process’ filter is applied immediately after data retrieval.
So to alter how the %PRICE% keyword is displayed you would add a filter with the tag ‘amazon_link_template_process_price’.
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.
- Have static data for displaying the template previews, for users without AWS keys
- Source Widgets not working on new install – Template ASINs has no default?
- Add diagnostics submenu, get cache cron task working, display ‘not found’ items in cache page
- Add ‘Status’ Box -> Alerts on Dashboard, nag, ‘not found’ items, x% from locale with no tag
- Kindle items not showing list price, add format?
- Combine ‘convert’ and ‘alternates’ extras plugins
- Add flush to sc cache on any admin change, settings, template post/page edit.
- Add Price history database, graph popup -> cloud store/access data