DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
TM ASIN Search¶
Author: | Kasper Skårhøj |
---|---|
Created: | 2002-11-01T00:32:00 |
Changed by: | Lars T. |
Changed: | 2009-07-21T22:51:21.250000000 |
Classification: | Documentation for TYPO3 extension TM ASIN Search |
Keywords: | TYPO3, Amazon, ASIN, THAMEY |
Email: | support@thamey.de |
Info 2: | |
Info 3: | |
Info 4: |
TM ASIN Search¶
Extension Key: tm_asinsearch
Copyright 2005-2009
Lars Thalheim, <support@thamey.de>Bernd Wilke
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
The content of this document is related to TYPO3
- a GNU/GPL CMS/Framework available from www.typo3.com
Table of Contents¶
ASIN Search 1
Introduction 1
What does it do? 1
Features 1
Configuration 2
Installation 2
Customize HTML template – Tutorial 2
Known problems 8
ToDo list 8
Changelog 8
Introduction¶
What does it do?¶
This extension retrieves product information from the Amazon Product API, formerly Amazon Web Services. The product retrieved is specified in the back end either with a content element, from TypoScript or by a number of records. You can create a content element just like normal text and specify an ASIN or select from a list of records defining Amazon items. Alternatively you can specify the ASIN with TypoScript, if you like to include the plug in with TypoScript at a fixed position within your template. The extension will retrieve the information from Amazon automatically and output it in a user defined way. Output is defined by TypoScript and HTML templates.
In addition, the Amazon associate program is also supported, in order to collect revenues from Amazon sales.
Background¶
The extension eim2amazonsearch (by Achim Eichhorn) was the origin of this extension. When implementing this extension into a web page, I missed a possibility to specify the item to display from back end. eim2amazonsearch seems to support front end input only.
Simply specify an ASIN in back end and show the item in front end. It's that simple.
Features¶
Supports various localized Amazon web services
you can override the default and specify a different web service URL by TypoScript
Supports Amazon associate partner program
you can specify your Amazon associates ID by TypoScript. The generated link honors your associate ID
FE output is templated by using TypoScript and an HTML template as commonly used by other extensions
The ASIN to search for is entered in back end content element via FlexForm, in a record or in a TypoScript template
Supports signed request as required by Amazon from August 15 th 2009
From now on you can also define and modify the output of the product images
What's new¶
The support of two different template formats is dropped, because the template would have to be extended by a third format. The new format is even simpler to use. The HTML template format from version 2.x is honored automatically to raise compatibility with former version of TM ASIN Search.
TypoScript support to configure the output is added. Now you can use most standard TypoScript features such as stdWrap, wrap to even more customize data to output.
From now on you not only can display the images delivered by Amazon, but you can configure images as you like. Resize it, crop it, insert watermarks, define quality. It's all up to you and configurable using the well known TypoScript.
Another addition is a list mode. The standard mode is to specify one ASIN in each content element. Now you can create a list of records specifying one Amazon product each. In the content element you then select what records to display. This feature was kindly provided by Bernd Wilke.
Screen shots¶
[Fill in screen shots here]
Administration¶
Installation¶
To install this extension, five steps must be taken:
Apply for an Amazon Access key ID from Amazon developer program, if you have not already done so. This ID is (currently) free of charge.
Optionally apply for a Amazon associates ID from the Amazon partner net, if you have not already done so and if you want to collect revenues by linking to Amazon products.
Install TM ASIN search with the Extension Manager.
Customize your TypoScript template. Specify at least your access key and your secret access key in your template. All other settings fall back to default values.
Customize your HTML template for output.
Apply for AWS Access Key¶
This extension obviously relies on the Amazon Product API (formerly Amazon Web Services). For sending requests to the product API, Amazon requires to send an AWS Access Key ID along with the request. Also each request must be signed by August 15 th 2009. This Access Key ID and the corresponding Secret Access Key are free of charge. You must apply for such an Access Key ID from the Amazon Developer Program (link: http://aws.amazon.com/).
The former developer token are not supported any more, because the old Amazon web services have expired on March 31, 2008. Don't use your old Developer token any more.
Also note, that you must specify the correct locale corresponding to your Access Key ID. A German Access Key does not work with the US web service and vice versa. (I'm not sure, if this still applies by July 2009.)
If you don't upgrade to this version, your TM ASIN Search of version 2.x and earlier will stop working on August 16 th 2009.
Install the extension¶
This is documented very well in the usual TYPO3 docs: just click the little gray sphere with the plus-sign and when it asks for any changes to commit, let it make them.
Customize TypoScript template¶
The current version of TM ASIN Search is reprogrammed from ground up in many areas. Therefore most configuration options have changed. Configuration is done in the TSetup field of your template.
You MUST at least specify your Access key ID and your secret Access key:
0: plugin.tx_tmasinsearch_pi1 {
1: accessKey = 000000000000000
2: secretAccessKey = 1234567890
3: }
For your convenience the old “access_key” is read if the new “accesKey” does not exist. Nevertheless you must specify a secret access key.
Customize TypoScript¶
To output your Amazon item, you have to define your template. The template contains of two parts: TypoScript and HTML.
With the TypoScript part you define labels you can use in your HTML as markers. You also define, what data to display and how to render it. Once finished you can use these self defined labels and construct your HTML template.
Customize HTML template¶
Like many other extensions, this extension uses a standard HTML template for output customization. A sample template is provided in the extensions directory. Copy this example template to a convenient place and modify it to fit your requirements.
1: plugin.tx_tmasinsearch_pi1.templateFile = fileadmin/mytemplates/asinsearch.tmpl
The HTML template is not dependent on the returned data from Amazon anymore, as in previous versions of TM ASIN Search. You define your own labels in TypoScript and use these labels as markers in your custom HTML template.
For detailed information about returned data consult the AWS documentation at `http://docs.amazonwebservices.com/AWSECommerceService/2008-03-03/DG/ <http://docs.amazonwebservices.com/AWSECommerceService/2008-03-03/DG/> `_
Configuration¶
Configuration parameters¶
[plugin.tx_tmasinsearch_pi1]
accessKey¶
Directive
accessKey
Data Type
string
Description
This defines your personal access key. To use this extension you're required to apply for an Access Key from Amazon Webservices. If this parameter is not set, the old “access_key” is tried. If even the old access_key does not exist, you'll revceive an error in the front end.
Default is not set!
d
secretAccessKey¶
Directive
secretAccessKey
Data Type
string
Description
This defines your personal Secret Access Key. To use this extension you're required to apply for an Access Key from Amazon Webservices. If this parameter is not set, you'll revceive an error in the front end.
Default is not set!
d
associateId¶
Directive
associateId
Data Type
string
Description
This defines your associate ID (PartnerID) from Amazon associate programme. If you have your own ID, please specify it here. If this setting is not present, the old “associate_if” is tried. If you want to clear the default value (see below), clear this setting.
d
wwwhaustierra-21
wsdlFile¶
Directive
wsdlFile
Data Type
string
Description
This specifies the target webservice. Specify the REST URL of the Amazon webservices in your country.
If you specify the “locale” setting and leave this setting unset, it will automatically default to the appropriate wsdlFile according to your locale setting. You can override this by specifying your own file in format: http://server/path/file
Default is automatic setting depending on the setting “locale”.
d
locale¶
Directive
locale
Data Type
string
Description
This defines the localization of the returned data. When retrieving data from Amazon certain result data fields are returned in a localized version. For example the reviews could be either in german or in english. This parameter defines, what localization you request.
Possible values are the international two-letter codes: CA, US, FR, JP, UK and DE. All other values default to DE. This is case- insensitive.
If this setting is specified, the wsdlFile will be preset to the corresponding REST URL.
Note that you must use the corresponding locale for your Access Key ID.
d
DE
resultType¶
Directive
resultType
Data Type
string
Description
This defines the “response group” requested from amazon. Normally all possible data is requested from Amazon. Set this to the response group required for your requested data. You can save traffic and parse time by specifying a response group returning lesser data.
Possible values are all valid “response groups” from Amazon webservice.
d
Medium
templateFile¶
Directive
templateFile
Data Type
string
Description
This parameter defines, what template file to use.
Default is the sample file provided with this extension.
d
Sample file from extension
mode¶
Directive
mode
Data Type
string
Description
This defines the operation mode. It is important, when operating as plugin. If you operate this as content element, you'll have to set the mode via flexform.
Possible values are: ASIN and LIST
d
ASIN
asin¶
Directive
asin
Data Type
string
Description
This parameter defines the ASIN to search for. If you specifiy an ASIN from a content element, the setting from content element overrides a setting from TypoScript.
This setting is becomes valid only, when “mode” is set to “ASIN”.
If this setting is unset, you'll receive an error in front end.
Default is not set!
d
asinList¶
Directive
asinList
Data Type
string
Description
This parameter defines a list of record uids, containing the ASIN to search for. If you specify the records from a content element, the setting from content element overrides a setting from TypoScript.
This setting is becomes valid only, when “mode” is set to “LIST”.
If this setting is unset, you'll receive an error in front end.
Default is not set!
d
debug¶
Directive
debug
Data Type
int
Description
Enable debug mode to aid in building your configuration.
0 = Disable debugging, 1= Show the query result, 2 > even more verbose (for development only)
d
0
forceImageCopy¶
Directive
forceImageCopy
Data Type
boolean
Description
When querying amazon the images are copied from Amazon to your local typo3temp folder. The image is not being copied, when the file already exists (it is cached). If you enable this option, the file will be copied, regardless of existing already.
d
0
items¶
Directive
items
Data Type
[ITEMS]
Description
This contains the definition of your template markers.
d
To build your template and to define, what to display, you have to create items within plugin.tx_tmasinsearch_pi1.items. These items follow the syntax you should be used to by standard TypoScript.
You can specify as many items as you like. Each item consists of a name, a type, a path from where to get the actual data and additional settings. An example item looks as follows:
1: plugin.tx_tmasinsearch_pi1 {
1: items {
2: myItem = TEXT
3: myItem {
4: resultPath = segment1|segment2|segmentX
5: wrap = <div class=”some-class”>|</div>
6: }
7: }
8: }
The name “myItem” can be chosen freely. There is no special restriction. Also the case sensitivity is of no relevance at this point. In your HTMl template you address this item by the marker ###MYITEM###. The marker is the name in upper case, surrounded by ###. So if you define an item “myItem” and another item “Myitem” you define two different items, but the marker in your HTML template would be the same for both: ###MYITEM### which would make one of your items inaccessible.
Configuration types¶
The following types can be used:
TEXT¶
Directive
TEXT
Description
This type is fully equivalent to the TEXT cObject in TypoScript. You can use the exact same parameters as with the TEXT cObject with one exception and one addition.
The property “resultPath” specified the access path of the data from your amazon result.
The property “value” will be set by TM ASIN Search.
LINK¶
Directive
LINK
Description
This type is fully equivalent to the TEXT cObject in TypoScript. You can use the exact same parameters as with the TEXT cObject with one exception and one addition.
The property “resultPath” specified the access path of the data from your amazon result.
The property “stdWrap.typolink.parameter” will be set by TM ASIN Search.
IMAGE¶
Directive
IMAGE
Description
This type is fully equivalent to the IMAGE cObject in TypoScript. You can use the exact same parameters as with the IMAGE cObject with one exception and one addition.
The property “resultPath” specified the access path of the data from your amazon result.
The property “file” will be set by TM ASIN Search.
GIFBUILDER¶
Directive
GIFBUILDER
Description
This type is fully equivalent to the GIFBUILDERcObject in TypoScript. You can use the exact same parameters as with the GIFBUILDERcObject with two additions.
The property “setImage” is the number of an IMAGE object within this GIFBUILDER, that shall contain the Amazon image.
The property “resultPath” specifies the access path of the data from your amazon result.
e.g.: If your GIFBUILDER object contains of 10=IMAGE, 20=BOX, 30=IMAGE, 40=TEXT, and you want the 30 to contain the image from Amazon, you have to set “setImage = 30”.
To the IMAGE object within the GIFBUILDER applies the same exception and addition, as to the IMAGE type above.
REGISTER¶
Directive
REGISTER
Description
This works almost like the LOAD_REGISTER cObject from TypoScript. The only parameter is the “resultPath” property. With:
myItem = REGISTERmyItem.resultPath = segment1|segment2
you could access the data within any other item using the well known “register:myItem” syntax.
The property 'resultPath' defines the path from where to get the data within the query result. If you want to display the ASIN from the query result, then set this to 'resultPath = ASIN'. If you want to display the price, set this to 'resultPath = OfferSummary|LowestNewPrice|FormattedPrice'. For an image use eg. 'resultPath = LargeImage'. Just follow the chain of field names from the query result (enabled with debug option).
((generated))¶
Example: Configuration of all options¶
All configuration can be made in TSetup of your template. The following example contains all possible configuration options:
1: plugin.tx_tmasinsearch_pi1 {
2: accessKey = 1234567890
3: secretAccessKey = 12345678901234567890
4: accessKey = 1234567890
5:
6: templateFile = fileadmin/tm_asinsearch_template.tmpl
7:
8: debug = 1
9: locale = de
10: wsdlFile = http://ecs.amazon.com/onca/xml
11: resultType = Large
12: forceImageCopy = 1
13:
14: mode = ASIN
15: asin = 1234567890
16:
17: items {
18: asin = TEXT
19: asin.resultPath = ASIN
20:
20: image = GIFBUILDER
19: image {
20: XY = 100,100
20: backColor = #abcdef
20: format = jpg
20:
20: setImage = 10
20: resultPath = ImageSets|ImageSet|MediumImage
20:
20: 10 = IMAGE
22: }
20:
20: altTitle = REGISTER
20: altTitle.resultPath = ItemAttributes|Title
20:
20: orderLink = LINK
20: orderLink {
20: resultPath = DetailPageURL
20: value = Order via Amazon...
20: }
23: }
24: }
Customzing HTML template¶
To create your HTML template you only have to create a file. The only fixed content of this file is:
<!-- ###AMAZONITEM### begin →<!-- ###AMAZONITEM### end →
Between these markers it's up to you what to insert. To insert a marker, take your item names from TypoScript, make them uppercase and surround them with ###. That's it. Here comes an example using the items from the above section:
<!-- ###AMAZONITEM### begin -->
<div class="amazon-item”>
###ASIN###
###ORDERLINK###
###IMAGE###
</div>
<!-- ###AMAZONITEM### end -->
Known problems¶
none
ToDo list¶
Nothing to do (send in your requests).
Changelog¶
- 0.0.1: First upload
- 0.0.3: First working version
- 0.0.4: Added localization support!
- 0.0.5: Added template support / added more configuration options / revised code
- 1.0.0: First public version / added documentation
- 1.5.0: Added support for AWS Access Keys
- 2.0.0: Dropped support for old developer token / ensured PHP5 compatibility / changed SOAP requests with REST requests due to higher flexibily and speed / changed fixed template markers with dynamic template markers
- 2.1.0: Added automatic cleaning of markers, left in extension output
- 2.2.0: Added new template version (version 2) for more flexibility
- 2.2.1: Updated documentation
- 2.2.2: Updated documentation
- 3.0.0: Added signature to request / added LIST mode / added TypoScript-able image output / updated HTML template
- 3.0.1: Fixed static template. Fixed sample HTML template.
- 3.0.2: Fixed/updated static template and HTML sample.
- 3.1.0: Updated static TS to make more compatible with existing installations. Added new item type (REGISTER) to pass on values via "register:myValue"
- 3.2.0: Added compatibility mode to automatically support old style HTML templates
TM ASIN Search - 6