=========================================================================== PIRANHA FEED: Version 2.50 Copyright (C) 2002-2004, Answers 2000 Limited: http://www.scriptrocket.com/ ***** WARNING ****** Redistribution or reverse engineering of any part of this product is strictly forbidden. Removal or modification of this copyright notice and warning is also strictly forbidden. This product may only be used on the authorised user's web site. For further information, including full Terms and Conditions, please see the License Agreement. Any violation of the above, or any of the Terms and Conditions specified in the License Agreement, may result in severe civil and criminal penalties, and will be prosecuted to the maximum extent possible law. ============================================================================ TABLE OF CONTENTS ================= 1. WELCOME (A) ADVANTAGES OF USING PIRANHA FEED (B) ABOUT PIRANHA FEED (C) VERSION HISTORY 2. FILES INCLUDED IN THIS DISTRIBUTION (A) FILES TO UPLOAD TO YOUR WEB SITE (B) WORKING EXAMPLES (C) DOCUMENTATION FILES 3. INSTALLATION (A) SYSTEM REQUIREMENTS (B) BEFORE YOU START (C) INFORMATION TO GET FROM YOUR WEB HOST (D) AMAZON "BASIC" XML vs WEB SERVICES + DEVELOPER TOKENS (E) ENTERING BASIC CONFIGURATION (F) UPLOADING FILES (G) INITIALIZING THE DATABASE (H) NOTES ON UPGRADING BETWEEN PIRANHA VERSIONS 4. CACHING AND SEARCH RESULTS (A) DATA FEEDS AND CACHING (B) IMPLICATIONS OF CACHING 5. INTEGRATION WITH PHP PAGES (A) EMBEDDING AMAZON PRODUCTS IN A PHP PAGE (B) ROTATING AMAZON PRODUCTS IN A PHP PAGE (C) EMBEDDING AMAZON BROWSE LISTINGS IN A PHP PAGE (D) CREATING A SEARCH FORM (E) SEARCH TEXT LINKS (F) MULTIPLE SEARCHES ON ONE PHP PAGE 6. INTEGRATION USING OTHER PAGE TYPES USING JAVASCRIPT (A) EMBEDDING AMAZON PRODUCTS IN AN HTML (etc.) PAGE (B) ROTATING AMAZON PRODUCTS IN AN HTML (etc.) PAGE (C) EMBEDDING AMAZON BROWSE LISTINGS IN A HTML (etc.) PAGE (D) AUTO-SEARCH JAVASCRIPT 7. CUSTOMIZING THE RESULTS APPEARANCE + CONTENT (A) CUSTOMIZING THE FORMAT (B) ADVANCED: CONTROLLING TABLE OUTPUT (C) ADVANCED: MULTIPLE FORMATTING OPTIONS (D) ADVANCED: PRICE DISPLAY CALLBACK (E) ADVANCED: HTML MODIFICATION CALLBACKS (F) ADVANCED: CACHE FILTERING 8. CONNECTIVITY ISSUES (A) THE INTERNET IS NOT 100% RELIABLE ============================================================================ 1. WELCOME ========== Welcome to Piranha Feed, a powerful script that allows you to easily integrate Amazon product listings (using the Amazon.com associate program and Amazon's data feeds) into your web site. (A) ADVANTAGES OF USING PIRANHA FEED ------------------------------------ Some of the advantages of using Piranha Feed include: * Include links to relevant Amazon products into your web pages. * Products links are always current because data comes directly from Amazon. * Customise the content, appearance and style of links to suit your site. * Automatically rotate different Amazon product listings in your pages pages. * Supports Amazon product categories. * Integrate searches of Amazon's product range directly into your web pages. Visitors do not leave your site until they have selected a product of interest. This allows you to show Amazon's products along side your own content and/or increase the number of banner impressions your site could generate. If your site has a search engine, you can even include the Amazon links along side your own search results! * Provide searches either for a specific product category or combine results from multiple product category. * Easily plugs relevant Amazon product links into both your own PHP pages, and pages made using other techniques such as HTML/CGI/SHTML/ASP/etc. (non-PHP pages require JavaScript enabled web browser). * Amazon serves images for the data feeds used by Piranha Feed. Stop wasting time cutting and pasting product-images. Better yet, save your bandwidth! * Piranha Feed uses a sophisticated caching mechanism for maximum speed and minimum bandwidth usage. We are aware that Piranha Feed is not the only product on the market designed to help Amazon associates with integration of Amazon.com product listings. Some advantages of Piranha Feed may include: * Piranha Feed is low cost. * Piranha Feed is easy to integrate into existing web pages and has a range of integration options. * Piranha Feed uses Amazon's fully documented interfaces. * Amazon support and encourage the use of their data feeds. In their associates' members area, you find they actively encourage you to interface to it. (B) ABOUT PIRANHA FEED ---------------------- Piranha Feed is developed by and Copyright (C) 2002-2004, Answers 2000 Limited and sold from our web site: http://www.scriptrocket.com/ Answers 2000 Limited owns a number of web sites. For additional information about our company, including a list of all active web sites, please visit our main corporate web site: http://www.ans2000.com/ While Piranha Feed uses Amazon.com's data feeds interfaces and is intended to assist members of Amazon's associates program, this program has not been endorsed by Amazon.com. All use of this product is subject to the Terms and Conditions stated in our license agreement, which is in the file LICENSE.TXT. (C) VERSION HISTORY ------------------- In this section of the manual we describe the version history of Piranha Feed. The version you have downloaded is: 2.50 1.02 Initial version. Supports Amazon XML interface. Released early May 2002 2.00 Supports Amazon XML interface and Amazon web services user interface (webmaster can choose which interface to use - see notes below). Released late August 2002. 2.10 Changes are assumed in both the software and documentation, where applicable, for the items below. Bug Fix: If doing a browse (not keyword) search with Web Services (not basic XML feed) and hardlinks turned off, the developer token was incorrectly passed in the URL link. We are not currently aware of any adverse effects caused by this. Bug Fix: Amazon *sometimes* seems to encode ampersand character in data feeds with hex coding, as %26. While we are not sure if this is correct, and as far as we can tell it doesn't have an adverse effect. We have added a parameter, $c_a2kpf_amazon26, which enables translation of this sequence in link URLs to the standard & character. By default this translation is turned off in the configuration file. A full explanation is in section 7(A). Bug Fix: $c_a2kpf_oborder incorrectly appeared in both the documentation and this file as $c_a2k_pf_oborder. The overall result was fiddling with this variable (to remove the overall border) probably didn't have the result you expected. Bug Fix (Cosmetic Enhancement): If a product has no author, and descriptions were enabled, the product description included a set of empty brackets (). Enhancement For Advanced Users: Split a2kpf_code.inc.php into 2 additional files. This potentially allows more than one set of Amazon results on the same page. We have added a very simple example - pfexample5f_1.php Enhancement For Advanced Users: Cache filtering callback function added. Enhancement For Advanced Formatting: Added additional configuration parameters: $c_a2kpf_otwidth, $c_a2kpf_otcellwidth, and $c_a2kpf_itwidth Documentation only: See additional note about $c_a2kpf_amazonhardlink Enhancement: Created new configuration parameter, $c_a2kpf_amazonbase2 2.11 Documentation only: Updated this file. License only: Made some minor edits. 2.50 Changes to work with a separate settings file for XML connections. This file is called a2kpf_connect.inc.php. This file can be modified to connect to other Amazon.com web sites (including international sites) which provide web services support. Don't not attempt this unless you know what you are doing! We have NOT fully tested with any version except Amazon USA, and do NOT promise it will work in these cases. Additionally this file can be modified if Amazon upgrade their XML interface URL (which has happened before, more than once) to allow the software to work with new Amazon versions. Minor changes at Amazon.com can be accommodated in this way, but no guarantees if Amazon completely redesigns their interface! ============================================================================ 2. FILES INCLUDED IN THIS DISTRIBUTION ====================================== This product should contain the following files: (A) FILES TO UPLOAD TO YOUR WEB SITE ------------------------------------ The following files contain the Piranha Feed "engine", and need to be installed on your web site for the product to function correctly. a2kpf_auto.js a2kpf_config.inc.php a2kpf_code.inc.php a2kpf_code1.inc.php a2kpf_code2.inc.php a2kpf_connect.inc.php a2kpf_piranha.gif a2kpf_install.php a2kpf_search.php (B) WORKING EXAMPLES -------------------- The following files contain working examples of different pages that make use of Piranha Feed. You can upload these files to your web site to see them in action if you wish, but, beyond this, they are not required for the product to operate correctly. pfexample5a_1.php pfexample5a_2.php pfexample5a_3.php pfexample5b_1.php pfexample5b_2.php pfexample5c_1.php pfexample5d_1.htm pfexample5d_2.php pfexample5e_1.htm pfexample5e_2.php pfexample5f_1.php pfexample6a_1.htm pfexample6a_2.htm pfexample6b_1.htm pfexample6b_2.htm pfexample6c_1.htm pfexample6d_1.htm (C) DOCUMENTATION FILES ----------------------- The following files contain the Piranha Feed product documentation in plain text format. You may wish to print this out, or you can view them in a text editor such as NotePad or DOS EDIT. You do not need to install these files on your web site. license.txt readme.txt ============================================================================ 3. INSTALLATION =============== (A) SYSTEM REQUIREMENTS ----------------------- To use these scripts you will need a web host which supports PHP version 4, and has the MySQL database. If your web host does not provide these facilities, or you don't currently have web hosting, you can find a searchable directory of web hosts at http://www.webhostingpicks.com/ (B) BEFORE YOU START -------------------- Make a safe copy of all files before beginning work. We strongly recommend you take a copy of all the files in this package on to another location that your hard-disk (such as a floppy disk) and store it in a secure location such as a fire-proof safe. (C) INFORMATION TO GET FROM YOUR WEB HOST ----------------------------------------- Piranha Feed requires a MySQL database in order to function properly. In order for Piranha Feed to connect to the MySQL database on your web site, you need the following four pieces of information from your web host: 1. Your MySQL user name 2. Your MySQL password 3. Your MySQL database name 4. The host name for your MySQL database. If the MySQL database is on the same machine as your web server, you should be able to simply enter 'localhost'. (D) AMAZON "BASIC" XML vs WEB SERVICES + DEVELOPER TOKENS --------------------------------------------------------- Amazon.com's associate program supports 2 different interfaces for retrieving data from their site: 1. A "basic" Amazon XML Feed (announced in an e-mail to their Associates approximately April 2002). 2. Amazon Web Services (announced in an e-mail to their Associates in July 2002). The Amazon Web Services interface (2) effectively supersedes the original Amazon "basic" XML Feed (1). The term "basic" is our term, as the original Amazon XML Feed (1) is somewhat basic in terms of functionality as compared to the rich functionality provided by Amazon's Web Services (2). We contacted Amazon.com (early August 2002) and they confirmed they intended to continue to support the "basic" XML Feed (interface 1), although they did not plan to make further enhancements to it. Piranha Feed version 2.00 (you are using version 2.50) can work with either interface: there is a simple switch in the configuration file. We recommend that you use the Web Services interface (interface 2), as some users have reported intermittent problems accessing the "basic" XML Feed URL - this can cause empty results to sometimes be returned especially from the Browse function. To use the Amazon Web Services, you will need to obtain a "Developer's Token" which is a string of alphanumeric characters. (You do not need a Developer's Token to use their XML feed interface). Obtaining a Developer's Token is easy: 1. Go to the members' area at http://associates.amazon.com/ and you will find a link to sign-up (free) for a Developer's Token. Follow the instructions and you will be given the token via e-mail. 2. After you have the Token, keep very careful note of it (print it!), as you will need it later. 3. After signing up for the Token, Amazon gives you the option to download their Developer's toolkit. You can download it if you want to (it contains documentation for programmers on how to use their Web Services interface), however you do NOT need to download or use the toolkit to use Piranha Feed (Piranha Feed is completely self-contained). In version 2.00 of Piranha Feed, the functionality provided by Piranha Feed is identical regardless of which interface you use (of course with the proviso about possible connection problems to the XML feed interface referred to earlier). Future versions of Piranha Feed may either require use of the Web Services interface and/or may provide additional functionality to users of the Web Services interface. (E) ENTERING BASIC CONFIGURATION -------------------------------- 1. Find out the four connection parameters for the MySQL database as described above. 2. (Optional but recommended), obtain a Developer's Token for Amazon.com's Web Services interface by signing up for in the Associates' members area as described above. 3. Choose a password for the Piranha feed administration functions. 4. Using a plain text editor (example: Windows Notepad, DOS EDIT, etc.) to edit the file a2kpf_config.inc.php. Fairly near the top of the file, immediately after the introductory comments, you will find places to enter the interfaces (Web Services or "basic" XML feed): // (v2) How to connect to Amazon // - set to 1 to use Amazon's "basic" XML interface // - set to 2 to use Amazon's Web Services interface $c_a2kpf_amconnect = 2 ; // (v2) Developer Token // - this is your developer token you get from Amazon's associates // area. This parameter is only used if you set $c_a2kpf_amconnect // to 1. The "legacy" XML interface ignores this option. $c_a2kpf_amdevtoken = 'insert_your_developer_token' ; Leave $c_a2kpf_amconnect set to 2 if you plan to use the Web Services interface (recommended). *********************************************************************** NOTE: As of approximately Summer 2004, Amazon no longer seems to have the legacy XML interface enabled. Therefore Piranha probably won't work if you set a2kpf_amconnect to 1. Check with Amazon if you are unsure, or better yet simply use the setting of 2! *********************************************************************** If you are using the Web Services interface, you also need to set the value in the quotes for $c_a2kpf_amdevtoken to the Developer Token you obtained from Amazon. For example, if you Amazon told you that you token was ABCDEF12345 (don't enter this it's just an example! Use the value Amazon gave you!) the line would become: $c_a2kpf_amdevtoken = 'ABCDEF12345' ; If you prefer to use the "basic" XML feed (the slightly older interface) you should set $c_a2kpf_amconnect to 1, but you do not need to modify (or obtain the Developer's Token). This is NOT recommended because we are not certain Amazon supports this older interface as of Summer 2004. *********************************************************************** NOTE: As of approximately Summer 2004, Amazon no longer seems to have the legacy XML interface enabled. Therefore Piranha probably won't work if you set a2kpf_amconnect to 1. Check with Amazon if you are unsure, or better yet simply use the setting of 2! *********************************************************************** Just after this section, you will find places to enter five essential pieces of information that Piranha Feed needs to work (the 4 MySQL settings, plus your chosen Piranha Feed administration password). For example: the default Piranha Feed administration password is sesame, and looking in a2kpf_config.inc.php you should find the following lines: // piranha feed administration password $c_a2kpf_ppassword = 'sesame' ; If for example, you wanted the administration password to be "secret", you would change these lines to: // piranha feed administration password $c_a2kpf_ppassword = 'secret' ; When you make edits, it is very important that you: * Get the quotes right (enclose the values in single quote characters) * Always end the line with a semicolon (;), as shown in the above * The majority of parameters are case sensitive: In other words, "secret" is not the same as "Secret" (F) UPLOADING FILES ------------------- Upload these files to your web host using the FTP program (this is all files except for the README.TXT and LICENSE.TXT files) into your public folder (where you place your HTML files). Usually, but not always, this folder has a name such as "docs", "www" or "public_html" - if you are not sure which folder to use, you will have to ask your web host. a2kpf_auto.js a2kpf_config.inc.php a2kpf_code.inc.php a2kpf_code1.inc.php a2kpf_code2.inc.php a2kpf_connect.inc.php a2kpf_piranha.gif a2kpf_install.php a2kpf_search.php (G) INITIALIZING THE DATABASE ----------------------------- After you have completed the upload, use your web browser to access the a2kpf_install.php page. For example, if your web site URL is http://www.yoursite.com/ then you should browse to: http://www.yoursite.com/a2kpf_install.php If everything is correct, you should see the log-in page for the administration functions. * If you get a page not found error in your web browser: you have either typed the wrong URL into your web browser, not uploaded the files correctly, or uploaded the files to the wrong folder on your web site. Check you entered the correct URL in your web browser, and if necessary go back to the "UPLOADING FILES" step. * If you get a PHP error in a2kpf_config.inc.php, you have made a basic when editing this file, such as mismatched quote, missing a semicolon. etc. Go back to the step called "ENTERING BASIC CONFIGURATION" and recheck your edits. Once you successfully are able to access the Piranha Feed administration page using your web browser, log-in using your Piranha Feed administration password, and you should now be presented with a menu with the following options: * Create Cache Tables * Clear Cache Tables * Log Out Click the option called "Create Cache Tables" * If you get an error indicating the script could not connect to the database, this means you have not entered the MySQL connection parameters correctly. In this event go back to "ENTERING BASIC CONFIGURATION" and repeat the process from there. Once you have created the cache tables, click "Go Back To Menu" and then click Log Out from the menu. NOTE: If you successfully create the cache tables once, and then you try to create them again, you WILL get an error the 2nd time saying the tables exist. This is to be expected, and does not cause any problems. (H) NOTES ON UPGRADING BETWEEN PIRANHA VERSIONS ----------------------------------------------- We recommend the following procedure for upgrading between Piranha Feed versions: 1. Make a safe copy of your current a2kpf_config.inc.php file 2. Overwrite ALL the old versions of the Piranha Feed files with the new version. 3. Copy any edits you have made in your old a2kpf_config.inc.php into the new version of this file. (You can simply continue using your old configuration file, as the new configuration file may include additional settings not present in your older version). 4. Use the Administration script to clear the cache (see below). ============================================================================ 4. CACHING AND SEARCH RESULTS ============================= (A) DATA FEEDS AND CACHING -------------------------- This product uses Amazon.com's data feeds to retrieve product information from Amazon.com. Accessing the data feeds is a network operation, and hence relatively time-consuming (as compared to a local server operation). To reduce bandwidth usage and boost speed, Piranha Feed, uses a caching algorithm to avoid repeatedly retrieving the same information from Amazon. Caching means that when the user does a search, Piranha Feed retrieves matching results across the network from Amazon.com, just once, stores a local copy on your web server (Piranha Feed uses a MySQL database for this local copy), and whenever possible uses this local copy of the search results. Eventually this local copy will get out of date, so the cached information is discarded automatically as this happens. (B) IMPLICATIONS OF CACHING --------------------------- While caching provides a major performance boost for the script, and is completely transparent to the user, it does have some important implications to you as the administrator: 1. How long are items cached: This is specified, in seconds, by the $c_a2kpf_scachetime parameter in a2kpf_config.inc.php. By default, this is set to 3600 (which is the number of seconds in one hour - 60 X 60 = 3,600). Amazon's guidelines for XML currently recommend a maximum cache time of one hour, so we do not recommend increasing this value (otherwise you would not only be breaking their guidelines, but might even be displaying information about products which are no longer available). In most situations, you should NOT need to decrease $c_a2kpf_scachetime. However, if you are running low on disk space, then decreasing this variable's value is a way to save space. Out-of-date items are removed from the cache automatically each time a search is done, so after editing this variable's value, simply do a search (or you can clear the cache nanually using the administration interface provided by a2kpf_install.php). 2. Clearing the cache manually: You can empty the cache of all contents using the "Clear Cache Tables" tables option in the a2kpf_install.php script. 3. Product categories: Searches for products at Amazon can be across a single product category (such as VHS videos, books, software, baby-products, etc.) or across "all" product categories. When performing a search across "all" product categories, Piranha Feed actually goes through each product category, one-by-one, and attempts to find matches. The reason "all" is in quotes, is you can configure the "all" search to skip over certain categories, and/or to go through the categories in an order of your choice. If you look in a2kpf_config.inc.php, you will find a variable called $c_a2kpf_scatorder which contains a comma-separated list of the categories to search for an "all" category search. If you want to search the categories in a different order, or never display results from a particular product-category, you can edit this parameter. For example, if you never wish to display Baby products, you could remove "baby" from this line. 4. Number of matches: There are two parameters in a2k_config.inc.php which control the maximum number of matches to retrieve from a search: $c_a2kpf_smodemax (default value of 4) specifies the maximum number of matching items to show from a particular product category. $c_a2kpf_sallmax = 20 (default value of 20) specifies the number of items that must be found, across all categories so far searched in an "all" category search, before no longer searching additional categories. This is almost, but not quite the same as saying the maximum number of items to be found, an example will show why it is not exactly the same. Imagine that you do an "all" category search, with the two parameters set at their default values: + For "books", you find 4 matches, total items so far is 4, this is less than 20 items, so the search continues. + For "software", you find 4 matches, total items is now 8, this is less than 20 items, so the search continues. + For "magazines", you find 4 matches, total items is now 12, this is less than 20 items, so the search continues. + For "music", you find 4 matches, total items is now 16, this is less than 20 items, so the search continues. + For "videogames", you find only 3 matches, total items is now 19, this is still less than 20 items, so the search continues. + For "electronics", you find 4 matches, bringing the total up to 23 items. This is more than 20 items, so only now do we stop searching additional categories. Additionally, as search results are cached, editing $c_a2kpf_smodemax and/or $c_a2kpf_sallmax may not produce an immediate change in the results. So, after editing either of these parameters, we recommend that you clear the cache to avoid confusion. ============================================================================ 5. INTEGRATION WITH PHP PAGES ============================= (A) EMBEDDING AMAZON PRODUCTS IN A PHP PAGE ------------------------------------------- This option allows you to include search results from Amazon easily into your web site's pages, each page containing the results of a particular predefined search. This is similar to cutting and pasting individual Amazon product links into your web pages, except: * You don't have to bother finding the products yourself and using the Amazon associates' link generator to generate the correct code. * You don't have to worry about the product links getting out of date. Current Amazon products that match your chosen search criteria are automatically displayed. * Instead of having to manually copy the title and cover for each product, including formatting HTML etc., you simply need to include 4 or 5 lines of code in each page. Step 1: Create the HTML / PHP code for your basic page (without the Amazon products), and save it with a .php extension, example: mypage1.php Step 2: At the point where you wish to include Amazon products, create a section of PHP code (enclosed within the PHP brackets ). In this PHP code, create PHP variables ($pfs and $pfm) which specify the search term and the product category for the Amazon products to include: * $pfs is the search term. * $pfm, which can be omitted, is the product category, such as "books". A list of the categories can be found in the a2kpf_config.inc.php file. If you do not define $pfm, the search will be of "all" product categories. After defining these two variables, include a2kpf_search.php Here is an example of a PHP code fragment to list "internet marketing" products from the "books" product category: Here is an example of a PHP code fragment to list "internet marketing" products from the "vhs" (VHS = videos) product category: Here is an example of a PHP code fragment to list "internet marketing" products for "all" categories (notice $pfm is not assigned): Step 3: Use your FTP program to upload your completed page to your web host, and view it in your web browser. Step 4: (Optional Advanced) The above examples all hard-code the type of search into the page's code. In other words for the particular page the search performed is always the same (the search results and which products are listed will vary from time to time depending on which products Amazon returns via their data feeds for that particular result). If you have other PHP code in your page, for example to perform an Internet search, etc., you could create PHP code to assign the values of $pfs and/or $pfm dynamically from other code in your page. WORKED EXAMPLES There are 3 complete working examples of the above techniques included with the distribution: * pfexample5a_1.php - demonstrates a search for chess / books * pfexample5a_2.php - demonstrates a search for chess / all products * pfexample5a_3.php - same as pfexample5a_2 but with different formatting (B) ROTATING AMAZON PRODUCTS IN A PHP PAGE ------------------------------------------ This is similar to option 5(A) [above] except the results of a number of predefined searches are randomly rotated. Step 1: Create the HTML / PHP code for your basic page (without the Amazon products), and save it with a .php extension, example: mypage2.php Step 2: At the point where you wish to include Amazon products, create a section of PHP code (enclosed within the PHP brackets ). In this PHP code, create PHP variables ($pfr and $pfm) which specify the search terms and the product category for the Amazon products to include: * $pfr is a backslash-separated or comma-separated list of possible search terms. (either backslashes or commas can be used and have the same effect, the reason for allowing backslashes is that they are more convienent when specifying parameters in a URL) * $pfm, which can be omitted, is the product category, such as "books". A list of the categories can be found in the a2kpf_config.inc.php file. If you do not define $pfm, the search will be of "all" product categories. After defining these two variables, include a2kpf_search.php Here is an example of a PHP code fragment to rotate the results of "internet marketing", "affiliate programs" and "copy writing" products from the "books" product category: Here is an example of a PHP code fragment to rotate the results of various popular sports-related products for "all" categories (notice $pfm is not assigned): Step 3: Use your FTP program to upload your completed page to your web host, and view it in your web browser. WORKED EXAMPLES There are 2 complete working examples of the above techniques included with the distribution: * pfexample5b_1.php - demonstrates a search for various sports + books * pfexample5b_2.php - same as pfexample5b_1 but with different formatting (C) EMBEDDING AMAZON BROWSE LISTINGS IN A PHP PAGE -------------------------------------------------- This option allows you to embed products generated by Amazon (example: Top Selling Books) easily into your web site's pages, each page containing the results of a particular browse listing. This is somewhat similar to using the "Amazon Recommends" links in the Amazon associate area, but whereas the "Amazon Recommends" links require a JavaScript enabled browser (and substitutes a banner if the user doesn't have a JavaScript enabled browser), the Piranha Feed PHP implementation works on all web browsers. Additionally with Piranha Feed you get more control over the layout, content and appearance of the product listings. Step 1: Log-in to the Amazon associates area and locate a browse link. At the time of writing, Amazon's associates area does not appear to contain very clear instructions (or any?) instructions on how to do this. This work round, works for us: (i) Generate an "Amazon Recommends" link type (ii) At the end of the procedure you will be given a large chunk of HTML code, which contains a SCRIPT tag (plus a lot of other stuff). (iii) Look carefully at the URL contained with the SRC= parameter of the SCRIPT tag, and make a note of the values in the URL following browse= (a number), and mode= (a product category). Step 2: Create the HTML / PHP code for your basic page (without the Amazon products), and save it with a .php extension, example: mypage3.php Step 3: At the point where you wish to include Amazon products, create a section of PHP code (enclosed within the PHP brackets ). In this PHP code, create PHP variables ($pfb and $pfm) which specify the browse and the product category for the Amazon products to include: * $pfb is the browse number * $pfm, which is required in this case, is the product category, such as "books". After defining these two variables, include a2kpf_search.php Here is an example of a PHP code fragment to list browse category 1000 products from the "books" product category (this is Top Selling Books): Step 4: Use your FTP program to upload your completed page to your web host, and view it in your web browser. WORKED EXAMPLES There is a complete working example of the above techniques included with the distribution: * pfexample5c_1.php - demonstrates display of best-selling books (D) CREATING A SEARCH FORM -------------------------- This is very much like the standard search form that Amazon provides except the results are returned as part of a page on your web site (which could, for example, including your banners or other material as part of the page). Step 1: Create the HTML / PHP code for your basic page (without the Amazon products), and save it with a .php extension, example: mypage4.php Make a note of the name of the file name as you will need this for the next two steps. Step 2: At the point at which you would like the results to appear in the page include the following lines: Step 3: You need to make an HTML form, which allows the user to select the product category and search term, and links to your search results page (from step 1 and 2): * A form field, named "pfs" contains the search term * A form field, named "pfm" contains the product category. A list of the categories can be found in the a2kpf_config.inc.php file. If you do not include pfm, or allow it to be set to an empty string, this will indicate the search will be of "all" product categories. * The ACTION field in the FORM tag contains the results page (from step 1 and 2). If the page containing the search form is in the same folder as the results page, you can simply give the name of the results page, for example: ACTION="mypage4.php". If however, the page containing the search form is in a different folder (or even a different web site) than the results page, you will need to give the full URL to the results page for example: ACTION="http://www.yoursite.com/mypage4.php". * The form code can be included (but not the results) can be included on any type of web page, not just .php pages. Here is an example of the HTML code fragment for a form that links to a results page called mypage4.php
Search for:


Product Category:


Step 4: Paste the HTML form code from step 3 into as many web pages as you would like. Step 5: Use your FTP program to upload your completed pages to your web host, and view them in your web browser. WORKED EXAMPLES There is a complete working example of the above techniques included with the distribution: * pfexample5d_1.htm - contains various search forms * pfexample5d_2.php - the search results (E) SEARCH TEXT LINKS --------------------- You can use the methods described in 5(A) and 5(C) to create a page which always displays a given set of Amazon results - i.e. the search is predefined. You can use the method descirbed in 5(B) to create a page which rotates different combinations of predefined searches. But what if you want to make a single page which could display the results of different searches depending on how the user linked to that page? Search text links provide the answer to this challenge. Step 1: Create the HTML / PHP code for your basic page (without the Amazon products), and save it with a .php extension, example: mypage5.php Make a note of the name of the file name as you will need this for the next two steps. Step 2: At the point at which you would like the results to appear in the page include the following lines: Step 3: On your other pages (which can be any type of page, they do not need to be PHP pages), you need to make hyperlinks to the page you created earlier (in this mypage5.php) passing the search parameters in the URL query string. * If you want to link to the page telling it to perform a search for all products, set pfs= in the query string. Use + signs instead of spaces. (We strongly recommend that you use only letters and numbers as part of this parameter). Here is an example of how to link including a search for "internet marketing", all product categories: Internet Marketing * If you want to link to the page telling it to perform a search for a particular product category, you need to pfs= (as above), plus also set pfm= to the product category. Here is an example of how to link including a search for "internet marketing" books: Internet Marketing Books * You can also use a combination of pfr= (and optionally pfm=) to rotate different results. For pfr= use the / character to rotate different searches, and + signs instead of spaces to perform the query. Here is an example of how to rotate "baseball" and "football" products: Baseball or Football Here is an example of how to rotate "baseball" and "football" books: Baseball or Football * You can also use a combination of pfb= and pfm= to do Browse listings in the final page (similar to 5(C)). Here is an example of how to link including a search for best-selling books (pfb=1000) in the query string Best sellers Finally, one noteworthy point - you can even make a page link to itself (each time doing a different search) using this technique. Step 4: Paste the text links from step 3 into as many web pages as you would like. Step 5: Use your FTP program to upload your completed pages to your web host, and view them in your web browser. WORKED EXAMPLES There is a complete working example of the above techniques included with the distribution: * pfexample5e_1.htm - contains various text links * pfexample5e_2.php - the results page, with more text links (F) MULTIPLE SEARCHES ON ONE PHP PAGE ------------------------------------- This is new (advanced) feature that we have added for more advanced users in version 2.10. You will need a basic understanding of PHP if you wish to use this feature. As of 2.10 it is now possible to display more than one set of search results on a single page. Step 1: Create the HTML / PHP code for your basic page (without the Amazon products), and save it with a .php extension, example: mypage5.php Make a note of the name of the file name as you will need this for the next two steps. Step 2: Somewhere in the page you must set up the 1st search parameters using PHP code of your own design. $pfs and $pfm (for a keyword search) OR $pfb and $pfm (for a browse search) At the point at which you would like the 1st set of results to appear in the page, include the following lines: Next you must set up the first 2nd parameters using PHP code of your own design. Note: If you switch between browse and keyword search, you must also reset the unused parameters $pfb/$pfs to an empty string, or unset them. $pfs and $pfm (for a keyword search) OR $pfb and $pfm (for a browse search) At the point at which you would like the 2nd set of results to appear in the page include the following lines: Step 3: Use your FTP program to upload your completed pages to your web host, and view in your web browser. WORKED EXAMPLES There is a complete (but short) working example of the above techniques included with the distribution: * pfexample5f_1.php - hard-coded, 2 searches in one page SUPER ADVANCED TIP Before including a2kpf_code2.inc.php, you could also include additional code to modify the configuration parameter variables. For example to change the style or layout. Be cautious about changing parameters which affect the caching or how many items to cache, as this can lead to odd effects, if for example the results of a previous search are cached (you end up getting too many or too few results). ============================================================================ 6. INTEGRATION USING OTHER PAGE TYPES USING JAVASCRIPT ====================================================== (A) EMBEDDING AMAZON PRODUCTS IN AN HTML (etc.) PAGE ---------------------------------------------------- Method 5(A) is, quite simply, the best way to incorporate Amazon product links into a page, as the results will always be current, the page will work for all web browsers and regardless of the user's web browser settings. That said, sometimes you may wish to include search results in a page, which is not a PHP page, for example: the page may be generated dynamically from a Perl CGI script, or you may want to incorporate to incorporate Amazon products in an existing HTML page, etc. The JavaScript embedding option allows you to incorporate Amazon products even into non-PHP pages, however the limitation of this option is that the user must have a JavaScript enabled browser for this function to work (otherwise no results will be incorporated). Step 1: Create the HTML for your basic page (without the Amazon products), or choose a pre-existing HTML page to work on. Step 2: At the point where you wish to include Amazon products, add something like the following line: or In the JavaScript SRC= link: * pfs is the search term. You may use letters and numbers in the search term, and use the plus-sign (+) instead of spaces. For example, to search for "internet marketing", set pfs to "internet+marketing". * pfm is the product category to search, although this can be omitted if you wish to search "all" product categories. A list of the categories can be found in the a2kpf_config.inc.php file. Step 3: Use your FTP program to upload your completed/updated page(s) to your web host, and view them in your web browser. WORKED EXAMPLES There are complete worked examples of the above techniques: * pfexample6a_1.htm - hockey books * pfexample6a_2.htm - printers, all product categories (B) ROTATING AMAZON PRODUCTS IN AN HTML (etc.) PAGE --------------------------------------------------- This is similar to option 6(A) [above] except the results of a number of predefined searches are randomly rotated. Step 1: Create the HTML for your basic page (without the Amazon products), or choose a pre-existing HTML page to work on. Step 2: At the point where you wish to include Amazon products, add something like the following line: or In the JavaScript SRC= link: * pfr is a backslash-separated list of search terms. You may use letter and numbers in the search term, and use the plus-sign (+) instead of spaces. For example, to rotate searches for "domain names" and "internet marketing", set pfr to "domain+names/internet+marketing". * pfm is the product category to search, although this can be omitted if you wish to search "all" product categories. A list of the categories can be found in the a2kpf_config.inc.php file. Here is an example of a JavaScript fragment to rotate the results of various popular sports-related products for "all" categories (notice pfm is not assigned): Step 3: Use your FTP program to upload your completed/updated page(s) to your web host, and view them in your web browser. WORKED EXAMPLES There are complete worked examples of the above techniques: * pfexample6b_1.htm - sports books rotation * pfexample6b_2.htm - sports all products rotation (C) EMBEDDING AMAZON BROWSE LISTINGS IN A HTML (etc.) PAGE ---------------------------------------------------------- This option allows you to embed products generated by Amazon (example: Top Selling Books) easily into your web site's pages, each page containing the results of a particular browse listing. This is somewhat similar to using the "Amazon Recommends" links in the Amazon associate area, and like the "Amazon Recommends" links requires a JavaScript enabled browser. Step 1: Log-in to the Amazon associates area and locate a browse link. At the time of writing, Amazon's associates area does not appear to contain very clear instructions (or any?) instructions on how to do this. This work round, works for us: (i) Generate an "Amazon Recommends" link type (ii) At the end of the procedure you will be given a large chunk of HTML code, which contains a SCRIPT tag (plus a lot of other stuff). (iii) Look carefully at the URL contained with the SRC= parameter of the SCRIPT tag, and make a note of the values in the URL following browse= (a number), and mode= (a product category). Step 2: Create the HTML for your basic page (without the Amazon products), or choose a pre-existing HTML page to work on. Step 3: At the point where you wish to include Amazon products, add something like the following line: In the JavaScript SRC= link: * pfb is the browse number * pfm is the product category to search, and is required in this case. Step 4: Use your FTP program to upload your completed page to your web host, and view it in your web browser. WORKED EXAMPLES There are complete worked examples of the above techniques: * pfexample6c_1.htm - best selling books (D) AUTO-SEARCH JAVASCRIPT -------------------------- This option is similar to method 6(A) except the search term is automatically generated based on the page title. This can be useful if you want to quickly incorporate Amazon products in a large number of pages, as you can insert the same code in every page. Be warned, if your page titles are not very descriptive, or are very long, the results may not be of a very good quality using this method. Step 1: Create the HTML for your basic page (without the Amazon products), or choose a pre-existing HTML page to work on. Step 2: At the point where you wish to include Amazon products, add something like the following line: Step 3: Use your FTP program to upload your completed/updated page(s) to your web host, and view them in your web browser. WORKED EXAMPLES There are complete worked examples of the above techniques: * pfexample6d_1.htm - auto search based on page title ============================================================================ 7. CUSTOMIZING THE RESULTS APPEARANCE + CONTENT =============================================== The a2kpf_config.inc.php file is a very important file as it contains a lot of information that controls how Piranha feed operates. This information includes: * Your administration password (described in "3. INSTALLATION"). * How to connect your MySQL database (described in "3. INSTALLATION"). * How Piranha Feed caches and limits results (described in "4. CACHING AND SEARCH RESULTS") * A wide range of options that specify how the results are formatted on screen. We will now discuss this last point, how to edit a2kpf_config.inc.php to control the formatting of the Amazon product listings that are incorporated in your site. (A) CUSTOMIZING THE FORMAT -------------------------- Piranha Feed search results are embedded within an HTML table. This is normally set to "100%" width. Using the PHP and JavaScript integration methods described previously you can build a page, which uses another table to control the width of the Piranha Feed table ("nested tables"). As of version 2.10, we also introduced another option to control the table formatting by modifying these 3 variables - $c_a2kpf_otwidth, $c_a2kpf_otcellwidth, and $c_a2kpf_itwidth. This explained in section 7(B). The following examples use the nested table technique to give a flavor of what is possible. All these examples involve quite simple formatting, so they are easy to understand - so when you create your real web pages, you should be able to do considerably better than these! * pfexample5a_3.php * pfexample5b_2.php * pfexample5c_1.php Over and above this, Piranha Feed allows you to extensively customize the appearance of the search results. You do this by modifying the settings in a2kpf_config.inc.php (look for the section of the file beginning with "APPEARANCE OF SEARCH RESULTS") Let's review these settings: $c_a2kpf_oborder Specifies whether to add a border around the results. Set to TRUE to add a border, or FALSE to turn off the border. $c_a2kpf_hallenable Specifies whether product category descriptions (e.g. "Books") should be displayed when doing an "all" category search. Set this to TRUE if yes, FALSE if not. $c_a2kpf_hmodeenable Specifies whether product category descriptions (e.g. "Books") should be displayed when doing a search of a particular specified Set this to TRUE if yes, FALSE if not. $c_a2kpf_hbgcolor Specifies the background color for product category descriptions. Specify the color using HTML color codes, and do NOT forget the initial hash sign. If you need a HTML color chart, you can find one at: http://www.hits4me.com/html_color.asp $c_a2kpf_hfontstart $c_a2kpf_hfontend Contain the font tags used to enclose product category descriptions. You can use these to control the choice of font, the color and size of the font, etc. $c_a2kpf_hspacerstart $c_a2kpf_hspacerend These contain the HTML code that used to pad out the start and end of product category descriptions. The default values force a blank line above and below the product category description. $c_a2kpf_ibgcolor = '#FFFFFF' ; Specifies the background color for product listings in the results. Specify the color using HTML color codes, and do NOT forget the initial hash sign. If you need a HTML color chart, you can find one at: http://www.hits4me.com/html_color.asp $c_a2kpf_ifontstart $c_a2kpf_ifontend Contain the font tags used to enclose products listed in the results. You can use these to control the choice of font, the color and size of the font, etc. $c_a2kpf_ispacerstart $c_a2kpf_ispacerend These contain the HTML code that used to pad out the start and end of product listings in the results. The default values force a blank line above and below each product listing. $c_a2kpf_icellalign This specifies the horizontal cell alignment for product listings in the results. This can be set to 'LEFT', 'RIGHT' or 'CENTER'. $c_a2kpf_iimage This specify whether product listings in the results should include images. This option can be set to 0 - Do not display the image 1 - Display the larger version of the image 2 - Display the small version of the image Note: Amazon.com provides the images, and we have no control over which images they provide. Although the images are generally very good there are some limitations: * Some products do not have images * Some products have the same image for both the large and small versions. * Many product images are designed to be used, and therefore look best on a white background. $c_a2kpf_ititle $c_a2kpf_idesc $c_a2kpf_iprice These specify whether product listings in the results should include product titles, descriptions and prices. Each option can be set to TRUE (indicating it will be shown) or FALSE (indicating it will not be shown). The image (see above) and title, if shown, are linked to the corresponding Amazon product page, so it is essential to make sure one or both of these is displayed - or otherwise there will be no way for the customer to buy the corresponding product! Amazon does not currently make full product descriptions available via their "basic" XML feed. They do however provide some descriptive information about each product, so a best-guess description field is synthesized automatically from the information made available by Amazon.com. If using version 1.02 of Piranha Feed, the description will always be synthesized. If using version 2.00 of Piranha Feed with the "basic" XML feed interface, the description will always be synthesized. If using version 2.00 of Piranha Feed with the Web Services interface, the description will be synthesized using a slightly different format. As the Web Services Interface provides access to additional product data including user comments etc., we hope that future versions of Piranha Feed will provide more accurate descriptions in a future upgrade. $c_a2kpf_iimagealign = '' ; This specifies the whether images should be displayed along side or above the title/description for each product description. Set this to an empty string to display the image above the text. Set this to 'LEFT' or 'RIGHT' to display the image to the left or right of the text. If you use the nested tables technique to include your search results in a narrow column, we recommend you set this attribute to blank, or otherwise the results may come out looking rather odd. $c_a2kpf_irowmax Specifies the number of columns to show results. This value must be at least 1. If you use the nested tables technique to include your search results in a narrow column, we recommend you set this attribute to low number or 1, especially if $c_a2kpf_iimage is set to TRUE, otherwise the results may come out looking rather odd. $c_a2kpf_linktarget Specifies the target window for links to Amazon.com. You can set this to '_blank' or '_top'. If you set this to '_blank', links to Amazon.com will open in a new browser window. If you set this to '_top', links to Amazon.com will open in the current browser window. $c_a2kpf_linkhide Specifies whether the status bar should hide link destination URLs in the status bar when the user moves the mouse over them. This feature is implemented using JavaScript, so may have no effect if the user has disabled JavaScript in their browser. Set this to TRUE to hide link destination URLs, or FALSE to allow the user to see the link destination URLs. $c_a2kpf_amazonhardlink If set to FALSE, links to Amazon use the destination URL provided by Amazon's data feeds (the method they advise). If set to TRUE will attempt to convert the link in to an Amazon ASIN product link. Last time we checked: Amazon's usage guidelines say you should use the links provided by their data feeds. But we noticed (2.10 - October 3rd 2002): One of the sample applications that Amazon links to in their web developer's area, itself uses hardlinks (it's the one about Google and WebLogs). Do View Source and see for yourself. It's at: http://mockerybird.com/index.cgi?node=book+watch ....so we are currently uncertain whether it is permissible to change the links to ASIN links. Therefore, we stronglyrecommend that you leave this value set to FALSE unless you have checked with, and got permission Amazon first. $c_a2kpf_amazonbase This is the start of the URL for for Amazon ASIN product hardlinks. Do not modify this value unless you are an expert on hardlinks. If you do modify it: check the code generated carefully or the links may not track or lead to the right destination. $c_a2kpf_amazonbase2 This is the end of the URL for for Amazon ASIN product hardlinks. Do not modify this value unless you are an expert on hardlinks. If you do modify it: check the code generated carefully or the links may not track or lead to the right destination. $c_a2kpf_amazon26 This value only has an effect if hardlinks are NOT enabled. Explanation... If you do NOT enable hardlinks using $c_a2kpf_amazonhardlink, Amazon returns the URL of products as part of their data feed. We have noticed they have *sometimes* begun encoding the & character in the link as %26 which is URL-style hex coding for this character. (By *sometimes*, we mean when we tested several times in the same day, sometimes we got %26 but later we got the &). Presumably they have done this because a simple ampersand is an invalid character in XML data, it should be encoded as & which would be much worse if the decoder forgot to decode it before sending it back to Amazon (it would be a broken link). That said: * We are far from sure (to the best of our knowledge and testing) strictly speaking, that encoding an ampersand that separates URL query string parameters as %26 is correct. (We thought it mean an ampersand _within_ a parameter value) * Regardless of whether or not it is correct, as far as we can tell, Amazon's own site does seems to be able decode the link adequately anyway. We say this on the basis of: (1) It finds the right product [which it would not be able to do if it could not decode the link] (2) It seems highly likely that Amazon anticipate that some/most people would leave the %26 intact - after all the data originates from Amazon in the first place! - Plus it looks like the whole reason for encoding ampersand like this, might be to avoid the whole XML-issue of encoding ampersands as & (3) We we checked: The "Share Your Media Collection with Friends" sample Web Services application which is linked from Amazon's Web Services Demo page definitely leaves the %26s intact. This is at: http://mockerybird.com/web-services/collection/collection-home.cgi Do View Source, and look what it puts in the Title column for the HTML code. In version 2.10 and after, we have added this new configuration parameter which controls whether Piranha Feed translates %26 sequences in product URLs back into ampersands. If set to TRUE, %26s are translated into ampersands. If set to FALSE, %26s are left as %26s As far as we know at the time of writing it has no practical effect on the working of the links or products... The default value is FALSE, which is what one of Amazon's samples is doing, but if you feel it ought to be translated, the option is there. If any reader has any additional information about this let me know. $c_a2kpf_eenable Specifies whether a "no items found" message should be displayed if the current search parameters do not yield any results. Set to TRUE to display the message, or FALSE to simply display nothing if no results are found. $c_a2kpf_ebgcolor The background color for the "no items found" message, if displayed. $c_a2kpf_efontstart $c_a2kpf_efontend Contain the font tags used to enclose the "no items found" message, if it is displayed. You can use these to control the choice of font, the color and size of the font, etc. $c_a2kpf_espacerstart $c_a2kpf_espacerend These contain the HTML code that used to pad out the start and end of the "no items found" message, if it displayed. The default values force a blank line above and below the messsage. $c_a2kpf_etext The text to use for the "no items found" message. $c_a2kpf_penable Specifies whether to add a "prices subject to change" message to the results, if pricing display ($c_a2kpf_iprice) is also enabled. Amazon's guidelines say you must display the text "Amazon.com prices subject to change" somewhere on your web site if you show Amazon's prices. * $c_a2kpf_iprice is TRUE, and you also set this variable to TRUE: the message will automatically be added to the bottom of results from Piranha Feed. * $c_a2kpf_iprice is TRUE, but this this variable is set to FALSE: the message will not automatically be added, but as Amazon's guidelines state you must display the "prices subject to change" message somewhere on your web site, you will need to add that text manually some place on your site. * If $c_a2kpf_iprice is FALSE, pricing information is not displayed, and regardless of the value of this message, the "prices subject to change" message is not added. $c_a2kpf_pbgcolor The background color for the "prices subject to change" message, if displayed. $c_a2kpf_pfontstart $c_a2kpf_pfontend Contain the font tags used to enclose the "prices subject to change" message, if it is displayed. You can use these to control the choice of font, the color and size of the font, etc. $c_a2kpf_pspacerstart $c_a2kpf_pspacerend These contain the HTML code that used to pad out the start and end of the "prices subject to change" message, if it displayed. The default values force a blank line above and below the messsage. $c_a2kpf_ptext The text to use for the "prices subject to change" message. (B) ADVANCED: CONTROLLING TABLE OUTPUT -------------------------------------- At the beginning of the previous section, we explained that the easiest way to control the width of results in the Piranha Feed results table is to make another table around it, and allow the Piranha Feed table, as it's normally set to 100%, to control expand/shrink automatically to fill it. As of version 2.10, we introduced another option, where the Piranha Feed results table can be set to a width your choose, so the table nesting trick is no longer necessary. This more advanced option also allows you to pad out the Piranha Feed results so they don't press up against each other. There is a downside... You need a reasonable grasp of nesting tables and how to plan out your page to use this. It helps if you have a good head for math. Piranha Feed's table formatting works: 1. There is one or more big tables than contains everything. 2. This can contain: product headings, products tables, a prices subject to change message table, and no results found message as applicable. There can be more than one product headings and product tables, if there are more than one category of products being displayed. 3. Products tables can contain multiple rows and columns. The number of columns depends on (and is the same as) the value that you choose for $c_a2kpf_irowmax. The number of rows depends on the number of products in that table. 4. Each individual cell in the products table contains a small 1X1 inner table, and within that the product data is displayed. This 1X1 inner table is horizontally centered, but top aligned vertically within the cell. 5. The default settings of the Piranha configuration make all outer tables 100%, leave the width of the cells in the products table to the browser to decide, and make the inner 1X1 tables 100% (so that they fill the product cell). These defaults can be changed however... NOTE: Browsers can do odd things to table if, for example, a table cell contains information/images (like a book cover) too large to fit in the table cell. Be careful of extreme values for these parameters $c_a2kpf_otwidth This sets the width of the outer tables. Default value 100%. The width goes directly into the HTML code, so you can also set this value in pixels (just put a number). $c_a2kpf_otcellwidth This sets the width of the product cells in the outer tables. Default value is an empty string, in which case it is ignored, and the browser decides the most appropriate column widths for products by itself. If set to any value other than an empty string, you should make sure that when multipled by $c_a2kpf_irowmax it comes to $c_a2kpf_otwidth - or otherwise you may get strange looking results because the HTML code generated would not be self-consistent. $c_a2kpf_itwidth This sets the width of the inner 1X1 tables containing each product. Default value is 100% which means fill the product cell completely. You can also set this value in pixels (just put. a number). If set as percentage it means a percentage of the product cell width. If set as a pixel number, this value should be set the same or less than $c_a2kpf_otcellwidth or otherwise it will mess up your table formatting. Making it less, results in horizontally spacing out the products items as there would be unused space in each cell. Example: 1. We want to produce a table with 3 columns of products, so we set $c_a2kpf_irowmax to 3 2. We want to make the table 750 pixels wide, so we set $c_a2kpf_otwidth to '750'. 3. We want to force columns in the table to always be the same width, so we set $c_a2kpf_otcellwidth to '250' because 750/3 = 250. 4. We want to add some extra horizontal spacing around each product so they are not squashed up against each other. So we set $c_a2kpf_itwidth to '240'. This will leave a gap of 5 pixels on the edge of each product cell ( 240 + 5 + 5 = 250). 5. The overall appearance of the columns from left to right, would thus be: 5 pixels ..... Product 1 cell.... a gap 240 pixels ... Product 1 cell.... the product 1 info in inner table 5 pixels ..... Product 1 cell.... a gap 5 pixels ..... Product 2 cell.... a gap 240 pixels ... Product 2 cell.... the product 2 info in inner table 5 pixels ..... Product 2 cell.... a gap 5 pixels ..... Product 3 cell.... a gap 240 pixels ... Product 3 cell.... the product 3 info in inner table 5 pixels ..... Product 3 cell.... a gap (C) ADVANCED: MULTIPLE FORMATTING OPTIONS ----------------------------------------- In most circumstances when you use JavaScript you will want to set up the display options once, and have all pages follow the same formatting rules. This has the advantage of ensuring that all pages of your site follow a consistent format. However, sometimes you may wish for different sets of pages to display the results in different formats, and Piranha Feed allows you to do this easily: To make a set of pages with a second, and different formatting options: Step 1: On your computer: Copy a2kpf_config.inc.php to a new file, called a2kpf_config2.inc.php Copy a2kpf_search.php to a new file, called a2kpf_search2.inc.php Step 2: On your computer: Open a2kpf_search2.php in a plain text editor such as Notepad, DOS EDIT, etc. Change the line which includes a2kpf_config.inc.php to include a2kpf_config2.inc.php instead. Step 3: For those pages which use the 2nd set of formatting options, change the PHP or JavaScript integration to link/include a2kpf_search2.php instead of a2kpf_search.php. Step 4: Use your FTP program to upload your completed/updated page(s), including a2kpf_search2.php and a2kpf_config2.inc.php, plus any other pages you have modified, to your webhost, and view them in your web browser. To make a set of pages with a third set of formatting options, repeat the above procedure, but this time creating a2kpf_config3.inc.php and a2kpf_search3.php. You can do this as many times as you like to create fourth, fifth, sixth, etc., sets of formatting options. (D) ADVANCED: PRICE DISPLAY CALLBACK ------------------------------------ This function in a2kpf_config.inc.php is intended for the more advanced user, one with some PHP programming knowledge. It allows you to customize the appearance of pricing information. The way this function works is: 1. It will be called for each product that is in the search results (but only if you have enabled pricing display by setting $c_a2kpf_iprice to TRUE. 2. The parameters provide the Amazon sale price ($our_price) and the list price ($list_price) of the item. Note: For some products, one or both prices may be an empty string, so the function should handle these cases properly. 3. The function should return an HTML string containing the information to be displayed about pricing. By customizing this function, you can therefore format the pricing information as you see fit. There are pricing callback function, is defined in a2kpf_config.inc.php: function a2kPF_cbPrice( $our_price, $list_price ) (E) ADVANCED: HTML MODIFICATION CALLBACKS ----------------------------------------- These functions in a2kpf_config.inc.php are intended for the more advanced user, one with some PHP programming knowledge. They allow you to further customize the appearance of the search results, and in fact totally customize the HTML output generated by Piranha Feed. The way these functions work is: 1. Each of the callback functions is called by Piranha Feed at appropriate points as it is generating the HTML, but before the HTML is sent to browser. 2. Piranha Feed calls whichever callback function, passing a block of HTML code. The callback function then has the opportunity to modify the HTML if it wishes, and returns the finalized version of the code back to Piranha Feed. (the default versions of these functions simply return the HTML code unaltered back to Piranha Feed). 3. When Piranha Feed has completely generated the HTML output, it either outputs the code to browser directly, or does an internal step to generate JavaScript from the completed HTML code. (as Piranha Feed automatically deals with the JavaScript output option, your code in the callback functions does not need to worry about handling JavaScript). There are three callback functions, and each is in a2kpf_config.inc.php: function a2kPF_cbCategory( $html ) This function is called with the HTML for each product category heading. It will not be called if product category headings are turned off for the current type of search results. (product category headings are turned off if, $c_a2kpf_hallenable or $c_a2kpf_hmodeenable is set to FALSE, and the search is of the corresponding type). function a2kPF_cbProduct( $html ) This function is called with the HTML for product listings. function a2kPF_cbAll( $html ) This function is called with the completed HTML output for the results including all product category headings and product listings. Note: most of the HTML code passed to this function will already have been passed in smaller blocks through the a2kPF_cbCategory and a2kPF_cbProduct functions. (F) ADVANCED: CACHE FILTERING ----------------------------- This functionm added in version 2.10 in a2kpf_config.inc.php is intended for the more advanced user, one with some PHP programming knowledge. It allows you to filter out unwanted search results as they are added to Piranha Feed's database cache. The way these functions work is: 1. The callback functions is called by Piranha Feed at appropriate point as it is about to store data into its internal database cache. 2. Piranha Feed calls the callback function, passing information about the type of search being performed (in Piranha Feed's internal format) and data retrieved from Amazon, with minimal prior decoding. The callback function then has the opportunity to review the item, and see if it should be added to the cache for subsequent display. This is useful if there are particular types of products that you wish to filter out of the results. (the default version of this function simply allows all items to enter the cache). 3. It is absolutely vital to clear the cache each type your modify this function, especially when debugging, as otherwise you will get highly confusing results. Piranha Feed remembers in its cache which search and search results it did before. If you forget to clear the cache after modifying this function, the final displayed results made include these types of errors: - You may get items which no longer pass your test, simply because they are already in the cache. - You may lose items which do pass your test now, but didn't before, are remembered by the cache as not passing before, and hence not displayed. There is one callback function, and it is in a2kpf_config.inc.php: function a2kPF_cbCacheFilter( $search, $mode, $title, $tagged_url, $binding, $release_date, $our_price, $list_price ) ============================================================================ 8. CONNECTIVITY ISSUES ====================== (A) THE INTERNET IS NOT 100% RELIABLE ------------------------------------- ** ** We have found that connectivity seems considerably more reliable ** if you use Web Services to connect rather than basic XML. See section ** 3(D) of this guide for more information on these options. ** *********************************************************************** NOTE: As of approximately Summer 2004, Amazon no longer seems to have the legacy XML interface enabled. Therefore Piranha probably won't work if you set a2kpf_amconnect to 1. Check with Amazon if you are unsure, or better yet simply use the setting of 2! *********************************************************************** The Internet is not a 100% reliable communication technology. Web servers can crash, routers can be incorrectly configured (or simply fail), sites can be down because of various technical issues and so on. The fact that the Internet usually works so well, means that most users are not aware of these little "glitches". However the fact that the Internet is not 100% reliable is something that you should be aware of. As regards Piranha Feed, the key point is that in order for Piranha Feed to retrieve search data from Amazon, it must first be able to establish connection from your web server to Amazon's web servers. The vast majority of the time it should easily be able to do so... However, if there is a problem with your server, with Amazon's servers, or with the connection some place in between, it won't be able to establish this connection and consequently will not be able to retrieve the search data. In our experience, Amazon's site is extremely robust and reliable - so you may never encounter this type of problem. Even you do (1) there's a good chance that the problem might be caused by an issue with your web host (some cheaper web hosts do not have redundant connections for example), and (2) you do not need to take any action [although you might want to talk to your web host if this type of problem occurs frequently]. What happens if Piranha Feed can't access Amazon? It will treat the current search as if no matching items were found - and then next time an identical search is performed, try to access Amazon again, and hopefully get the information on the next attempt. Piranha Feed's caching algorithms also help considerably in mitigating any connectivity issues with your web host (or Amazon): Because Piranha Feed caches recent search results, in many cases it will be able to display search results to the user without even bothering to access Amazon's servers. ============================================================================ Copyright (C) 2002-2004, Answers 2000 Limited. http://www.scriptrocket.com/