.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ============== 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: TM ASIN Search ============== Extension Key: tm\_asinsearch Copyright 2005-2009 Lars Thalheim, 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: 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: Introduction ------------ .. _What-does-it-do: 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: 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: 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 :sup:`th` 2009 - From now on you can also define and modify the output of the product images .. _What-s-new: 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: Screen shots ^^^^^^^^^^^^ [Fill in screen shots here] .. _Administration: Administration -------------- .. _Installation: 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: 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 :sup:`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 :sup:`th` 2009. .. _Install-the-extension: 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: 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: 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: 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/ `_ .. _Configuration: Configuration ------------- .. _Configuration-parameters: Configuration parameters ^^^^^^^^^^^^^^^^^^^^^^^^ [plugin.tx\_tmasinsearch\_pi1] .. ### BEGIN~OF~TABLE ### .. _accessKey: accessKey """"""""" .. container:: table-row 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: secretAccessKey """"""""""""""" .. container:: table-row 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: associateId """"""""""" .. container:: table-row 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: wsdlFile """""""" .. container:: table-row 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: locale """""" .. container:: table-row 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: resultType """""""""" .. container:: table-row 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 .. ###### END~OF~TABLE ###### .. ### BEGIN~OF~TABLE ### .. _templateFile: templateFile """""""""""" .. container:: table-row 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: mode """" .. container:: table-row 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: asin """" .. container:: table-row 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: asinList """""""" .. container:: table-row 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: debug """"" .. container:: table-row 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: forceImageCopy """""""""""""" .. container:: table-row 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: items """"" .. container:: table-row Directive items Data Type [ITEMS] Description This contains the definition of your template markers. d .. ###### END~OF~TABLE ###### 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 =
|
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: Configuration types ^^^^^^^^^^^^^^^^^^^ The following types can be used: .. ### BEGIN~OF~TABLE ### .. _TEXT: TEXT """" .. container:: table-row 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: LINK """" .. container:: table-row 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: IMAGE """"" .. container:: table-row 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: GIFBUILDER """""""""" .. container:: table-row 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: REGISTER """""""" .. container:: table-row 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. .. ###### END~OF~TABLE ###### 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: ((generated)) """"""""""""" .. _Example-Configuration-of-all-options: 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: Customzing HTML template ^^^^^^^^^^^^^^^^^^^^^^^^ To create your HTML template you only have to create a file. The only fixed content of this file is: