==================================================================
Snippet-title:		show_how_searched v1.0
Creator:		Graham Keellings
E-mail:			pivot@keellings.com
Website:		http://www.keellings.com/software/pivot.php
Creation date:		08 Mar 2006, Singapore
==================================================================

Content of zipped file:
-----------------------
snippet_show_how_searched.php
readme_show_how_searched.txt (this file)


Usage:
------
1) unpack this package in your extensions/snippets/ folder.
2) place a [[show_how_searched]] tag, with the appropriate parameters, in any of your (template) files, whereever you want the output text to appear
Example: [[show_how_searched:0:8:<hr><h2>How the last %num% visitors found my site</h2>:Someone searched for \"%keys%\" on %engine%<br />:<h2>How boring!</h2>:<h2>Looks like no-one searched for me yet</h2><hr>]]
or   [[show_how_searched:1:8:<hr><h2>The %num% most popular searches, leading to my site</h2>:Search term \"%keys%\" found me %hits% times<br />:<h2>How boring!</h2>:<h2>Looks like no-one searched for me yet</h2><hr>]] 

3) rebuild the FrontPage(s), if you are using it from within Pivot.
   

Description:
------------
* This snippet processes the data file stored by my [[how_searched]] snippet
* and outputs information about either the lastest searches to find your site, 
* or the most popular.
*
* Although it is a snippet, it is not Pivot specific, and this functionality 
* can be used on every page on your web site.
*



Parameters:
-----------
* @param  int     mode       - 0 (default) show most recent results,
*                              1 show most popular search strings
* @param  int     showCount  - show this many entries (default = 5)
* @param	string	introText  - for instance "<hr><br>How people found my site: "
*                              You can use %num% for the actual number of hits 
*                              found. For instance, you might pass the showCount
*                              parameter as 10, because you want to show a 
*                              maximum of 10 search results; however, if there 
*                              are only 3 search results, then %num% will be 3.
*                                Example "The %num% most recent searches"                         
*                              This will be output first, but only if there are 
*                              any searches, otherwise the "noHitsText"
*                              paramater will be output.
* @param  string  format     - tells how to format output for each search, if any
*                              The info available for each search hit is as
*                              shown here for a single entry 
*                                ["search_engine"]=> string(6) "Google" 
*                                ["keys"]=> string(29) "keellings graham's world blog" 
* 
*                              Pass a string that you want want output, 
*                              including the tags %keys% (always), %engine% (if
*                              mode = 0) and %hits% (if mode = 1)
*                                for example, if mode = 0, you could use:
*                                  Someone searched for \"%keys%\" on %engine%
*                                and, if mode = 1, you could use:
*                                  The search term \"%keys%\" found me %hits% times
*                                NOTE: you have to 'escape' quotes, with a 
*                                     backslash, as shown in the above example. 
* @param	string	outroText  - for instance "<hr>" - will be output last
* @param	string	noHitsText - for instance "No-one searched for me :-(" 
*                              This will be output, instead of 
*                                 <intro><format><formt>...<format><outro>,  
*                              if there are no search hits.
*                                            
* @return The requested HTML, as specifi