SmartyDocBBrettZamir2007Brett ZamirAcknowledgmentsMany thanks to "boots" for getting me interested in his useful and well-written SmartyDoc code by providing it open source, by answering my questions, giving helpful feedback, and by encouraging my participation. I would also like to thank "vain" for helping out, and despite having only just joined in on the development (around 3/07) has made some very helpful improvements and ideas for the future. The PHPDocumentor documentation was by his doing.While the implementation and functionality is slightly different, I owe the idea of the partial-page XSL conversions to Richard Bateman's SomeXSLTPlugins and Serge Stepanov's XSLT block function. Thanks are also definitely in order to Jonah Winters, who has generously and patiently enabled me to work with him on his Bahá'í Library Online site.IntroductionSmartyDocB is a tool for Smarty to allow you to edit XML (including XHTML) or plain HTML in a flexible fashion. It is a fork of the original SmartyDoc plugin by "boots". This documentation itself was created using SmartyDocB.While the separation of data, structural output, styles, and localization indeed holds many desirable benefits and has been made possible via XML, XSLT, CSS, and XML entities respectively (not to mention the separation of (PHP) server-side code from data/structure/styles/localization brought by Smarty templating), all of this separation can become a hassle--both in terms of managing different files (e.g., opening them, referencing them, etc.) and switching back-and-forth between them. Sometimes, it would be nice to have the ability again (as with an old HTML page) to look at a file and understand what type of data, styles, and localized content (i.e., translations) were intended to go within that page. This holds true even for files which we have ourselves created, as it can be hard on our memories--even in the short-term--to understand a page without any concrete examples of intended output, styles, and localization being made within it.SmartyDocB makes it possible to have the best of both worlds. One can stuff all of the above into one's templates if desired (e.g., data, styles, scripts)--while having the output shuttled off into different directions (e.g., into the head of the document, into separate files, or into one site-wide file for scripting, styles, localized content, etc.). SmartyDocB will also add comments/notes to the files where the content was moved (and optionally within the main output document), in order that when viewing the resulting files, you or your designers can know the name of the template from which the various content there originated.In addition to the possibilities of including style and script content that is shuffled away, one can also shuffle away the following to a site-wide file or to separate files: XSL, DTDs, XML Schema, entities, and even notes to yourself (which you can either hide or reference in the comments). Various other tags can be invoked from anywhere within a template to be created in the proper sequence within the head of an XHTML document (e.g, title, meta, link) or an XML/XHTML prolog (e.g., XML declaration, processing instructions, internal doctype, etc.), and generic content can be sent to various general parts of a typical document such as before the root element (prolog), to the head (epilog) or body (post-epilog), or after the root.While the shuffling of content in SmartyDocB generally occurs one whole block at a time, the tag/tagc functions also enable one to have style data shuffled away to the head of the document or to an external file while the style assignment itself is attached to just a single tag. This allows a person to replicate the functionality of the now-deprecrated "style" attribute in XHTML without it showing up in the source code as such. However, it goes beyond the "style" attribute in that one can decide how to treat it--whether to add the style information to the stylesheet using the element's id, or to reuse that style by assigning the style to a whole element and/or class. An id or class will even be auto-created if none were manually added. These functions (which can appear similar to a regular XML tag) allow for more portability, since, to make changes, one does not need, for example, to change the class name in both the head and in the document when making a class name change. And, this offers the ability to place the styles exactly where you are really using them (or where you first use them)--directly within such an element. This will thus allow you to both visualize your data with your desired styles, but let the data also be reused, and take advantage of the other benefits of external stylesheets--e.g., browser caching.SmartyDocB also seeks to automate certain aspects of writing XHTML and XML so that common tags, headers, etc., can be auto-created. The application also makes XML easier in other ways (e.g., partial or complete server-side XSL transformations, Tidying of output, creation of CDATA sections, managing whitespace, etc.).SmartyDocB is intended to make XML more fun and manageable than would otherwise be possible with expecting you to separate all the components of your pages from the get-go. It is intended to allow you to write and edit in a more organic fashion, while still producing documents which offer cleanly-separated PHP, data/localizations, structure, styles, client-side scripts, etc.Questions on setup or use are also welcome in the forums as is any feedback.Installation and set-upSmartyDocB must have the class required along with the Smarty class and then create a new Render_SmartyDoc object (instead of creating just a regular Smarty object):require($smarty_dir.'/smarty/libs/Smarty.class.php');
require($smarty_dir.'SmartyDoc2.class.php5');
new Render_SmartyDoc();This will create an object that will let you use the default 'doc_info' and 'moveto' functions.Note that this manual and the program's API, for historical reasons, still refer to 'moveto' as 'doc_raw'. However, within templates, you can use the preferable function name 'moveto'. For example,
{moveto target=head}<-- head items -->{/moveto}
To use the older terms (or other ones) within the template as well, the desired terms can be added, respectively, to the constructor call:require($smarty_dir.'/smarty/libs/Smarty.class.php');
require($smarty_dir.'SmartyDoc2.class.php5');
new Render_SmartyDoc('doc_info', 'doc_raw');One could thus use the older:
{doc_raw target=head}<-- head items -->{/doc_raw}Future editions of this program will probably move exclusively toward "moveto", so please use that within your templates for now.As with Smarty, you'll need to define the following directories:$smarty->template_dir = $sm_base_dir.'/smarty/templates';
$smarty->compile_dir = $sm_base_dir.'/smarty/templates_c';
$smarty->cache_dir = $sm_base_dir.'/smarty/cache';
$smarty->config_dir = $sm_base_dir.'/smarty/configs';The following must refer to your own site. Note that to change their setting you must first make the above call to construct the smarty object, and then reference your Smarty object such as follows: $smarty->site_root_public = '/home/main/public_html';$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 or /public_html in Apache) if you want to avoid the chance for others to guess its location! Although the script should work as intended, just to be sure, if you have 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 for your site (if you are using them) or otherwise set $auto_xform_mobile to false:$Browscap_cache_dir$Browscap_fileIf 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 save a copy of the XSL stylesheet from the W3C site to your own system and then set $xhtmlbasic_xsl to the location of your local file; otherwise, the transforms will take much, much too long if you try to reference the file above directly! One unfortunate inevitable inadequacy of any such XHTML to XHTML Basic transformation is that this stylesheet won't work properly if your page has nested tables, since XHTML Basic doesn't support them, and the stylesheet doesn't know how to convert them.You will also need to consider the following important settings:In order to avoid constant file-rewriting, the default value of $rewrite_doc_raw_on is set to FALSE. However, please realize that in such a case, no externally targeted doc_raws will be written if you do not at least once set this to true and visit the page! You can then set $rewrite_docraw_on back to FALSE after debugging (but preferably 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).Note that when $rewrite_docraw_on is true, the styles (and scripts, etc.) 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 the 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 for the script 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).You also have the following options (the following are all on and set by default, so you'll need to turn them off if you don't want this available to your site's users--and for extra security, you may in fact wish to turn them off unless you are debugging or if your site wishes to be especially open in sharing its content):
With $comments_get set to TRUE and a URL GET string set for $comments_get_url to turn on all of the comments in the output document (if caching is not on) through a URL GET request.You can also optionally strip some, all, or none of the extra whitespace with a URL request when $whitespace_get is set to TRUE and $whitespace_get_url has a URL GET string set.With $xform_get set to TRUE and $xform_get_url set to a GET string, you will be able to circumvent all server-side transforms and allow the transformation to be done client-side. Be aware that this will allow your site visitors to see the generated XML document as well as your XSL stylesheets.And one can have $xformtobasic_get set to TRUE with $xformtobasic_url string defined in order to allow a URL request to transform the document into XHTML Basic, using the file at $xhtmlbasic_xsl for the transformation (please do not use http://www.w3.org/2003/04/xhtml1ToBasic.xsl directly but instead go to this site, save a copy of this file on your system, and reference it within the $xhtmlbasic_xsl class variable to avoid long delays at your site and undue calls to the W3C site!). XHTML Basic is used by devices such as cell phones, and although this script offers the possibility for auto-detection of mobile phone devices and automatic server-side transformation of your pages into XHTML Basic, you may wish to keep a GET request available for either yourself during debugging (if you want to see how the page will appear to cell phones), or to mobile phone users directly in case the transformation is not made.
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, but then again, so are comments referring to your template file names also necessarily added within your attached CSS/script/etc. files which can be viewed publicly anyways).$debug is set to true, but you may wish to set it to FALSE so that things like your XSL file location will not show up in the error output in the event that there is a failure in making a stylesheet transformation.Finally, instead of using $smarty->display() to display your template, you will invoke "displayDoc", such as:
$smarty->displayDoc('mytemplate.tpl');
As with Smarty's 'display' method, 'displayDoc' allows you to add a pipe-separated sequence of variables for conditional caching. For example:
$smarty->displayDoc('mytemplate.tpl', $language.'|'.$userstatus);If you would like to display documents without making any $smarty->assign() calls, such as if you wished to inject X/HT/ML from the PHP side into a blank template (e.g., for testing purposes) or if, on the converse, you just wished to use templates written in X/HT/ML (without using any $smarty->assign's) while taking advantage of the doc_raw features of SmartyDocB, see the sections below on "Working solely with templates (XML/HTML)" or "Working solely with PHP injection of content".You are now ready to use the program.DependenciesTo use XSL server-side transforms, one must have installed the XSL extension (the update of the "XSLT" extension from PHP4).To use Tidy, one must have the Tidy extension installed (for PHP5).To use Browscap, one must have it installed and follow its licensing--use of the browscap.ini database is under Creative Commons Attribution-Non-Commercial (or get its author's permission) whereas the PHP class for Browscap is under the Creative Commons Attribution-Share Alike 2.5 License).The script checks to see if you have the zlib extension loaded in order to avoid using PHP's own gzip. This extension is not in any way required.Working solely with templates (XML/HTML)--no PHP injection of content or Smarty assignsIf 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 off 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 (though you should look into the relevant security concerns, as I'm sure there are by allowing data in like this unfiltered):
<?php
// $smarty->xml_plain = true; // Uncomment if you want to work with XML
// $smarty->add_openclose = false; // Uncomment if you want to work with (non-XHTML) 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)Working solely with PHP injection of content--no templates or Smarty assignsIf 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:
<?php
$avar = "Some";
$postcontent = <<<HERE
<!-- Content on each page but not on any template -->
<!-- some comments or tags could go here -->
HERE;
$smarty->addRawContent($precontent, '', 'head_post');
$smarty->displayDoc('blank.tpl');
?>
Avoiding potential pitfallsIf you do not assign different values to these member variables, the default "<<" and ">>" are used for tag and tagc functions. I did not bother to add yet another regular expression to escape these even within the {literal} tag, so you will have to use < and > to do so. The prefilter for the class also does some escaping that could potentially interfere with certain sequences of characters (although it is not likely).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!Differences with the original SmartyDocSmartyDocB was naturally heavily inspired by SmartyDoc. However, due to some changes I wanted to make for naming consistency, I have not made SmartyDocB to be wholly compatible with the original SmartyDoc (at least for a number of the items such as DTD's).At this stage, you will need to consult their respective source code to find the exact differences or consult the relevant part of this manual to see how a given feature is now used.However, the following paragraphs describe some of the key differences.The purpose of this fork was originally to improve XHTML support and allow unescaped CSS (expanding on doc_raw) until such time as Boots was able to update his version (SmartyDoc) and reconcile any parts of the fork that he wished to incorporate. However, the file has since expanded considerably to include:strong support for XML (including XHTML)the ability to shuffle off styles, scripts, XSL's, DTD's, XML Schema, parsed/unparsed entities, and personal notes, not only into the head of the document (where appropriate and specified), but also into either one coordinated site-wide external file or into specified files (the idea for the latter, I should mention, was already envisaged by boots).auto-generation of comments denoting which blocks were created by SmartyDocB and from what templates the code within originated.features for facilitating use of XML (e.g., CDATA, XInclude, robots/processing instructions, targetting pre- or post-root, byte-order-marks, etc.)ability to add attributes to doc_raws (where appropriate--e.g., when shuffling off content to a style tagleveraging of a number of PHP extensions or external code (e.g., Tidy, XSL, zlib, Browscap (for detecting mobile phones to serve them XHTML Basic))some new functions/modifiers that can also be used independently: various PHP5-compatible XSL conversions that mimic and expand upon the function of some user-submitted XSL plugins for PHP4 (Richard Bateman's SomeXSLTPlugins and Serge Stepanov's XSLT block function).functions which in combination with the prefilter allow one to make individual tags which will be printed out where they were called (unlike doc_info and doc_raw), but which will intelligently shuffle off style information into external files or the head (Tag and tagc functions).
some developer-related changes: the bulk of doc_raw processing has been moved to its own 2 functions to facilitate code maintenance.The new version of this fork has regrettably also made some backwards-compatibility-breaking changes. For example, 'DOCTYPE' was changed to 'dtd' for definitions referencing an external file, while it is now 'doctype' that creates internal doctype additions (following the convention I've started to have the tag-name (e.g., doctype, style, script) represent internal additions, with a pseudonym (e.g., dtd, css, code) representing externally-targeted items). There are certainly other backwards-compatibility-breaking changes for which one should consult the documentation.There are also a few features (such as boots' modules and a number of the public API functions that I do not document here) which I have not tested on the code and may well break if used in the new version without modifications.Doc_info and moveto/doc_raw typesNote: "moveto" is the new name for "doc_raw" (explained below), but for historical reasons, much of the API still uses "doc_raw". You should use "moveto" within the templates (though for backwards compatibility one can add an argument to the constructor at present to use "doc_raw" instead). This documentation will use the term "doc_raw", however.Doc_raws and doc_infos allow one to place certain blocks of content (or references to content) and shuffle them off into other areas including external files. Doc_raw is a Smarty block function (i.e., encapsulates text), whereas doc_info is a plain Smarty function (i.e., no encapsulated text besides any content contained within its attributes).Doc_raws, when not being targeted to the head or other place within the document, can have their content shuffled off into:Any number of separate external files (as indicated by the "file" attribute for the doc_raw)One site-wide external file (specifiable via the API) into which all styles, scripts, etc. for the site are to be collected (as indicated by the absence of any "file" attribute).Targeting the doc_raw blocks into the latter type (one site-wide external file each for scripts, styles, etc.) has numerous benefits including:One is forced to coordinate all of one's styles (or scripts, etc.) and avoid duplicating items that must be maintained separately.One is forced to provide site-wide styles that are consistent and follow the same naming pattern.One's pages can take advantage of browser caching of stylesheets, as visitors' browsers will not reload the same external file (e.g., a stylesheet) if the file were already loaded (e.g., after visiting the main page).A key can be assigned to doc_raws to force them to follow a prescribed order (or to override an existing doc_raw elsewhere in the template). For example, {doc_raw target="script" key=2}alert('a');{/doc_raw}
{doc_raw target="script" key=1}alert('b');{/doc_raw}
will create two alerts--with 'b' coming before 'a'. One can also overwrite a previous doc_raw of a given type (and file if present) by using the same key for the subsequent (overriding) item.The various subsections here describe in detail how to use a given doc_info/doc_raw feature. In many cases, if a name exists for doc_info, it will exist for doc_raw and vice versa.All features are available when writing XHTML, and as appropriate if writing plain HTML. For plain or "pure" (non-XHTML) XML, one can of course also use the features to create an XML declaration, XSL stylesheets, and XML Schemas, doctypes and dtd (internal or external references), CSS (will be external only and as a xml-stylesheet processing instruction) and 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) but they will not have the head/body tags printed (it will simply target the encapsulated block of XML toward the top, top-middle, bottom-middle, or bottom of the document). However, if the type is specified (via the API or a relevant doc_info) in some way as XHTML, it will try to print the tags and any attributes specified (in the case of "head" and "body").Please note the following important points:Doc_info's will be necessary to indicate such things as DTD, html/root, head, body, etc. elements, if you want the doc_raw or $add_openclose automated addition of tags to mix well with these elements. Otherwise, if you have a doc_raw targeted for the head, for example, and then manually add a <head> tag, the doc_raw content is going to be placed before the head tag, since the script doesn't know to find and move your manually added tags into the right place--i.e., manually-added tags (besides doc_raw and doc_info) will go into a section of the document earmarked for the body.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 for the doc_infos) must be the first attribute.While comments can be turned off via the API for printing within a document, comments (C-style or XML-style depending) are also used automatically to allow the script to identify sections within the external document that it should recreate when $rewrite_docraw_on is true (and it will leave the rest of the page alone, so that you can manually edit the site-wide file without it being erased later). So if you edit the site-wide file, don't tamper with those comments or the content between the beginning and ending of them! (Also be sure to back-up any manual additions you make just in case the automatic rewriting process goes awry for some reason and overwrites your manual additions).
Note that some attributes must be escaped in order to work with Smarty: to create a colon, two underscores must be used (e.g., "xml__lang" for "xml:lang") or one underscore for a hyphen (e.g,. "http_accept" for "http-accept")Except for "pi" and "root", one cannot add arbitrary attributes to doc_raw or doc_info--at best they will be ignored. Each doc_info/doc_raw performs a simple kind of validation to check that only those attributes contained within the relevant section of the $doc_info_types array are produced.As a mnemonic device, all of the doc_raws with content targeted internally (for the head) will generally have the same name as the name of the element or pseudo-element after which they are named (e.g., 'doctype', 'script', 'style', 'comments') whereas those targeted externally will be named with a pseudonym (e.g., 'dtd', 'code', 'css', 'notes'). Some types, such as XSD may not, by their nature, have content targeted interally (e.g., 'xsd').Since SmartyDocB needs to escape curly brackets in order to allow curly brackets to be added unescaped within doc_raw script and style blocks, Smarty variables, Smarty config variables, and Smarty functions (which also use curly brackets), must be escaped with [-...-], [#...#], or [=...=], respectively, if placed within a doc_raw block. Thus,
{assign var=myvar value="alert('You!');"}
{doc_raw target="code" file="javascript.js" charset="UTF-8" defer="defer"}
[-myvar-]
alert('Howdy!');
{/doc_raw}
will produce the following in the code:
/* Begin doc_raw documentation.tpl */
alert('You!')
alert('Howdy!');
/* documentation.tpl end doc_raw */"bom" (byte-order mark)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=""} As with items targeted before the root, to the head, etc., 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, doc_raw, or inserted via the API or automatically).
"xml"{doc_info xml="1.0" encoding="UTF-8" standalone="yes"} produces the following at the top of the document (the value of "xml" turning into a version attribute-value pair):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>"robots"{doc_info robots="yes" follow="no" archive="yes"} produces the following at the top of the document:
<?robots index="yes" follow="no" archive="yes"?>. See the official specification for more.
"pi" (processing instruction)Processing instructions can be added to the top of an XML document. One can use a doc_info with "pi" being set to the prefix, and "_content" defining the raw instruction going within the processing instruction.{doc_info pi="php" _content="print 'ok';"} which produces the following at the top of the document:
<?php print 'ok';?>A doc_raw can also be used to inject even more content:{doc_raw target=pi prefix="php"}
print 3;
exit;
{/doc_raw}which produces:
<?php print 3;
exit;
?>(Note that the above are not regular PHP commands (though they could be designed to be used as such), but rather will show up in the XML document and will be ignored unless the script operates on it.)One can also add an indefinite number of pseudo-attributes which will be added as such (looking like real attributes, but not considered as such by the XML parser).{doc_info pi="execute-this" attr="val"}which produces:<?execute-this attr="val"?>"xsl"One can shuffle off parts of a stylesheet (or a whole stylesheet) into external file(s) via an XSL doc_raw. Doc_info can be used to attach an existing stylesheet to the document. By using the pseudo-attribute, "xform", one can also opt to perform a server-side transform for the given stylesheet before sending it out to the user (one must have the PHP5 XSL extension installed).Note that I have set the default of XSL types to "text/xsl" for the sake of keeping Explorer happy. However, the standard is supposed to be "application/xml".Please note that in using the doc_raw function, a basic prolog and root element is added. If you want to change this (e.g., to add prefixes), you have to manually make the change to $xsl_prefixed (i.e., via the API).
Test:
{/doc_raw}
]]>
will produce:<?xml-stylesheet href="/myfile.xsl" type="text/xsl" title="stylesheet1" media="screen" charset="UTF-8" alternate="no"?>
and a valid XSL file "/myfile.xsl" which includes the contents within this doc_raw.Please note that if you try to use a relative URL you may have problems, unless the page calling the XSL file is also at the directory specified by $site_root_publicAs with other doc_raw's, you can inject additional code into an existing stylesheet by referring to the same file again. For example, we could, in addition to the above doc_raw, add the following:
{/doc_raw}
]]>
If both of the above doc_raws are placed anywhere in the document (assuming they are in the sequential order, or have keys that place them in sequential order), the following will be produced in the external document:<?xml version="1.0"?>
Test:
]]>
We don't need to readd any other attributes since they were already defined by the former doc_raw."root_pre" (prologue) / "head_post" / "body_post" / "root_post"This category of doc_raws allows one to inject generic content into various predefined parts of a document (with the doc_raw being placed anywhere within your template(s)). While the terms such as 'head' and 'body' relate to HTML/XHTML, since no tag or attributes are being created here--only raw content being moved into a specific area--they can also be used within generic XML documents as well. So, in a generic XML document, "head_post" would allow one to shuffle off XML content into what some call the "epilogue": an area after the root, but before other content.Any content allowable in that region can be included within the doc_raw:{doc_raw target=root_pre}
<!-- root pre comments -->
<?my-proc-inst myattr="myval"?>
{/doc_raw}The above will simply move the enclosed contents as is into a section following any doc_raw/doc_info-added XSL stylesheet processing instructions or comments."head_post" gets targeted at the end of the X/HTML head element (if one is being added automatically by $add_openclose or by a doc_info or doc_raw), "body_post" to the end of an X/HTML body element, while root_post actually posts content entirely after the root element's closing tag (e.g., comments can be legally placed here). One can use "head" or "body" to inject content toward the beginning of these sections (or "root" to target toward after the root for non-XHTML XML documents). One can also optionally create attributes for the latter types--see the relevant section for details."notes" / "comments"These doc_raws/doc_infos let you have comments added. "Notes" will save the comments to an external file and then optionally reference the file in an X/HT/ML comment added before the doctype (known as being a part of the prolog in XML), whereas "comments" simply places the comments themselves within the document (also before the doctype/in the prolog area).{doc_raw file="notes.txt" target=notes comment_style="c"}
comment_style c in an external file{/doc_raw}
will add the following to 'notes.txt':
/* Begin doc_raw documentation.tpl */
comment_style c in an external file
/* documentation.tpl end doc_raw */
while:
{doc_raw target=comments}
Comments targeted for the prolog{/doc_raw}
will add the following to a comment preceding any DOCTYPE declaration:
<!-- Comments targeted for the prolog
-->'comment_style' can currently be set to 'c' (for C-style comments: /*...*/), 'xml' (for XML-style comments: <!---->), or 'none' (though the latter will still print text such as 'Begin doc_raw documentation.tpl' and 'documentation.tpl end doc_raw', albeit without comments).'notes' and 'comments' both accept a 'hide' attribute. For 'notes', if you add the attribute, this will cause the referencing comment to be hidden, even if $visible_notes is TRUE. You can also hide all of your note references by setting $visible_notes to FALSE. By hiding the notes through either method, this does not delete or otherwise obscure the file itself--only the reference to it within your X/HT/ML source code. If you absolutely don't want people to have the ability to see your notes, set $notes_in_hiddendir to TRUE (and be sure that $site_root_hidden is set to a directory which is not publicly accessible--e.g., in Unix systems, higher in the hierarchy that htdocs or public_html). In such a case, your file will be saved on your file system, off of the web. (While we think it should work fine as intended, we are not responsible for any damages that may occur to you if the script does not work properly at concealing your notes files though, so please use discretion.)(For 'comments', adding the 'hide' attribute means you will only be able to see these comments within the template so you'd probably be better off using Smarty's comment features unless you want the ability to quickly toggle the visibility of the given comments.)Note that 'comments' (and 'notes') will appear in the document even if $comments and $comments_get are set to false."xsd" (XML Schema)"xsd" doc_raw will shuffle away the contents of an XSD file into an external file (named within the 'file' attribute) and then reference that file as part of the xsi:schemaLocation attribute within the root element of the document ('html' if the document is X/HTML). Additional schemaLocation's can be added via the xsi__schemaLocation attribute. For this to work in plain non-XHTML XML, the 'root' doc_info must be used to set the root element into which the XML Schema referencing information can go.
{/doc_raw}
]]>
will produce:
]]>
Doc_info can create a reference to XSD's (though the 'file' attribute is not used in the doc_info since no file is being created):
gives the following (when used with XHTML--the root element name will of cuorse be different for other languages depending on the document type):
]]>
Note that 'xmlns__xsi' does not really need to be added to either the doc_info or doc_raw since it is added by default."dtd" / "doctype"A 'dtd' or 'doctype' doc_raw will add raw document type definition data into an external file or into the internal 'DOCTYPE' within the document, respectively.To use a doc_raw DTD or doctype in plain (non-XHTML) XML, you must set the rootnode of the document (through the root attribute here, through having set a 'root' doc_info', or through setting $rootnode to something other than 'html')--the script doesn't auto-detect a manually added root-node.
{/doc_raw}
]]>
will produce:
]]>
and, in the mydtd.dtd document will be:
]]>
To use an internal doctype doc_raw, the following
{/doc_raw}
]]>
will create:
]>
]]>
XHTML 1.1 is assumed if no root has been set.Setting the root on a doctype or dtd doc_raw does not create the root element itself. To create one, use a 'root' doc_info.To add a SYSTEM or PUBLIC identifier, add it under the attribute "type" (e.g., type=public) and its file(s) under "subtype" (e.g., subtype='publicid" "localdtd.dtd'--notice how the subtype can allow two quoted files if both are surrounded by apostrophes instead of quotation marks).Note that entities added through these doc_raws can be transformed server-side into their appropriate values if $entity_replaces is set to TRUE."entity"Entities are probably the most complicated feature of SmartyDocB but could be helpful for those wishing to have their site easily translated into other languages.Due to poor browser support, however, and due to the fact that many of the features this function offers can be easily replaced by Smarty functions such as 'include' or 'capture', this function might only really be useful at the present time when the translation features are used and server-side conversion features are turned on--or for those writing XML for off of the web. Still, the fact that the files are saved externally and based on a standard (XML) does offer the opportunity for better reusability in other systems (as well as transparent sharing of your site's data to your users).Entities are used by XML (including XHTML) to allow a user to define their own symbols (within an internal doctype or external DTD file) which, when referenced within the document, will have their text automatically substituted with the designated replacement text. They are defined like this:
]]>
One can then refer to the symbol by adding an ampersand in front of it and a semicolon after it (e.g., ). This will insert the phrase "replacement text" wherever this symbol is thus placed (though entities cannot be placed inside of tags, except within attribute values).
If you use the symbols in place of each piece of translatable text in your document and place these symbols and their translated values in separate files--with each file having the symbols translated differently according to the language being employed, you can then have the script optionally attach the appropriate DTD so that the page will be translated into the desired language. The conversion will usually be done by the visitor's browser, but for those users whose browsers can't support entities (support for entities in external files is especially poor now--even Firefox doesn't support them), SmartyDocB can perform the conversions (as well as the selective attachment of DTD's) server-side.While you could just add the entities via the 'doctype' or 'dtd' doc_raw functions, the 'entity' doc_raw offers special features not possible with these functions. The 'entity' doc_raw can also be used to create external entity files and add content to them.External parameter entities/External DTD subsets can also be created with this doc_raw, though due to a lack of support of external entities in many browsers, this function may have little use now for web use of SmartyDocB. In addition, bug https://bugzilla.mozilla.org/show_bug.cgi?id=267350 of Firefox, instantiating this will not only not work in Firefox, but cause subsequent references, etc. in the internal doctype to be ignored; for Firefox as of now (1/29/2007).The following will create the contents of the following doc_raw as an external parameter entity file (i.e., allow inclusion of reusable DTD data (that will become a subset of the current DTD) from an external file):
{/doc_raw}
]]>
will create the doc_raw's contents in the file subset.dtd:
]]>
and add a reference to the created (or edited) file inside of the internal doctype:
%insertme;
]]>
The following will create the contents of the following doc_raw as an external general entity file (i.e., allow inclusion of its contents in the document via a symbol) from an external file):
hey guys
{/doc_raw}
]]>
will create the following within extgenent.xml:
hey guys
]]>
and add this reference to that file within the internal DOCTYPE:
]]>
Thus, the document will now include hey guys
]]>
wherever the symbol
is used.If no file is specified (but a name and type are present), the content will be added to the main site's entity file. If the document root is 'html', $dr_entity_file_src will be set by default to "/html.xml" (i.e., the root element's name plus '.xml' located at the root directory.Unlike in XInclude, external parsed general entity references must themselves resolve into well-formed XML when included within the document without depending on other entities to do things such as close tags started within the entity (also, unlike in XInclude, there is no means of including portions of a document or including documents which themselves contain a DOCTYPE, etc.). Also, unlike internal entities, they cannot be used inside of attribute values.An external unparsed entity can also be created (along with a NOTATION declaration)--i.e., to include non-XML data, though again browser support may be quite lacking:
will create the following within the internal doctype:
]]>
Besides not working in browsers, there is also no standard defined for the notation identifiers and their contents. However, if there is a PUBLIC type, one can use the subtype attribute to define the locations of the definitions.If no file and no name attributes are present, the 'entity' doc_raw will simply be treated as a 'doctype' doc_raw (i.e., its contents such as raw entity declarations will be sent to the internal doctype).As far as localization, the 'entity' doc_raw also allows items to be added in a tab-delimited fashion so that multiple translations can be added for a page in one place. The first item in a row will become the name of the entity while each subsequent column's data will represent the entity value (i.e., a translation). If no file attribute is set, then the entity declarations will be added to the internal doctype--only for the column called by a GET request, or the second column if there are only two columns.If a file attribute is set (with a pipe-delimited list of files in the same order as the data columns), each column's data will be saved into its own file (e.g., for reuse) but only one file will be referenced, according to a GET request (again, if there is more than one column--otherwise the second column will automatically be chosen).
{doc_raw target=entity file=en.ent|zh.ent|fr.ent}
hello hi ni hao salut;
goodbye bye zai jian au revoir
{/doc_raw}
]]>
If English is chosen (see below how this is done), the value will be referenced as follows:
%ents;
]]>
An alternative is to set the file attribute to 'defaults' and then the files chosen will be those set in the pipe-delimited (i.e., delimited by the "|" character) $entity_files:
{doc_raw target=entity file=defaults}
hello hi ni hao salut;
goodbye bye zai jian au revoir
{/doc_raw}As shown above, the external file that is chosen will be referenced via an external parameter entity (with the default name of this parameter entity specified by $parsed_ent_name). Since there is poor browser support for external entities, one may instead wish to avoid the use of a file attribute entirely (unless server-side replacement of entities is performed--see below), except to have the entity files saved (e.g,. for sharing, reusing).$noextparams can be set to true (the default) in order to avoid external parameter entities from printing at all. This could be set to false if more browsers start supporting external (parameter) entity references (currently Firefox has a bug even printing one let alone using it) or if one simply wanted to generate the XML for non-web purposes; server-side replacement can still take place if this is set to true (see below).However, the use of external files (targeted to the same localization files across your templates) is potentially quite helpful as it allows one's localization data to be saved all together for one site but with the localization data being placeable in various templates (e.g., in the context in which they will first or most prominently appear). When server-side replacement of entities takes place (see below), the entity file that is currently being used will be read in its entirety, so any manually-added changes to that language's entity file will be available to the current document.The GET request has the same name as the first item in a space-delimited list defined by $getentparams. Subsequent items in the list will represent the GET value that will trigger that numbered column's localization data. The given localization files (which can be localization targets of other templates too) to which the data should be saved should be in the same pipe-delimited (i.e., delimited by the "|" character) sequence in $entity_files.For example, given this doc_raw:
{doc_raw target=entity file=en.ent|zh.ent|fr.ent}
hello hi ni hao salut;
goodbye bye zai jian au revoir
{/doc_raw}
if $getentparams is "langu en zh fr" then if the GET request is "?langu=zh", the 3rd column of tab-delimited data will be the value of each entity.Thus, the entities in use with this GET request would be:
]]>
and they would be saved to the 2nd column of the file data (since there is no need for the first item in the files list to represent the GET request name nor to represent the entity symbol name): i.e., here, to 'zh.ent'. And, the entity file would thus be referenced by:
%ents;
]]>
Again, if there are no GET requests sent or set, the 2nd column of data will be used.Server-side replacement of these entities (as well as those added via a 'doctype' or 'dtd' doc_raw, via a non-tab-delimited 'entity' doc_raw, or also by any entities which were manually-added) can be performed for the sake of browsers that do not support entities (especially ones in external files) by setting $entity_replace to TRUE. Even if $noextparams is set to TRUE, parameter entity references won't be printed out at all, though server-side transformations can still take place.
"root"Note that if using a root doc_info, it can have any attributes, though 'xsi__schemaLocation' and 'xsi__noNamespaceSchemaLocation', if used, will be allocated in such a way as to meld with any doc_info or doc_raw 'xsd's (and will auto-create xmlns:xsi if not specified). Other common attributes for generic root tags might include prefixed namespaces, but remember to use "__" instead of ":", however, and also use '_' in place of '-' within your attribute names--this is for the sake of Smarty's function parsing).{doc_info root="purchase-orders" myattr="75" anotheratt="June 2003" xsi__schemaLocation="schema.xsd"
xsi__noNamespaceSchemaLocation="nns.xsd" xmlns="http://example.com/mynamespace"
will produce:
]]>
The value of the root attribute will also change the root reference within a DOCTYPE, if one has been set."script" / "code"Notes: The "script" doc_raw or doc_info will create a script tag in the head of the document. The 'script' attribute (for doc_infos) or 'target' (for doc_raws) should be the first attribute.Note that the script at present allows a global variable $langu to influence the script name. The purpose of this is so that scripts can also be localized (e.g., if you have an alert of text to display tot he user).Required attributes: Script: (doc_raw content or doc_info 'script'); Code: (doc_raw content or doc_info 'code')Optional attributes: type, charset, deferDefault attributes: type="text/javascript"{doc_info script="alert('Hi!');" type="text/javascript" charset="UTF-8" defer="defer"}
will produce
<script type="text/javascript" charset="UTF-8" defer="defer">
<!--//--><![CDATA[//><!--
alert('Hi!');
//--><!]]></script>The following will produce the same results as above:
{doc_raw target="script" type="text/javascript" charset="UTF-8" defer="defer"}
alert('Hi!');
{/doc_raw}'code' (whether as a doc_info or doc_raw) will create a reference to an external javascript file (as opposed to putting the code itself in the head):
{doc_info code="http://example.com/javascript.js" type="text/javascript" charset="UTF-8" defer="defer"}
will produce:
]]>
The doc_raw for 'code' will additionally add the content to the designated file (whether the file designated in the 'file' attribute or, if there is no file attribute, in $this->dr_code_file):
{doc_raw target="code" file="javascript.js" charset="UTF-8" defer="defer"}
alert('Howdy!');
{/doc_raw}
will produce:
]]>
and create the following within javascript.js:
/* Begin doc_raw documentation.tpl */
alert('Howdy!');
/* documentation.tpl end doc_raw */Note that for those new to XHTML-treated-fully-as-XML, when serving files as application/xhtml+xml (attempted if the $xml_plain attribute is true and the file is specified as XHTML) it is recommended to avoid inline scripts/styles."style" / "css"Notes: The "style" doc_raw or doc_info will create a style tag in the head of the document. The 'style' attribute (for doc_infos) or 'target' (for doc_raws) should be the first attribute. The "css" doc_raw or doc_info will create an external stylesheet reference whose implementation will depend on whether the mode is XHTML/XML or not (see below).In style or css doc_raws or in style doc_infos, in order to have escaping of braces (curly brackets) work within, the target attribute (or style attribute for the style doc_info) must be the first attribute.Since SmartyDocB needs to escape curly brackets in order to allow curly brackets to be added unescaped within doc_raw style blocks, Smarty variables, Smarty config variables, and Smarty functions (which also use curly brackets), must be escaped with [-...-], [#...#], or [=...=], respectively, if placed within a doc_raw block. Thus,
{assign var=blue value="color:blue;"}
{doc_raw target="css" file="mycss.css"}
p {[-blue-]}
{/doc_raw}
will produce the following in mycss.css:
/* Begin doc_raw documentation.tpl */
p {color:blue;}
/* documentation.tpl end doc_raw */Required attributes: For doc_info 'style' or 'css', the 'style' or 'css' attribute is required, for doc_raw 'style' or 'css', target must be equal to 'style' or 'css'Optional attributes in HTML:
rel', 'id', 'class', 'dir', 'lang', 'style', 'xml__lang', 'type', 'target', 'rev', 'hreflang', 'media', 'charset', 'title
Optional attributes in XML/XHTML:
type', 'media', 'title', 'lang', 'xml__lang'Note that for those new to XHTML-treated-fully-as-XML, when serving files as application/xhtml+xml (attempted if the $xml_plain attribute is true and the file is specified as XHTML) it is recommended to avoid inline scripts/styles. However, there is a convention to reference the inline style tag via an id attribute:
{doc_raw target=style id="toc"}
div.toc {color:green;}
span.toc {color:orange;}
{/doc_raw}
will produce:
]]>
and
<style type="text/css" id="toc">
<!--/*--><![CDATA[/*><!--*/
div.toc {color:green;}
span.toc {color:orange;}
/*]]>*/--></style>If no 'id' is present on any doc_raw or doc_info-added style tag when in (non-text/html) XML/XHTML mode, one will be auto-created in both the xml-stylesheet instruction and on the style tag (the id having the prefix, 'style_tag_id' followed by an incrementing number). Thus,
{doc_info style="div.toc {color:green;}
span.toc {color:orange;}"}
will produce:
]]>
and
<style type="text/css" id="style_tag_id1">
<!--/*--><![CDATA[/*><!--*/
div.toc {color:green;}
span.toc {color:orange;}
/*]]>*/--></style>The CSS doc_info and doc_raw, when in XML/XHTML mode, will reference an external xml-stylesheet with type 'text/css'. Thus,
{doc_info css="mycss.css"}
will produce the following (including the 'type' and 'media' defaults which can be overridden):
]]>
The CSS doc_raw will also first save its enclosed contents to the file to be referenced. If no file attribute is provided, the site-wide styles file defined by $dr_css_file_src will be used.
{doc_raw target=css}
div.header {font-weight:bold;}
{/doc_raw}
will, in XHTML/XML mode, produce the following in the document:
]]>
and save the following to the main stylesheet:
/* Begin doc_raw documentation.tpl */
div.header {font-weight:bold;}
/* documentation.tpl end doc_raw */
If XHTML/XML mode is not on (i.e., regular HTML mode where $xml_plain is not set) and there is an "external" attribute set to true:
{doc_info css="mycss.css" external=true}
will produce:
]]>
If XHTML/XML mode is not on (i.e., regular HTML mode where $xml_plain is not set) and there is no "external" attribute set to true:
{doc_info css="mycss.css"}
will produce:
<style type="text/css" media="screen">
<!--/*--><![CDATA[/*><!--*/
@import "mycss.css";
/*]]>*/--></style>"html"A doc_info 'html' will insert an HTML tag with any specified attributes.The standard xmlns for XHTML will be added by default for XHTML when $xml_plain is TRUE.The 'v' attribute is not printed, but is rather a shortcut to represent the XHTML version in use. If XHTML is not specified by any other means, this attribute will also be used to flag the document as XHTML (e.g., for setting the content type). It will also let an appropriate XHTML doctype be created if not specified by a dtd doc_info.{doc_info html="ar" xsi__schemaLocation="schemaloc.xsd"
xsi__noNamespaceSchemaLocation="nnsschema.xsd" id="htmlid" dir="rtl" lang="ar"}
will produce
...