SmartyDocB Files

See now the documentation in documentation.xml (The information below might be a little outdated
in places.

Important setup notes: 

To utilize "doc_info" and "doc_raw" (as in previous versions) instead of the now default "info" 
and "moveto" functions, you will need to refer to these functions respectively as strings 
within the constructor.

The following must refer to your own relevant site directory.
site_root_public: used as a base for main files (e.g., for writing to a main site CSS file)
site_root_hidden: used as a target for hidden files (e.g., if you are embedding publicly hidden 
notes across your files--this feature assembles those notes into one place); this directory 
should be out of the publicly-accessible directory (e.g., above /htdocs in Apache) if you want 
to avoid the chance for others to guess its location! Although I think the script should work 
as intended, if you have very sensitive content, you might not want to add them through this 
script; the main idea was to allow you to embed programming to-dos and notes within your 
templates and be able to retrieve them later all in one file automatically

// You should also set the following (if you are using them) or otherwise set auto_xform_mobile 
//   to false
Browscap_cache_dir
Browscap_file
If you want to use browscap or browscap.ini to allow your pages to be auto-transformed into 
XHTML Basic for cell phones, be sure to copy the XSL stylesheet specified at "xhtmlbasic_xsl" 
below and set its value to your local file location; otherwise, the transforms will take much 
too long.

You will also surely want to turn $rewrite_docraw_on to false after debugging but before going 
live so that rewrites (e.g., of the main site's CSS file) will not be performed on each script 
execution! You may also want to set rewrite_docraw_get to false or at least change the name of 
rewrite_docraw_get_url if you don't want others to be able to selectively force a rewrite of 
those files on the live site (it is there for your testing and debugging convenience). You have 
the same options with $comments_get and $comments_get_url (to turn on all of the comments 
through a URL) as well as with $whitespace_get and $whitespace_get_url (to strip some, all, or 
none of the extra whitespace).

You will probably want to also set the public $comments item to false (or tweak the related 
comments object variables) once you go live, since quite a few comments can be added and this 
can slow things down during loading time (they also make reference to your template file names 
if not locations)

One very necessary tip for debugging if you decide to tweak the code at all (especially the 
prefilter or changing the tag/c delimiters too!)...Be sure to delete both your caches and 
compiled template files!

// If you want to still allow {} in literals, you should find and change this line in 
//   Smarty_Compiler.class.php to the following:
return "<?php echo '" . strtr($block[2], array("'"=>"\'", "\\"=>"\\\\")) . "'; ?>" . $this->_additional_newline;
return "<?php echo '" . strtr($block[2], array("[[["=>"{","]]]"=>"}", "'"=>"\'", "\\"=>"\\\\")) . "'; ?>" . $this->_additional_newline;


// Dependencies:
// To use XSL transforms, one must have installed the XSL extension (the update of the 
    "XSLT" extension from PHP4). See http://php.net/XSL
// To use Tidy, one must have this extension installed (for PHP5). See http://php.net/tidy
// To use Browscap, one must have it installed and follow its licensing--use of the 
    browscap.ini database (from http://browsers.garykeith.com/index.asp ) is under Creative 
	Commons Attribution-Non-Commercial (or get its author's permission) whereas the PHP class 
	for Browscap (from http://garetjax.info/projects/browscap/ ) is under the Creative Commons 
	Attribution-Share Alike 2.5 License).

// Note that in doc_raws (or in style/script doc_infos with content), in order to have escaping 
    of braces (curly brackets) work within, the target attribute (or script/style attribute) must 
	be the first attribute

// Note that when $rewrite_docraw_on is true, the styles generated by the external doc_raws for 
    that set of template(s) will be replaced (if they already existed) and placed at the top of 
	the preexisting file(s). They are placed first so that later cascading will force designer 
	to see that new changes may be being overridden by styles added from other templates (and 
	comments are always auto-created for external doc_raws (out of necessity in order to know 
	where to find the portion of the file that should be replaced), so you can see where the 
	other styles/code is coming from).

// Note that if using a root doc_info, it can have any attributes, though some other common 
     ones are listed in the 'optional' section as a general guide, not actually enforced. Other 
	 common ones not listed would include prefixed namespaces (remember to use "__" instead of 
	 ":", however).

// Tagc/tag functions can also process any attributes not used by the function (useful for 
    adding XML with styles)

// Note that for those new to XHTML-treated-fully-as-XML, it is recommended when serving 
    files as application/xhtml+xml (attempted if the $xml_plain attribute is true and the 
	file is XHTML) it is recommended to avoid inline scripts/styles.

// Note that although I have changed the default of XSL types to "application/xml", I have 
    ready that Explorer may only work (incorrectly) with "text/xsl". Given that Firefox also 
	supports the latter, you may wish to change the default to the latter (though I've tried 
	to stick to the correct convention).

// Note I have added "bom" for "byte-order mark". You will probably not need this unless 
    dealing with UTF-16 (e.g., for documents with mostly Chinese characters). If you do need 
	it, simply use it like in this example: {doc_info bom="&#xFEFF;"}   . You can't just add 
	the mark to the top of your text because this script places such things as XML 
	declarations, etc. ahead of your own content (unless called by a doc_info or doc_raw).

// For plain (non-HTML) XML, one can of course also use XML declaration, XSL, and XML 
    Schemas, doctypes and dtd (internal or external references), CSS (will be external only 
	and as a xml-stylesheet processing instruction), notes (which if shown, are only comments). 
	However, one can also use body, body_post, head, and head_post in plain XML (with the 
	object variable $xml_plain set) as they will not have the head/body tags printed (simply 
	to target XML toward the top, top-middle, bottom-middle, or bottom of the document). 
	However, if the type is specified in some way as XHTML, it will try to print the tags 
	and any attributes specified (in the case of "head" and "body").
		
// Note that the prefilter with regexps can be unregistered with a simple call to 
     $smarty->no_prefilter(); some heavy regular expressions can be avoided.
	
// If you wanted to just work with XML or HTML as template files (i.e., without PHP 
    adding any template variables for you, but you wanted to take advantage of doc_raws 
	shuffling of content or doc_infos), after requiring all of the necessary Smarty files 
	(including this one), you might simply consider a PHP script like the following 
	(bearing in mind security concerns):

/*
// $smarty->xml_plain = true; // Uncomment if you want to work with XML
// $smarty->add_openclose = false; // Uncomment if you want to work with XML

$tpl = $_GET['tpl'].'.tpl';
if (file_exists($smarty->template_dir.'/'.$tpl)) {
	$smarty->displayDoc($tpl);
} // end if
else {
	print "Template could not be found.";
} // end else
*/
// You could thus have a URL like the following work: http://example.com/portal/index.php?tpl=myxhtml (where myxhtml.tpl was a template in your template directory)

// If you wanted the opposite of the above (i.e., just to work in PHP without templates--e.g., for testing), consider using the addRaw functions (perhaps on contents gathered by ob_get_clean() after a ob_start() call within the PHP script) on a blank template, then calling displayDoc on the blank file
/*
$avar = "Some";
$postcontent = <<<HERE
<!-- {$avar} content on each page but not on any template -->
<posttag attr="value">post content</posttag>
HERE;
$smarty->addRawContent($precontent, '', 'head_post');
$smarty->displayDoc('blank.tpl');
*/

// Future programming notes: 
// doc_infos might be integratable into their own repeatedly called function as the 
     doc_raw_head_build and doc_raw_build functions are to enhance maintainability (but then 
	 again, the code for doc_infos may vary a lot in each instance)
// Could put class and element (including pseudo classes) into object var that is retrieved 
     later (or do regexp's within) and grouped together by element or class or element.class, 
	 etc. (including pseudo) rather than tagc/tag functions repeating the specification of the 
	 same element or class in CSS (and its attendant auto-added comments)
// If we could utilize some open-source XML validator (or more specifically one with an API to 
    just the DTD/XSD interpretation), we might remove redundancy (and need for manual maintance 
	of what is allowable in doc_infos)
// If integrating the doc_infos into a common function could make sure that if the file were 
     XHTML 1.1 or higher, "lang" would not be printed (and would be replaced with xml:lang)
// Also, as with the tagc/tag functions, one could make equivalent functions to shuffle off 
    script functions enclosed within an onclick using an attribute to represent the function 
	name (or if none is present, to auto-create a function name), for example

// Notes to self!

// I added the && $this->HTTP_ACCEPT !== 'text/html' conditions within the outputfilter 
    (when xml_plain was on--to try to serve without any XML elements like XML Declaration 
	or xml-stylesheet, etc. when the browser didn't support it) during testing, but they may 
	not really be necessary, as the problem may have more been the fact that I hadn't served 
	a "rel" attribute when printing out the link element for these visitors (those to whom I 
	was trying to serve as application/xhtml+xml but who could only accept text/html). Though 
	I did just discover now that although Explorer 7 doesn't _mind_ an xml-stylesheet also 
	(nor the XML Declaration), it must have a link element to process it, so it is of no use 
	anyways to serve the xml-related instructions when trying to serve as XML but where the 
	browser doesn't accept it. One potential pitfull to watch out for though is that one would 
	need separate caches for each type (and this program is setting/detecting them during 
	output time (the outputfilter), so one would have to find a way to add this information 
	to the caching conditions, assuming it is possible (or get the contenttype earlier).

// Change doctype, dtd, head, body, entity, so that they can accept multiple blocks, but into 
    the same place?
// Note that one should use 'file' instead of 'subtype' in 'entity' docraws in order for the 
    file to be created
// If multiple doc_raws exist for the same file (e.g., if specifying keys), make only one 
    at most contain an xform=true

// Todo: documentation: the documentation should be transformed successfully into XHTML on 
    the server-side (but there is presently an issue with the xsl:number count attribute 
	getting processed all right)
// Todo: document 'include_in_xml' differences with HTML inclusions
// Todo: documentation: should 'css' have all those attributes (since sometimes it can 
    create a 'link')
// Todo: I haven't documented 'langu' attribute within 'script' (it probably should be 
    optionally allowable for style too since content can be added with via 'content' 
	property (other ways?), as well as numbering, etc., not to mention just wanting 
	different styles for each--e.g., background pictures, etc.)
// Todo: Need to streamline behavior of 'body' and 'head'. The latter detects plain XML 
    and doesn't create the element, while the former does create it even if the type is XML.
// Todo: Streamline doc_info/doc_raw documentation so that each section follows same 
     pattern of 'required attributes', etc. 
// Future todo: Once code is changed to 'moveto', etc., the documentation should reflect it.




// Previous changes:
 /* Changes
  * 2006-Okt-15:
  *	   tdmme, I moved the if-statement that sets the page content-type of the header,
  *	   from the constructor to a separate function called 'setContentType()' and
  *	   added a call to that function at the beginning of the 'smarty_outputfilter_SmartyDoc'
  *	   function. This way the $this->doc_info array is NOT empty, like it was in when
  *	   it was in the constructor. Now the automatic content-type recornizion works.
  */