Site Plugins (OpenDb 0.81+)
---------------------------

1) Introduction

	As of 0.81, the site plugins architecture has been completely rewritten.  This was done
	to make the using site plugins within OpenDb much more flexible.  The class based
	design also makes it much easier for developers to implement new plugins.

	A site plugin consists of at most 3 files:
	
	1) The site plugin class
		site/$classname.class.php

	2) The site plugin icon
		site/images/$site_type.[gif|jpg|png]

	3) The site plugin installation script.
		patch/site/$site_type.sql


	The $classname is the s_site_plugin table classname column value, and allows more
	than one site plugin to share the same plugin class file.

	The $site_type is the s_site_plugin table site_type column value, and is unique
	for a single plugin only.

2) Components

2.1) Site plugin class

	The site plugin class consists of a class which extends SitePlugin (functions/SitePlugin.class.inc)
	and has 3 methods, two of which require modification by the plugin developer.

2.1.1) Site plugin template

	A site plugin template is provided at docs/site/plugin.class.php and looks a lot like this:

	------------------------- begin template -------------------------
	include_once("./functions/SitePlugin.class.inc");

	class plugin extends SitePlugin
	{
		function plugin($site_type)
		{
			parent::SitePlugin($site_type);
		}
	
		function queryListing($page_no, $items_per_page, $offset, $s_item_type, $search_vars_r)
		{
			// standard block of code to cater for refresh option, where item already has
			// reference to site item unique ID.
			if(strlen($search_vars_r['plugin_id'])>0)
			{
				$this->addListingRow(NULL, NULL, NULL, array('plugin_id'=>$search_vars_r['plugin_id']));
				return TRUE;
			}

			//else - if no ListingRows then 'No Records Found' is displayed, while returning FALSE
			// results in a Undefined Exception
			return TRUE;
		}
	
		function queryItem($search_attributes_r, $s_item_type)
		{
			return FALSE;
		}
	}
	-------------------------- end template --------------------------

	For your individual plugin, you should replace the references to 'plugin' both for the
	php file name, and in the source itself, to whatever classname you have chosen; for
	example 'amazon'.

2.1.1.1) function plugin($site_type) - A.K.A The 'Constructor' function (Object oriented talk!)

	The constructor function looks like this, and except for changing the 'plugin' reference
	you should leave it exactly as is - changing this function will render the plugin useless!

	function plugin($site_type)
	{
		parent::SitePlugin($site_type);
	}


2.1.1.2) function queryListing($page_no, $items_per_page, $offset, $s_item_type, $search_vars_r)

	@returns - Returns TRUE if no HTTP access issues were encountered, even if no records
	returned.  Otherwise return false.

	This function is where you build up a list of all matching titles for a specified set of
	$search_vars_r.  The variables in the $search_vars_r correspond to the s_site_plugin_input_field
	records.  The 'field' name will be the index.

	The other parameters have been derived for you, if possible.  Where an $items_per_page value of
	zero is configured, the $page_no, $items_per_page and $offset values should be ignored.

	The $s_item_type is the item type of the item the user is adding / refreshing.  This can be useful
	to modify the queries sent to the site plugin website or webservice, but can be ignored if you
	don't need it.  For instance the IMDB plugin only handles generic video data, so the $s_item_type
	is ignored in this plugin.

	This function is not responsible for building the user interface for the listing, merely to
	provide the raw data (in the form of arrays of arrays) for the architecture to generate the
	UI.  Thus the data does need to be provided in a particular format.

	You need to use the $this->addListingRow($title, $cover_image_url, $comments, $attributes_r) function
	call for each item you want to list as an option.

		* $title - is the complete title of the item (for users to recognise), which might include
		the year or other info, but not any images!

		* cover_image_url - should be a complete url (including http:// prefix) for a cover image
		url.  If you do not provide one, the architecture will generate a default theme specific one,
		so don't do it yourself.

		* $comments - any additional comments about the title, for instance a release date, or
		the fact that its a special edition, vs. normal, etc.

		* $attributes_r - a set of attribute values that can be used to uniquely identify the
		item, such as the 'imdb_id' or 'amazonasin' for example.  You would format the call thus:
			$this->addListingRow($regs[1], $regs[2], array('amazonasin'=>$regs[3])

		where $regs is a regular expression result, which matched title, cover_img_url and 
		amazonasin (in that order!)

2.1.1.2.1) Notes

	In order to cater for an exact match on the $search_vars_r parameters, which should happen
	in every case for refresh option (where the appropriate site attribute is saved), is done
	by saving a single listing row.

	The standard block of code that always should be at the beginning of your queryListing
	function:

		if(strlen($search_vars_r['plugin_id'])>0)
		{
			$this->addListingRow(NULL, NULL, NULL, array('plugin_id'=>$search_vars_r['plugin_id']));
			return TRUE;
		}

	... where 'plugin_id' is the unique ID for a site plugin.  For instance IMDB uses 'imdb_id'.

2.1.1.2.2) Returns

	* TRUE 	- Indicate that the site was queried successfully, this is not to say any
		listing titles will actually be found however.
	* FALSE	- If the fetchURI(...) call fails.  The fetchURL will set the appropriate HTTP 
		error as a result, so you never should.

2.1.1.3) function queryItem($search_attributes_r, $s_item_type)

	The $search_attributes_r array should contain enough information to uniquely identify ONE site title.  If
	it does not, you should return FALSE, as the queryListing function has obviously been coded
	incorrectly.
	
	For that unique item, you need to save all the attributes of the item, applicable for populating
	a $s_item_type item and attributes.  You use the function:
		$this->addItemAttribute($name, $value);

	Do NOT space delimit lookup values (such as AUDIO_LANG) as you would have done previously in the
	old plugins architecture, instead you should call the $this->addItemAttribute($name, $value); 
	for each individual value, the process will handle it correctly.

	For multi-value attributes that are not for lookup values (such as MOVIEPLOT), you would still call
	$this->addItemAttribute($name, $value); for each one, and the interface will present the user with
	all of them, from which they have to pick one.

	You can use the Attribute Map functionality to map your $name's to specific s_attribute_type's
	in the OpenDb.  For instance, you may map 'genre' to MOVIEGENRE as an example.

2.1.1.3.1) Notes
	
	You do not need to trim the $value before passing it to $this->addItemAttribute($name, $value);,
	as thats done for you.

	You can pass an array for $value, and each $value will be separately added, so that it can
	be dealt with by the input process in a standard way.

2.1.1.3.2) Returns

	* TRUE  - Indicate that the item was found and processed successfully.
	* FALSE - Indicate item was not found, should never occur in practice, but may if the 
		plugin is badly coded.

	

	

	