Themes
------

1)	Introduction

Theme support was added to OpenDb in version 0.38.  From then on the structure
of the themes has stayed pretty much the same.  From OpenDb 0.51 onwards theme
support has undergone a bit of a redesign to support such things as language 
specific theme images and 'text' based themes.

2)	What is a theme?

The theme/ directory is where all the themes are actually stored.  Each directory
underneath theme/ contains a separate theme.  The name of the theme _is_ also the
name of the theme itself.

The theme/$_OPENDB_THEME/ directory has the following structure:

	index.php
	style.css
	images/*.gif,*.jpg,*.png
	images/$_OPENDB_LANGUAGE/*.gif,*.jpg,*.png

The existence of a 'index.php' is the only thing required to indicate to OpenDb
that the theme is valid.

The index.php has several functions which can be called from outside the
theme itself:

	theme_index()
	theme_header($title)
	theme_footer()
	theme_menu()
	theme_image_src($src)
	theme_image($src, $alt, $title, $align, $type, $class, $width, $height)
	theme_error($error)
	theme_refresh_menu()
	theme_graph_config()

If any of these functions is not defined, the default functionality will be used 
instead.

3)	_theme_image functionality

	When this function is called from main scripts it goes looking in particular 
	directories for the $src image.

	These are the steps it uses to work out which image to display:
	1.  Checks if 'theme_image' function is defined.  This function
		should return a fully formed <img src="" ...> or a textual 
		equivalent.

		If the theme specific 'theme_image' returns FALSE, this indicates
		that the local function is not taking responsibility for displaying
		the image in this case.  We should continue as though the theme
		specific 'theme_image' function did not exist.

	2.	Check if theme_image_src($src) function is defined, in which case will
		use image from the location returned by this function in theme_image.  Useful
		for themes, where there is only layout changes, and the images are the
		same as for example the default theme.
		
	3.	Checks for $src in the following directories:
			theme/$_OPENDB_THEME/images/$_OPENDB_LANGUAGE/
			theme/$_OPENDB_THEME/images/
			theme/$_OPENDB_THEME/
			theme/default/images/$_OPENDB_LANGUAGE/
			theme/default/images/
			theme/default/
			images/$_OPENDB_LANGUAGE/
			images/
			
		Note: As of 0.60-dev29, the 'default' theme directory is checked.
		
	4.	If $type == "action"
			return FALSE;
			
		If the $type is "action", and the specific theme did not handle it, then
		we have to let the caller (listings.php, item_input.php, item_display.php, etc)
		handle it in a default way.  This is a special case, because the default
		functionality lists all the actions in text, with a '/' separator between
		each one.  We cannot achieve this in theme's as we do normally, because the
		_theme_image is only passed one thing at a time.  If _theme_image(...) returns
		FALSE, the caller will know to proceed as normal.
		
	5.	If $alt is not null, the $alt text will be returned instead 
		of <img ...> tag.  This is even if the $alt=="" (empty string),
		which is new in 0.51-dev6

	6.	Otherwise return the $src, without extension, in initcap format.

	As you will notice from the above steps, the theme specific 'theme_image'
	function will be called first if it exists.  If this function does exist, 
	and it returns _anything_ than FALSE, the processing in '_theme_image' is
 	considered complete.  If the theme function does _not_ exist or returns
	FALSE, step 2 takes over.

	For 'text' based themes, you would implement 'theme_image' with step 3 only
	and return FALSE otherwise.  (See section 4.1 in this document for an
	example)

4)	theme/$_OPENDB_THEME/style.css configuration

	As of 0.80-dev9, the style.css will be parsed to ascertain the correct
	graph style, as long as a custom theme_graph_config() function is not
	defined at the theme level.
	
	The parser will look for all the options for the graph in the new 
	'.OpendbStatsGraphs' element, which include:

	Chart colours:
		==> 'text-color'		--- All text
		==> 'caption-color'	--- Pie chart Caption link lines
		==> 'light-color'  --- Standard background of charts
		==> 'dark-color'  --- Alternate background for striped charts
		==> 'light-border-color' --- light border of pie charts
		==> 'dark-border-color' --- Pie chart wedge separator, pie chart border and bar chart shadow border.
		==> 'background-color'   --- Background of generated image

	Image attributes:
		==> image-size
		==> font-size
		==> transparent

	The element has the following form:
		.OpendbStatsGraphs
		{
			image-size: 175;
			font-size: 2;
			transparent: true; 
			text-color: #000000;
			caption-color: #000000; 
			light-color: #6D78AB;
			dark-color: #8E9DE0;
			light-border-color: #8E9DE0;
			dark-border-color: #000000;
			background-color: #FFFFFF
		}

	If any Chart colours are not included in the '.OpendbStatsGraphs', standard mappings to 
	existing elements will be performed.

	The parser uses the standard mappings as recommended in the docs/notes/themes.txt section 
	4.2, as follows:

		'text-color'		=> BODY color
		'caption-color' 	=> BODY color
		'light-color' 	=> .top class background-color
		'dark-color' 	=> .top2 class background-color
		'light-border-color' => .top2 class background-color
		'dark-border-color'	=> BODY color
		'background-color'	=> BODY background-color
	
	Browsers will ignore this entry, as it does not correspond to any
	class or predefined element.

4.2) _theme_graph_config() functionality

	This functionality is deprecated and should be replaced with '.OpendbStatsGraphs'
	in style.css

4.3) Other
	If required update the CSS 'img.graph' in style.css so that border-width: 1
	and border-color => BODY color:
		img.graph { border: solid; border-width: 1; border-color:#0000FF }

	If you decide to go with a 'bgcolor' that is not the same as BODY, you 
	might like to consider getting rid of the border around the image.  You
	can do this by setting { border-width: 0; }

	* Netscape 4.x will not correctly handle border-width attribute.

5)	OpenDb Help integration

As of 0.80-dev20, a link to OpenDb Help help.php may be included on various pages
within OpenDb.  The link to the help has to be enabled by including a call to
get_help_href_link($mask=NULL) into the theme_header function or thereabouts.

The theme/default/index.php::theme_header(...) had its code updated to include:

echo("<td valign=top>".
		"\n<div align=\"right\">".
		"\n<h1>".$CONFIG_VARS['site.title']." ".$CONFIG_VARS['site.version']."</h1>".
		get_help_href_link("[%hreflink%]").
		"\n</div>");
		
Whereas before it was:

echo("<td valign=top>".
		"\n<div align=\"right\">".
		"\n<h1>".$CONFIG_VARS['site.title']." ".$CONFIG_VARS['site.version']."</h1>".
		"\n</div>");
		
	The $mask argument, allows you to include the [ and ] to enclose the <href ...> link.

6)	Changes

6.1) 0.51-dev6

	See Changelog for this version, for particular details.  Here is
	the changelog entry for functions/theme.php:

	New arguments added:
		$class - originally in the _theme_image, but not added to the
		call to theme specific 'theme_image' call.

		$type - Specifies the origin of the image.  
				Current types being	used are:
					s_item_type - for 's_item_type' table images.
					borrowed_item - Borrow system status images.

  	The spec of the theme specific 'theme_image' now looks like this:
	theme_image($src, $alt, $title, $align, $type, $class, $width, $height)

	Changed the logic so that the $alt text will be displayed if no image
	found if it is NOT NULL.  The test used to be !empty($alt).  The calls 
	to _theme_image in the main code have been updated, so that instances 
	where the $alt text can be used, it will be specified.  Where the alt
	text cannot be specified, and nothing else is suitable, an alt value 
	of "", will be specified instead.  This indicates that the image
	is not required and can be safely ignored.  You can override the new
	functionality in your own theme 'theme_image' functions anyway.

6.2) 0.51-dev5

The $OPENDB/images/ directory now includes the default 'avail.gif', 'reserved.gif',
'inactive.gif','borrowed.gif' images, so if all you are doing in your theme is
modifying the style sheet and layout -while keeping the 'default' theme images-
you do not have to worry about including your own images directory.

	New		-> Old
	--------------------------------------------------------------------
	a.listlink	-> NEW

6.3) 0.51-dev3

OpenDb 0.51-dev3 was the first release with the overhauled CSS styles
infrastructure active.  Following are the conversions that were
performed from the previous style sheets:

	New		-> Old
	--------------------------------------------------------------------
	.smsuccess	-> is .small
	.prompt		-> includes the .top background color.
	.data		-> includes top2 & .head (except for color)
	.navbar		-> includes the .head class, added text-align: center
	.menutext	-> is .plain
	.help		-> is .footer
	.blocktitle	-> REMOVED
	.alphalist	-> is like .footer
	
	a.listlink	-> NEW
	.printtitle	-> REMOVED

7)	Questions & Answers

7.1) How do I force my theme to display text in place of images.

	From 0.51-dev5 onwards all the 'default' theme images have been
	moved into the $OPENDB/images directory, so that new themes can
	be created without resupplying the images again.  In order to
	override this functionality, you will need to add a 'theme_image'
	function to your theme index.php.

	The following is an example of just such a theme_image function.
	Please note that you must specify the function spec, exactly
	as illustrated, for your theme as well.  (Obviously the content
	can be different though!)

	You will notice that this particular theme_image function, will only
	return the $alt text if it is _not_ NULL.  This is an idea that has 
	been perfected for 0.51-dev6+.  Any calls to _theme_image will specify
	NULL for $alt text if there is _no_ text alternative to the image
	being displayed.  This gives you the option of returning FALSE from
	your custom function in these cases, so that the main process can 
	take over and display the image.  
	
	The 'rs.gif', 'rgs.gif', 'gs.gif' images used for Reviews are just
	such an example of this convention.  The review functionality would
	most certainly break without these images being displayed.

	All references to 'rs.gif', 'linked.gif', 'ticks.gif' have also been
	updated to follow this convention.  These images are small and will
	be cached, and they provide important interface functionality that
	cannot be bypassed without compromising OpenDb.

7.1.1) Example theme_image - 'text' theme.
	---------------------------<snip>---------------------------------------------
	/**
		A theme_image function to print text in place of the image.
	*/
	function theme_image($src, $alt, $title, $align, $type, $class, $width, $height)
	{
		if($alt!==NULL)
			return $alt;
		else
			return FALSE;
	}
	---------------------------<snip>---------------------------------------------

7.1.2) Example theme_image - 'text' theme with specific formatting for 
	   Media type (s_item_type) images. 

	---------------------------<snip>---------------------------------------------
	function theme_image($src, $alt, $title, $align, $type, $class, $width, $height)
	{
		if($alt!==NULL)
		{
			if($type == "s_item_type")
				return "[".$alt."]";
			else
				return $alt;
		}
		else
			return FALSE;
	}
	---------------------------<snip>---------------------------------------------

7.2) How can I get the global _theme_image(...) functionality to produce the 
	 image in certain circumstances, and my own theme based theme_image()
	 in others?

	If you 'return FALSE' from your theme_image function, the core functionality
	will take over producing the image; any other return and it will assume
	you have handled it.

	For example, I want to display text for all images, except for 'dvd.gif':

		if($src == "dvd.gif")
			return FALSE;
		else ...

8)	"Action" images

To support using images for actions, you must supply the following images.  Note
that all action images have a 'action_' prefix, to avoid name clashes.

	Input:
		action_edit.gif
		action_delete.gif
		action_refresh.gif
		action_update.gif
	
	Borrow:
		action_reserve.gif
		action_borrow.gif
		action_cancel.gif
		action_add_to_reserve_list.gif
		action_delete_from_reserve_list.gif
		action_quick_check_out.gif
		
