MyHeadlines v4.x.x API Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The MyHeadlines object is a self contained php class that serves as a powerful
content syndication engine.  Here is a list of core functions that you'll need
to understand in order to seamlessly integrate MyHeadlines into your CMS.


Assumptions and Notes:
~~~~~~~~~~~~~~~~~~~~~~
a)	Setting the "$myhPath" global variable: You must define this variable
	as global, and it must be set to the proper value BEFORE you include
	the MyHeadlines.php file.  
	  [ ex. include_once("$myhPath/MyHeadlines.php"); ]

b)	MyHeadlines uses cookies to track anonynmous users.  You must
    Initialize MyHeadlines BEFORE any content is sent to the browser.  If
    you have already sent something to the browser before MyHeadlines has
    a chance to issue its cookie you will receive an error message about
    the headers already being sent.  Avoid this issue by initializing
    MyHeadlines as early as possible.

c)	MyHeadlines expects there to be an external user account management
	system.  This system must be able to detect the following user
	properties prior to initializing MyHeadlines:  
			Is_Admin / Is_User / Is_Anon / Username / User_ID
	The Is_??? properties are boolean, Username is string, User_ID 
	is int32 (and must not be 0). MyHeadlines is forgiving enough that 
	the only critical property is the Is_Admin value.  All other properties 
	are optional, (but nice to have).

d)  MyHeadlines requires an active DB connection to a MySQL v3.23.23
	(or better) DB _BEFORE_ you initialize the MyHeadlines object.  The Object will
	create all the tables it needs at initialization (if they don't already
	exist) so the connection to the DB must have the access rights for creating
	and deleting tables.  (I know this is a bad thing, I don't care, and
	damn near everybody does this by default anyway). 
	Keep these system requirements in mind:
		-> MySQL v3.23.23 or Better.
		-> PHP 4.0.4 or Better.


API Definition:
~~~~~~~~~~~~~~~
1)  MyHeadlines is initialized by calling the member function:
		function MYH_INIT(	$url, 
							$table_name_prefix="AGAR", 
							$isAdmin=0, 
							$externalUID=0, 
							$userName=0, 
							$DBG=0)
	Where:
		$url = the url used to access MyHeadlines 
		       [ ex.PHPNuke: $url="modules.php?name=MyHeadlines" ]
		$table_name_prefix = the prefix that you may define to force 
		                     MyHeadlines to create its tables according
		                     to your site specific naming convention
		$isAdmin = if set to 1 the admin interface is exposed.
		$externalUID = if you have a user id from your CMS that you'd like
		               MyHeadlines to track (and not issue a cookie) enter
		               it here, if the user is anonymous enter a 0.
		$userName = If you have a handle for this user you may enter it here
		            if not (or the user is anonymous) the MyHeadlines account
		            will identify the user by the RARP value for the user's
		            IP Address.
		$DBG = if you'd like to see pages of debug information just turn this on.

2)  DEPRECATED -> The showGUI() will return the HTML for the "Main Menu" for MyHeadlines as a string.
                  Please see getDashBoard()

3)  The getSubs($position) function returns an array of the user's source ID's (sid) for all
	the subscriptions in that location.  This is the current list of two character
	$position flags:
		"lt" = Top Left
		"lb" = Bottom Left
		"rt" = Top Right
		"rb" = Bottom Right
		"ct" = Top Center
		"cb" = Bottom Center
	The intent is for the external CMS to use each of these sid's to query again to 
	gather the content for each individual source.  See Step 4.
	
4)	The getCache($sid, $show_desc=0, $show_all=0, $show_date) function returns the $box array (defined
	below) that contains the raw HTML for this source's cached items.  First we'll define
	the input parameters:
		$sid = this is the source id of the cached items
		$show_desc = optional flag to indicate verbose mode
		$show_all = optional flag that overrides the "max_rss_items" config parameter
					This will force EVERY cached item of this source to be displayed
		$show_date = optional flag to indicate attaching the date stamp of the item
	The Output value is an array with the following contents:
		$box["title"] = this is the site name for the source id
		$box["image"] = this is the site logo (optional as some sites don't define their logo)
		$box["content"] = this is the raw HTML for the cached items returned
            Added in Version 4.0.5:
		$box["url"] = this is the source url
		$box["next_update"] = this is a string indicating the time left before the next update.

5)	The updateCache($sid) function will refresh the cache for the source id ($sid) if it
	has expired.  It is wise to call this before you call getCache($sid).
		->THIS ONLY UPDATES SOURCES THAT HAVE EXPIRED (TIMED-OUT).  
		->IT WILL NOT UPDATE EVERYTIME THIS IS CALLED.
		
6)	The refreshExpired() function will refresh the cache for all the expired sources.  This is
	a bulk refresh function that should be integrated with a scheduler like cron to keep the
	headline cache current.  This will speed up load times for your users since the cache will
	be current when they arrive, and MyHeadlines will not have to go off to other sites to
	retrieve the stale sources.  It also improves the search engine considerably, since it will
	always be adding new sources and the cache size will grow dramatically.  Here are some 
	number for you to consider:  My site has 220 unique sources with user subscriptions, I 
	expire old stories after 14 days ("rss_cache_expire"), I use cron to "refreshExpired"
	every 10 minutes, I have 51,000 cached stories, and my database is about 20 MegaBytes.  If
	I left the "rss_cache_expire" config value at the default I'd have 100,000 cached stories,
	and a 40 MegaByte database...  (do your own math, and adjust to fit your site)
		->THIS IS RESTRICTED BY THE "max_updates_per_cron_cycle" CONFIG VARIABLE.

7)  The getStats($horizontal=0) function returns the raw HTML for the "Top Ten" page.  The
	$horizontal flag indicates that the Top Ten lists are to appear side by side.  If set
	to 1 then it is side by side, if set to 0 then it is in a vertical alignment: one on top
	of the other.  The vertical format is useful for side block type content.

8)	The userSubscriptionScreen() function returns the raw HTML for the default screen layout
	for user subscriptions.  All of the user subscriptions are placed in the appropriate locations.
	This is an easy way to show the user's subscriptions if you don't want to handle each source
	and location individually.

9)  The registerMenuURL($header,$text,$url) function extends MyHeadlines so that you may add URL's to the 
    Main Menu (showGUI).  This will let MyHeadlines function as the primary menu for your site. $header 
    is a "group" title, you can have as many groups as you want.  Inside each group ($header) you may
    register as many $text/$url pairs as needed.

10) doGoogleSearch($search,$start) is the function that executes Google searches via SOAP.  You must
    have a Google account to make this work.  $search is the query string, $start is the index into the
    results (handy for "More" buttons).  This will return an array $result["html"] is the raw html
    table to display the results, $result["more"] is a flag indicating there are more results, increment
    the $start value by 10, and you can re-issue the search to get the next ten values.
    
11) getDashBoard() - this replaces the old showGUI() function.  It does the same thing but now is much
    more buzz word compliant.

12) getDashBoardComponent_Menu() - This is the raw HTML of the Menu fron the Dash Board (left most column)

13) getDashBoardComponent_MainScreen() - This is the raw HTML of the action screen from the Dash Board
                                         (center column).

14) getDashBoardComponent_StockTicker() - This is the raw HTML of the Stock Table from the Dash Board.
                                         (right most column).
        
All other functions are self contained and should not concern you.  Note that only Debug
information is sent directly to the browser.  All other HTML is returned to the CMS for
further processing, and it is the CMS's responsibility to send to the browser.


Enjoy!


Mike Agar
myh_support@jmagar.com
www.jmagar.com