==================================================================
Snippet-title:		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_how_searched.php
readme_how_searched.txt (this file)


Usage:
------
1) unpack this package in your extensions/snippets/ folder.
2) place a [[how_searched]] tag, with the appropriate parameters, in any of your (template) files, whereever you want the output text, if any, to appear 
Example: [[how_searched:So, you want to know about \"%keys%\"?]]
         [[how_searched:You got here by searching for \"%keys%\" on %engine%]]
or even  [[how_searched::1]]
if you just want to log the search to a file (see parameter logToFile)

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

Description:
------------
* Add this snippet to a page and if the viewer reached it through a search 
* engine, it will output some text, if you wish, about the search engine and the 
* keywords used, formatted as you wish. 
*
* It can also, optionally, store this information to a file, to be preocessed 
* later, probably by [[snippet_show_how_searched]]. 
*
* 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  string  format     - tells how to format output, if any
*                              The info available looks something like this: 
*                               object(search_keywords)(4) 
*                                  { ["referer"]=> string(85) "http://www.google.co.uk/search?hl=en&safe=off&q=keellings+graham%27s+world+blog&meta=" 
*                                    ["search_engine"]=> string(6) "Google" 
*                                    ["keys"]=> string(29) "keellings graham's world blog" ["sep"]=> string(2) "\&" } 
* 
*                              Pass a string that you want want output, 
*                              including the tags %refer% %engine% and %keys%
*                                for example:
*                                [[how_searched:So, you want to know about \"%keys%\"?]]
*                                [[how_searched:You got here by searching for \"%keys%\" on %engine%]]
*                                  or even
*                                [[how_searched::1]]
*                                  if you just want to log the search to a file
*                                  (see parameter logToFile)
*                                NOTE: you have to 'escape' quotes, with a 
*                                     backslash, as shown in the above example. 
*                              Note that this will only be output if the visitor
*                              did reach your page through a search engine. 
*                              Otherwise, no text will be output.
* @param  bool    logToFile  - if 0 (default)ill not be logged to file.
*                              if 1, will be logged to the file defiend in 
*                                $howSearchedDataFile above.
*                                            
* @return The requested HTML, as specified by the parameters.