Molly
Version 10 release beta 1
Copyright 2000-2012 by Ronald P. Vullo, Ph.D.
rpv(a)mail.rit.edu
molly.rit.edu

These notes are here for PHP programmers interested in understanding how Molly works "under
the hood" but are primarily notes for the active developers of the core Molly code. Please 
note that there is no need to understand or program PHP to use Molly. Molly is open source, 
so if you make improvements or extensions to Molly please share them with us so that we can
roll them into the next release.

	Molly's Default behavior is to consider the extension of the files and processes 
	them as follows:
	
	Extension     Action
	----------------------------------------------------------------------------------
	.php          Process as normal php, no Molly functionality
	
	.inc          PHP include files
	
	.html         Process similarly to Molly 1, that is, set all the globals and include
				  basic function and object libraries and module libraries, then procede
				  to pass the file through the php parser.  (Note that for normal HTML
				  files this does essentially nothing, but that it allows you to minimally
				  incorporate some of Molly's functionality if you understand the 
				  underlying architecture.)
	
	.maml         Set all the globals and include all the libraries and modules, then
				  parse the file through Molly's MAML XML parser.
	
	.tplt         template files
	.ini          prevent being served to the web
	.txt          (Maybe turn into a nice formatted web page?)
	.mss & .css   Treated like a template file - that is, all *[tokens]* are replaced 
				  with config values
	
	
	
	
	Naming Conventions
	
	Prefix      Example             Meaning
	----------------------------------------------------------------------------------
	$gv_        $gv_VarName         Global Variable (will be found in $GLOBALS)
	$fv_        $fv_VarName         Variable with scope local to a function
	$go_        $go_ObjectName      Global Object
	$fo_        $fo_ObjectName      Object  with scope local to a function
	$pv_        $pv_ParemeterName   Parameter passed to a function (function scope)
	$po_        $po_ParameterObject Object passed to a function (function scope) or class
	$t_			$GET['t_Name']		Tokens passed via the query string
	
	maml_       maml_TagName        Class name for MAML Tag
	molly_      molly_ClassName     Class name for non-tag objects used in Molly
	
	molly_      molly_TableName     Database Table specific to Molly
	
	m_          m_FunctionName      Function that is part of Molly
	
	MOLLY_      MOLLY_CONST_NAME    Molly Constants
	
	
	
	Inline Documentation
	
	When defining a maml_ class to create a new tag programmers must take care
	to set the $doctext to explain the use of the tag. This will allow Molly to
	generate user documentation which is accurate and current with the code and
	better able to withstand versioning. We will use PHP's Nowdoc syntax
	(http://www.php.net/manual/en/language.types.string.php#language.types.string.syntax.nowdoc)
	to accomplish this.
	
	
	Molly System Constants
	
	Constant                        Value
	----------------------------------------------------------------------------------
	MOLLY_SYSTEM_DIRECTORY      Unix Path to Molly's system directory (core functionality)
	MOLLY_INI                   File Name of This Site's .ini file (allows multiple sites
								to share the same codebase by having different .ini files)
	
	
	Molly System Globals
	
	Global                         Value
	----------------------------------------------------------------------------------
	Config Table generates $gv_Config array which is used to replace *[ ]* setting names with values
	
	
	
	Molly Utility Functions
	
		m_AppendJavaScript($pv_Scripts, $pv_ScriptName, $pv_AllowDuplicates) [system/core/40_tags.inc]
			Adds $pv_Scripts to the JavaScript section in the head of the page.  
			$pv_ScriptName is tracked to know which scripts have already been added.
			$pv_AllowDuplicates is FALSE by default.
		
		m_AppendQueryString($pv_Key, $pv_Value) [system/core/40_tags.inc]
			Allows Molly to dynamically create the querystring for links such as 
	
		m_AppendStylesheet($pv_Styles, $pv_StyleName, $pv_AllowDuplicates) [system/core/40_tags.inc]
			Adds $pv_Styles to the stylesheet in the head of the page
			$pv_StyleName is tracked to know which styles have already been added.
			$pv_AllowDuplicates is TRUE by default.
	
		m_ArrayLastKey($pv_TheArray) [system/core/80_environment.inc]
			Returns the last key of an array
	
		m_AutoInclude($pv_PathToIncludesDirectory, $pv_FileExtension) [system/loader.php]
			Includes all the files in a directory with the specified extension
	
		m_CheckLogin($pv_LoginName, $pv_Password) [system/core/27_security.inc]
			returns user_id for successful login, FALSE for failed login.
	
		m_DateGMT($p_UnixTimeStamp) [system/core/10_date_time.inc]
			Converts a Unix timestamp to a formatted date, adjusted by user's timezone
	
		m_debug($pv_TheDebugString) [system/core/80_environment.inc]
			Caches debug string for output after parsing completes. (see system/parser.php)
		
		m_DoLogin($pv_UserID) [system/core/27_security.inc]
		 	Creates session variables to make a user logged in
	
		m_DoQuery($pv_Query, $pv_HostName='', $pv_User='', $pv_Password='', $pv_Database='', $pv_DatabaseApp='') [system/core/20_database.inc]
			Does a query and returns record set of the results.

		m_EchoModulesDocs() [system/core/70_modules.inc]
			Checks for the existence of docs.htmf file in each module directory (as
			specified in the molly.ini [Modules] section) and echos it (or a file not
			found message). This function is used in the docs page.
	
		m_FetchDBHash($pv_Query, $pv_HostName='', $pv_User='', $pv_Password='', $pv_Database='', $pv_DatabaseApp='') [system/core/20_database.inc]
			Does a query and returns an array of associative arrays (array of hashes)
	
		m_FetchRecordsArray($p_TableName, $p_Fields, $p_Query, $p_OrderBy="", $p_Limit="") [system/core/20_database.inc]
			Wrapper function for m_FetchDBHash that builds the SQL from appropriate pieces.
			
		m_GetDocument ($pv_URL) [system/core/15_file.inc]
			Returns the text of a file specified by $pv_URL
	
		m_HashArrayToXML [system/core/30_XML.inc] /* Not Currently Used */
			
		m_ImplementedTags() [system/core/80_environment.inc]
			returns an array of class names for implemented tags.
	
		m_Interpolate($template, $hash, $prefix = '*[', $postfix = ']*') [system/loader.php]
			Replaces placeholders in a template string with values from a hash
	
		m_IsMollyTag($pv_TheTagName) [system/core/80_environment.inc]
			Checks a string to see if it's a defined Molly tag classname

		m_LoadModules() [system/core/70_modules.inc]
			Loads modules specified in the molly.ini file for the site in
			the [Modules] section.
	
		m_MakeUnixTimestampGMT($hh=0, $mm=0, $ss=0, $m, $d, $y) [system/core/10_date_time.inc]
			Creates a unix timestamp from hour, minute, second, year, month, day
		
		m_NakedHTML ($pv_URL) [system/core/15_file.inc]
			Returns the text from between the  tags of an HTML document specified in $pv_URL
	
		m_ParentDir($pv_Path) [system/loader.php]
			Returns the parent directory pasth of the unix file path passed to it.
	
		m_PullParse [system/core/90_parser.inc]
			This is the actual XML parsing function that does Molly's magic. Starting 
			with this version of Molly the parsing is done using the XMLReader extension 
			(http://us.php.net/manual/en/intro.xmlreader.php).  Previous versions used 
			the expat XML Parser (http://us.php.net/manual/en/intro.xml.php).
	
		m_sess_close [system/core/25_sessions.inc]
			Callback function for session_set_save_handler() allowing Molly to store 
			sessions and associated information in a database table.  Among other 
			things this allows us to easily determine who's logged in, and to share 
			sessions across multiple web servers.
	
		m_sess_destroy [system/core/25_sessions.inc]
			Callback function for session_set_save_handler() allowing Molly to store 
			sessions and associated information in a database table.  Among other 
			things this allows us to easily determine who's logged in, and to share 
			sessions across multiple web servers.
			
		m_sess_gc [system/core/25_sessions.inc]
			Callback function for session_set_save_handler() allowing Molly to store 
			sessions and associated information in a database table.  Among other 
			things this allows us to easily determine who's logged in, and to share 
			sessions across multiple web servers.
			
		m_sess_open [system/core/25_sessions.inc]
			Callback function for session_set_save_handler() allowing Molly to store 
			sessions and associated information in a database table.  Among other 
			things this allows us to easily determine who's logged in, and to share 
			sessions across multiple web servers.
			
		m_sess_read [system/core/25_sessions.inc]
			Callback function for session_set_save_handler() allowing Molly to store 
			sessions and associated information in a database table.  Among other 
			things this allows us to easily determine who's logged in, and to share 
			sessions across multiple web servers.
			
		m_sess_write [system/core/25_sessions.inc]
			Callback function for session_set_save_handler() allowing Molly to store 
			sessions and associated information in a database table.  Among other 
			things this allows us to easily determine who's logged in, and to share 
			sessions across multiple web servers.
			
		m_ShowINI($pv_VariableName) [system/core/80_environment.inc]
			debugging tool for outputting two dimensional arrays as are read from INI files
	
		m_testDOMi [system/core/30_XML.inc] /* Not Currently Used */
			
		m_TimeGMT($p_UnixTimeStamp) [system/core/10_date_time.inc]
			Converts a Unix timestamp to a formatted time, adjusted by user's timezone
	
	
	Universal Tag Methods
			
		$this->docs()
			Returns the tag documentation stored in the protected $this->doctext variable.
			This allows us to generate the tag reference documentation (See Appendix II in
			m9r0d1/docs/index.maml) automatically from all properly defined maml_ tag classes.
	
		$this->echoTemplate($pv_TemplateFile, $pv_TemplateVariables) 
			fetches template file, then If $pv_TemplateVariables is undefined/false, 
			echo template, otherwise uses $pv_TemplateVariables hash to replace
			*[HashKeyName]* placeholders with associated hash values in template before
			echoing.
			
		$this->fetchTemplate($pv_TemplateFile)
			Reads template file and returns it.  No file locking as template files
			should not be modified by Molly.
		
		$this->function id()
			Generates a CSS/JavaScript ID unique on the current page.
	
		$this->token()
			Creates a unique key (32 character hexadecimal string) like: ef5442d2c8afb84fe938cb64f1368bcd
		
		$this->startCache()
			Begins caching output to $this->tagCache
		
		$this->finishCache()
			Finishes caching output to $this->tagCache
		
		$this->splitAttribute($pv_Attribute)
			Creates an array from a comma or space delimited list of items.
	
	
	
	To Do:
	
		Session tag - maybe a set variable tag with a persist option? (get variable tag?)
	x	fix path to stylesheet
	x	Implement Sessions: why is nothing going into sessions table? OK, I think I finally got this working 12/22/09
	x	implement stylesheet
	x	implement colorize
		maml:colorize tag, then redo docs/colorize.html
	x	Incorporate various time & date functions & rename/review/rewrite from old format.php module
		Clean Up/re-write Calendar (way too many globals, etc.) add style attribute
		Implement translation object
		complete proper file extension handling (parser.php, molly.ini)
		implement  for download-resistant images and watermarks
	x	implement  (mostly functional now)
	x	override  tag to add styles and javascript
	x	override  tag to add doctype, etc.
		finish re-writing forms
	x (partial)	add debug variables to molly.ini and incorporate into debugging code
		finish select tags:
			record tag's maxentries attribute
			numrecs
			previous
			next
			pages
			detail
	x		sort
	x	Fix queries to deal inteligently with empty result set:
			Warning: Invalid argument supplied for foreach() in /Volumes/VulloFirewire/rvullo/Sites/m9r0d1/system/core/20_database.inc on line 82
		When submiting multiforms, t_Link should be something reasonable
	x	Keep track of whether or not a style or javascript has been added to the head via m_AppendJavaScript() and m_AppendStylesheet() (the config array)
	
	x	maml:sort
			create sortable column headers inside maml:fetch
	
	?	maml:picklist - wrapper around maml:fetch?
		maml:column
	
		maml:detail
			 display selected record
		
		re-implement as format attribute to maml:field?
			maml:dayfield
			maml:timefield
			maml:urlfield
		
		maml:pages
		
		maml:numrows
		
		maml:next
		
		maml:previous
		
		maml:template
		
		maml:time
		
		maml:date
		
	x	maml:private - renamed maml:protect
		
	x	maml:multiple check to make sure it's done
		
		maml:comments
		
		maml:login
		
		maml:httpheader
		
		maml:phpinfo
		
		maml:if
		
		maml:else
		
		?	maml:setcookie
			maml:clearcookie
			maml:showcookie
		
	x	maml:block
			fix new insert
		
		maml:blocklist
		
		maml:rss
		
		maml:syndicate
		
		?	maml:breadcrumb
		
	x	maml:menu - partial
		
		maml:menuitem (rename maml:item?)
		
		maml:setvariable - need better name - integrate with sessions? 
	
	
	
	/*
		http://www.php.net/manual/en/language.constants.predefined.php
		http://us.php.net/manual/en/function.opendir.php
		http://us.php.net/manual/en/class.recursivedirectoryiterator.php
		
http://techtrouts.com/mac-mysql-does-not-connect-on-localhost-but-connects-on-127001/

	*/
	
	
	find:
	(.*)\r
	
	replace:
		if ($this->\1) {
			$fv_TemplateVars['\1'] = ' \1="' . $this->\1 . '"';
		} else {
			$fv_TemplateVars['\1'] = '';
		}