Documentation for UniversalContent and UniversalContentAdmin


/***************************************************************************
//"universalcontent.php"
/***************************************************************************

Universalcontent provides fundamental MySQL access.  The class accesses MySQL 
at the table level. As such, scripts employing UniversalContent, must complete
any necessary authorization before calling any function which needs to access
the database.  UniversalContent is designed to access only one table per instance.

/***************************************************************************
//Class Variables
/***************************************************************************
	$data: An array of the data which the class accessed last.
	$tablename: Name of the MySQL table, which the class will access
	$sortingvalue: An internal variable used to get around a limitation of 
		the PHP function strnatcasecmp.

/***************************************************************************	
//Class Functions
/***************************************************************************
function universalcontent ($paramtablename)
	
	Class constructor.  
	
	$paramtable name is simply the name of the table which universalcontent will access.  
	

function BlankData ()
	
	Internal function to clear any data used by Universal Content (or its children).
	This does not change the tablename.
	

function LoadContent ($paramname, $paramid)
	
	Loads the first record in which the table column $paramname is equal to $paramid.
	The function will not load multiple records.  If the id does not exist, the 
	function will call BlankData. The function returns true if a record was successfully
	load and false otherwise.
	
	$paramname:  MySQL column name
	$paramid:  Value of column name in a record.
	

function ListOfAll (&$dataarray, $indexvalue, $othervalues, $HTMLSafe = TRUE, 
		$numberedlist=false, $forcesubarray=false, $where='1=1')
	
	Loads a list of all partial records which meet the criteria provided by $where 
	into the array $dataarray.  If there are no records, $dataarray is set to null.
	If $numberedlist is true, all values (from $indexvalue and $othervalue) will be
	listed as a sub-array of $dataarray (ie $dataarray[$x]=>arrayofonerecord).  
	Otherwise, the results will be listed as an associative array using the values
	of the $indexvalue column (in this case, that column needs to meet the MySQL 
	requirements "not null" and "key").  If an associative array is returned, the values
	of $indexvalue will NOT be included in the subarrays.  If one or fewer values is 
	specified for $othervalues when $numberedlist is false and $forcesubarray is false, then 
	$dataarray will be a single dimensional associative array.  In such a case where 
	there are no other values, then the value and the key will be the same.
	
	$dataarray:  Target of function.
	$indexvalue: MySQL column name.  Column name must be specified.  If $numberedlist
		is false, the values of $indexvalue will be used 
	$othervalues:  Additional MySQL column names.  Multiple column names should be 
		listed as a single string with comma separators.
	$HTMLSafe: All values and keys of dataarray will be subjected to HTMLEntities if true.
	$numberedlist: If true, $dataarray will not be an associative array.  If false,
		$dataarray will have keys equal to the values in the column $indexvalue.
	$forcesubarray: If one or less $othervalues are specified, $numberedlist is
		false, and $forcesubarray is false, then $dataarray will be a single dimensional
		array.  Otherwise, $dataarray will be multi-dimensional.
	$where:  Used in the MySQL query.  Must return a valid MySQL boolean.
 

function ReturnData ($parameter, $HTMLSafe = false, $NoNull=false)
	
	Returns the value of a given parameter already loaded from the database (as such 
	this function can only be called after a valid LoadContent() call.  This function
	is intentionally not fault tolerant, so if you pass an invalid parameter name you
	may get a warning message from PHP.  This can also occur if the value in the MySQL
	table is null.
	
	$parameter:  Name of the MySQL table column which holds the desired value.
	$HTMLSafe: Apply HTMLEntites to results if true.
	$NoNull:  Will return "&nbsp;" instead of "" if there are no results.
	

function SubstituteList ($dataarray, $indexvalue, $othervalues, $replacementstring,
	$specialindex=UC_NO_SPECIAL_INDEX, $specialreplacementstring='')
	
	Returns a string of with multiple copies of $replacementstring in which values 
	in $replacementstring have been replaces with the values of $indexvalue and 
	$othervalue as provided by the associative array $dataarray.  Replacements
	are done with $indexvalue first and then sequentially through $othervalues.
	If $specialindex is assigned a value other than UC_NO_SPECIAL_INDEX, then
	if and when the value of $indexvalue in $dataarray is equal to $specialindex,
	then $specialreplacementstring will be used instead of $replacementstring.
	This function is particularly useful for creating selector options.
	
	$dataarray:  Associative array with keys equal to the values of $indexvalue 
		(essentially identical to an array returned by the function ListOfAll)
	$indexvalue: String which the keys of $dataarray will replace in $replacementstring.
	$othervalues: String of values separated by commas which are also keys in 
		the subarrays of $dataarray.
	$replacementstring: A string on which the replacements will be performed.  "$"
		should precede the name of any variable you want replaced.
	$specialindex: If not UC_NO_SPECIAL_INDEX and the key of the $dataarray is equal
		to $specialindex, $specialreplacementstring will be used instead of 
		$replacementstring.
	$specialreplacementstring: Alternate to $replacementstring.
	
		
function SortDataArray (&$dataarray, $alphabetize, $firstkey='', $secondkey='')

	This sorting function will sort $dataarray as specified by $alphabetize.  
	$alphabetize may be one of three constants or it can be a valid user-defined 
	comparison function (see details on these functions in PHP documentation on
	the function usort, particularly one the use of user-defined functions in 
	classes).  The constants recognize by SortDataArray are UC_ALPHABETIZE_BY_KEY,
	UC_ALPHABETIZE_BY_VALUE, and UC_ALPHABETIZE_NONE.  
	
	$dataarray:  The array to be sorted.
	$alphabetize:  Either a constant of a valid user-defined comparison function.
	$firstkey  The key which to be used by UC_ALPHABETIZE_BY_VALUE.
	$secondkey  The alternative key to use if $firstkey is equal to ''.		
	

function ReturnList ($indexvalue, $othervalues, $replacementstring, 
	$alphabetize = UC_ALPHABETIZE_NONE,  $HTMLSafe = TRUE, 
	$specialindex=UC_NO_SPECIAL_INDEX, $specialreplacementstring='',
	$where = '1=1')
	
	ReturnList loads, sorts, and then creates a list of all the records in a table
	(basically combining ListOfAll, SortDataArray, and SubstituteList).  Variables
	for this function are named identically to those in the fore mentioned functions.
	Please review those functions for details.	
	

function ArrayCompare ($a, $b)

	An internal function identical to the PHP function strnatcasecmp, except 
	ArraySort compares the values of $a[$this->sortingvalue] and 
	$b[$this->sortingvalue]. 
	
	

/***************************************************************************
//"universalcontentadmin.php"
/***************************************************************************

A child of UniversalContent, UniversalContentAdmin provides basic administrative 
control for a MySQL table.  The limitations of UniversalContent regarding 
database access also apply to universalcontentadmin.  Please note that the 
"Replacement Code" comments are tags for use with the class UniversalUpdater.  If you
are not using that class, you can remove the tags.

/***************************************************************************
//Class Variables
/***************************************************************************
	$tableformat: An internal array to keep track of the columns of MySQL table 
		with which the class will interact.
	$comments: A collection of comments to display to an administrator.
	$itemcount:  A counter for the number of items specified in $tableformat
	$defaultpadding: The default amount of space between the edge of the left
		edge of the screen and the items in the form.  Automatically calculated.
	
	
/***************************************************************************	
//Class Functions
/***************************************************************************
	
function universalcontentadmin ($paramtablename)
	
	Constructor - clears admin variables and calls the universalcontent constructor 

function SelectorListOfAll ($indexvalue, $othervalues, $replacementstring, 
	$blankstring, $label = 'Record: ', $alphabetize = UC_ALPHABETIZE_NONE, 
	$display=true, $selectorsize=1)

	Creates the options for a selector of all records in the table.
	
	$indexvalue: Name of the MySQL column which acts as an index.
	$othervalues:  A list of MySQL columns which should be queried
		in order to make the selector.  Items should be listed in a string 
		with commas seporating the items.
	$replacementstring:  A model of how the text of the options should
		appear.  The function will scan this string for variables listed
		in $indexvalue and $othervalues.  Variables should be preceded by '$'.
		Example:  '$recordname ($recordid)'.
	$blankstring:  The text which should appear if there are no records in the
		table.
	$label:  The text which should appear to the left of the selector.
	$alphabetize:  See universalcontent function SortDataArray for possible
		values.
	$display: Echo the results if true.  Return the results if false.
	$selectorsize:  Value to be added to HTML property size.
	
	

function CreateSelector ($indexvalue, $othervalues, $replacementstring, 
	$blankstring, $label = 'Record: ', $description = 'Record', $editoption=true, 
	$duplicateoption=false, $deleteoption=false, 
	$alphabetize = UC_ALPHABETIZE_NONE,	$selectorsize=1)

	Creates standarized form with selector and buttons for the page.  The form 
	created by this function will interface with the function ProcessUpdate ().
	
	See variable descriptions for SelectorListOfAll for all variables not 
	listed below.
	
	$description: Text indicating what kind of data is in the table.  Purely
		cosmetic.  Text is added to buttons such as "Edit ________" or
		"Delete ________".
	$editoption: Indicates a button to edit the record should be present.
	$duplicateoption: Indicates a button to duplicate the record should be 
		present.
	$deleteoption: Indicates a button to delete the record should be present.
	

function GetFileName ()
	An internal function to determine file for forms.
	

function TrueDisplay ($displayname, &$left, &$right)
	Internal function to help split display name information in the AddInt, 
	AddChar, AddText, etc. functions.
	
	$displayname: String with or without a UCA_DISPLAY_NAME_SPLITTER in it.
	$left: Part of $displayname to left of UCA_DISPLAY_NAME_SPLITTER.
	$right: Part of $displayname to right of UCA_DISPLAY_NAME_SPLITTER.
	

function AddInt ($databasename, $displayname, $displaywidth, $min=null, 
	$max=null, $key=false, $hidden= false, $spacing=null, 
	$minorspecial = false)
	
	Represents a column of the MySQL table with which the admin class
	will interact.  All Add___ functions should be called in order of their
	appearance in the MySQL table they will access.  Using this function
	allows the admin class to automatically generate tables to modify
	the database.  
	
	NOTE: Currently, the types of variables processed by UniversalContentAdmin 
	is limited.  If you wish to provide expanded modules copying the pattern
	of these functions or would like more features added to the Add____ 
	functions, please contact Arthur Lathrop at art@aaedesigns.com or 
	art@lathrop.com.
	
	$databasename: The MySQL column name for this column.
	$displayname: The "people-friendly" name you wish the administrator to see.
		If the $displayname has an UCA_DISPLAY_NAME_SPLITTER ('||') in
		its display name, the display will be split in half with the first part
		going to the left and the second part going to the right.  This is 
		useful for fields where you wish to have a symbol (such as a "$" next
		to the text field).
	$displaywidth:  Integer indicating how wide the text box should be.
	$min: Minimum value.  Null indicates no minimum value.
	$max: Maximum value.  Null indicates no maximum value.
	$key: Indicates this is an "index" value.  Generally should be
		used once and only once for any given table.
	$hidden: Indicates this is a value which the administrator cannot
		see or manipulate (it is included as a hidden field in the form).
	$spacing: The amount of spacing used in displaying the variable.
		Purely cosmetic.
	$minorspecial:  Indicates that the variable needs a little more
		processing than an integer, but essentially is a normal integer
		(example: a variable that for some reason could only be odd, 
		or an integer from which you want to remove commas before checking
		to make sure it is a valid integer). If this is true, the 
		override function ProcessMinorSpecialItem will be called before 
		any other value checking is carried out.  The function is called
		once for each variable which has minorspecial set to true.


function AddChar ($databasename, $displayname, $displaywidth, $length, 
	$key=false, $allowblank = true, $displayheight = 1, $hidden= false,
	$spacing=null, $minorspecial = false)
	
	Essentially the same as AddInt, except it adds input for a 
	character based string (text fields should use AddText, not
	AddChar).  See AddInt for descriptions of most arguments.
	
	$length: Maximum number of characters for variable.
	$allowblank: Variable can be equal to ''
	$displayheight: If not equal to one, class will use 
		textbox of $displayheight height instead of text
		field for administrator's input.
		
	
function AddText ($databasename, $displayname, $displaywidth, $displayheight, 
	$key=false, $allowblank = true, $hidden= false, $spacing=null, 
	$minorspecial = false)
	
	Essentially the same as AddInt and AddChar, except it is designed
	for textfields of unlimited length.  See AddInt and AddChar
	for details on function arguments.
	

function AddSpecial ($databasename, $displayname, $spacing=null)

	Allows programmer to create an entry which cannot be 
	accounted for with the simple AddText, AddChar, or AddInt 
	functions (such as selectors and variables which must
	cross-reference a number of items).  For such items to 
	be processed and displayed correctly, the user of the class
	must provide function overloads for ProcessSpecialItem and
	AdminDisplaySpecial.  These functions are called for each
	special variable.	
	

function AddFormBlankLine ()
	
	Inserts a blank line into the admin display.  Blank lines
	are simply comments with an EOL symbol.  There can be only
	one comment or blank line between any given entry.  To 
	add more than one, use AddFormComment
	

function AddFormComment ($comment)

	Will insert a comment after a variable on the admin page.
	An EOL ("\n") can be used to insert line breaks in the comment
	or allow for more than one line break.  You can only have
	one comment or blank line between two variables.
	
	$comment: A string comment.
	

function SplitPadDisplay ($itemproperties, $padding)

	An internal function which formats the variable display names
	and properly pads them with spaces.
	
	$itemproperties: Database name of variable.
	$padding:  The amount of space the display name plus white spaces
		should equal.
		

function GenerateItemLine ($itemname, $padding=30, $display = true)

	Creates the HTML code to display a single line of the admin forms.
	
	$itemname: Database name of the variable.
	$padding: The default amount of space which the display name and 
		white space should occupy.
	$display:  If true, results will be echoed.  If false, results will
		be returned by the function.
		

function GenerateAllItems ()

	Internal function to create form output for each variable.	
	

function GenerateForm ($description)

	Creates the input form for all variables of a given table.  Results
	are echoed to HTML and are compatable with the ProcessInput function.
	
	$description: A label for the record.  The description is cosmetic
		and used on the button "Add/Change ___________."
		
		
function MakeDBFriendly (&$key, &$val)

	Makes sure variable is appropriate for a MySQL query.  Currently,
	function only covers integers and strings. 
	
	$key: Database name of variable.
	$val: Current value of variable.

	
function ProcessEditDup (&$warning, &$reporttext)
	
	Internal function to process the Edit/Duplicate button.
	
	$warning: Indicates whether there was an error or not.
	$reporttext: Returns message if necessary.

	
function ProcessDelete (&$warning, &$reporttext)

	Internal function to process Delete button.  See ProcessEditDup 
	for details on arguments.
	

function ProcessUpdate (&$warning, &$reporttext)
	
	Internal function to process Add/Update button.  See ProcessEditDup 
	for details on arguments.	
	
	
function ProcessIntItem (&$key, &$val, &$warning, &$reporttext)

	Varifies integer matches specifications indicated in AddInt.
	
	$key: Database column name.
	$val: Input value.
	$warning: Indicates whether there was an error or not.
	$reporttext: Returns message if necessary. 
	

function ProcessCharItem (&$key, &$val, &$warning, &$reporttext)

	Processes both AddText and AddChar variables.  See ProcessIntItem.
	

function ProcessUpdateItem (&$key, &$val, &$warning, &$reporttext)

	Determines and calls the appropriate function for each variable in
	$tableformat.  See ProcessIntItem for details on arguments.
	

function VarifiyAndProcessInputData (&$warning, &$reporttext)

	Internal function which goes through the $tableformat and processes
	each variable.  It returns the "values" portion of a MySQL replace 
	query.  
	
	$warning: Indicates whether there was an error or not.
	$reporttext: Returns message if necessary.	
	
	
function RecyclePostedData ()
	
	Processes posted data so it can be reused in a form (in particular it
	removes slashes if there is an error in the input).
	

function ProcessInput (&$warning, &$reporttext)
	
	Function processes any form created by universalcontentadmin.
	
	$warning: Indicates whether there was an error or not.
	$reporttext: Returns message if necessary.		


/***************************************************************************	
//Class Override Functions
/***************************************************************************

These functions allow easy customization for child classes of universalcontentadmin.
All $warning and $reporttext arguments are as follows:
	$warning: Indicates whether there was an error or not.  
	$reporttext: Returns message if necessary.	
	
In general, it is safe to assume that $warning is not false before processing one
of these functions.  Returning a $warning of false will generally stop an item
from being processed immediately.  

function ProcessPreDelete ($indexfield, $indexvalue, &$warning, &$reporttext)

	Executed after all verifications, but before record has been deleted from 
	database.
	
	$indexfield: Name of table key column.
	$indexvalue: Value of said column in a given record.


function ProcessPostDelete ($indexfield, $indexvalue, &$warning, &$reporttext)
	
	Identical to ProcessPreDelete, except it is executed after a record has been 
	removed	from the database.
	

function ProcessUpdatePreGenerateQuery(&$warning, &$reporttext)

	Executed after all verifications, but before database query to add record has been 
	generated.
	

function ProcessUpdatePreQuery(&$warning, &$reporttext)

	Executed after all verifications, but before record has been updated/added to 
	the database.
	
	
function ProcessUpdatePostQuery (&$warning, &$reporttext)

	Executed after all verifications and after record has been updated/added to the database.


function AdminDisplaySpecial ($itemname, $padding)

	Display nonstandard variables for editing. 
	$itemname: Database name (check for input via $_POST[$itemname] (prefered) or 
		$_REQUEST[$itemname].
	$padding: The recommended space an item's display name and white space should consume.

function ProcessSpecialItem ($variablename, $value, &$warning, &$reporttext)

	Process input from special items.  Should return an entry for the database.  
	If $val is invalid, set warning to true and give a report.
	
	$variablename: Database name.
	$value: Value to be displayed
}

function ProcessMinorSpecialItem ($variablename, $value, &$warning, &$reporttext)

	Process variables with some special quality which only affect how they should 
	be interpretted initially. Such items, for example, could include IDs (which 
	are essentially text, but have "illegal characters) or text fields which should 
	not allow HTML, php, etc. This is processed before any other checks are done 
	and as such could be used to "prep" a variable for normal processing.
	
	$variablename: Database name.
	$value: Value to be displayed
}

