Class: XT
- Package: saf.XML
- Author: John Luxford <lux@simian.ca>
- Copyright: Copyright (C) 2001-2003, Simian Systems Inc.
- License: http://www.sitellite.org/index/license Simian Open Software License
- Version: 2.2, 2003-09-28, $Id: XT.php,v 1.17 2008/03/09 18:46:06 lux Exp $
- Access: public
XT is an XML-based template engine. For reference information,
see the {@link http://www.sitellite.org/index/news-app/section.Templates Templates
category of the Sitellite.org articles}.
Change History
New in 1.2:
- Added support for xmlchar tags as a means of displaying HTML entities that
are not supported by the XML spec, without having to declare an HTML doctype.
For more information see http://xmlchar.sf.net/ and
http://www.w3.org/TR/REC-html40/sgml/entities.html for a list of HTML
entities.
- Added global functions as aliases of the main public methods. These simply
call the methods on a global XT object named $tpl. They are: template_xt(),
template_messy(), template_validate(), and template_wrap().
- Passed the default object to the $intl->get() calls so that {tag}-style
substitutions can be made.
- Added aliases xt:translate and xt:i18n that point to xt:intl.
- Added aliases xt:elsif that points to xt:elseif.
- Fixed a few bugs regarding xt:content and xt:replace attributes, and the
xt:condition, xt:if, xt:elseif, and xt:else tags.
New in 1.4:
- Added an xt:cache tag which allows you to cache pieces of a template for
improved performance.
- Added an ignoreUntilLevel() method which controls the private
$_ignoreUntilLevel property.
- Added the $cacheLocation, $cacheDuration, and $cacheCount properties to
work with the new xt:cache tag.
- Added the $isHtml property to tell the xt:intl tag whether or not to add
an HTML span tag to its output.
New in 1.6:
- Added xt:comment and xt:note tags (xt:note is an alias to xt:comment), so
that comments can be added to templates that will be retained in the
rendered output (since normal xml comments are stripped by the
xml_parse_into_struct() function). For comments that should not be
retained, please use ordinary xml comments.
- Added start, end, and length as attributes of loop iterators.
- Added _header_handler(), makeToc(), and support for automatic generation
of tables of contents for HTML content. Also added the $toc and $buildToc
properties.
New in 1.8:
- Added the ability to call XT tags (attributes too? not sure) using
<xt-tagname /> as well as with the <xt:tagname /> namespace. This feature
helps when you want to render XT tags with CSS, since namespaces in CSS are
not supported by any browser (except Opera 7 apparently) at present.
New in 2.0:
- Added the ability to use inline expressions in any tag attribute, for example:
<a href="${site/prefix}/index/news"><xt:intl>News</xt:intl></a>
This drastically reduces the amount of code needed to implement common
expressions, and really increases the flexibility of the language.
- Fixed a bug where XT string expressions that began with an inline expression
(for example: <h1 xt:content="string: ${site/domain} - welcome">welcome</h1>)
would cause the inline expression to disappear.
- Changes to PHPShorthand have improved the stability of the php expression type,
especially in the area of respecting quoted strings.
New in 2.2:
- Fixed a bug where tags that contained no children and used the xt:condition
attribute would improperly set the $ignoreUntilLevel variable, causing
unpredictable rendering below.
New in 2.4:
- Added a new include type "virtual" which includes a relative URL from the
web site document root, allowing the inclusion of CGI scripts and other
types of dynamic content directly into the template. This would be the
equivalent of the PHP code:
include ('http://www.example.com/cgi-bin/script_name.cgi');
Usage Example
<?php
loader_import ('saf.XML.XT');
$tpl = new XT ('inc/html', XT_DEFAULT_PREFIX);
$tpldata = '';
if ($tpl->validate ($tpldata)) {
echo $tpl->fill (
$tpldata,
array (
'foo' => 'Testing...',
)
);
} else {
echo 'Error: ' $tpl->error . ' on line ' . $tpl->err_line;
}
?>
Return to Top
Properties
$doc
The XMLDoc object that was last parsed.
$error
The error message, if an error occurs.
$client
The XML-RPC client object.
$errno
The error number (faultCode) if an error occurs.
$name
$value
Value of the attribute.
$version
XML version. Default is 1.0
$encoding
The optional encoding type to use when creating the XML parser resource.
$doctype
May contain the entire DOCTYPE declaration tag, including the
< and >.
$root
The root node of the XML document.
$filename
If this object was read in from a file, it may be specified here.
$xquery
If query() has been called, this will contain the XMLDocQuery object.
$content
Content of the node.
$children = array ()
$attributes = array ()
Array of attribute objects.
$comment
The contents of the current comment tag.
$cdata = false
Notes whether the contents of this node should be displayed as
a <![CDATA[ ... ]]> block.
$number = 0
Contains the number of this node within its parent node. Numbers
only increase when more than one child has the same name.
$parent = array ()
A list of references to the next node in the XMLDoc hierarchy.
Destroyed before returning from parse().
$callbackStart = false
The function or method to use as a callback for the start tag
of the current XML node.
$callbackEnd = false
The function or method to use as a callback for the end tag
of the current XML node.
$callbackObject = false
The object that contains the methods listed in $callbackStart
and $callbackEnd (if they are methods and not ordinary custom or built-in
PHP functions).
$propagateCallback = false
Whether or not to propagate callback settings to new child
nodes upon their creation. Defaults to false.
$nodes
$condition
If a condition token is found, this is set to an array containing
the 'operator' and the 'left' node set of the condition.
$rules = array ()
$current
$schema
$tags
$types = array (
'path',
'string',
'php',
)
The types of expressions available in XTE. Currently
these are 'path', 'string', and 'php', where a path is a
filesystem-like reference to objects and their properties and
methods, a string is a literal string (with the ability to
embed sub-expressions within them via a ${sub-expr} syntax),
and php expressions are PHP code with a few modifications
for brevity and for avoiding the > character. These
differences are documented elsewhere in this document.
$parser
The XML parser resource.
$rule = 'required'
$err_line
The error line number, if an error occurs.
$err_code
The error code, if an error occurs.
$err_byte
The error byte number, if an error occurs.
$err_colnum
The error column number, if an error occurs.
$attrs = array ()
$type = false
$ns
$parents
$test
$xslt
This is an XSLT processor resource returned by the
xslt_create () function. Please note: the XSLT processor
is not created until the process method of this class is
called, so as to maintain compatibility with systems that
do not have Sablotron support installed, but are using
EasyText.
$docroot
If an RSS document is being created, this will
contain a reference to the root node.
$channel
If an RSS document is being created, this will
contain a reference to the current channel.
$comment_open = false
$handle
This is the XSLT processor resource returned by the
xslt_create () function.
$register = array (
'nothing' => false,
'default' => false, // not used
'loop' => false,
'repeat' => false, // alias of loop
'attrs' => false, // depends on the node sent to evaluate()
'session' => false,
'user' => false, // alias of session
'cgi' => false,
'request' => false, // alias of cgi
'object' => false,
'here' => false, // alias of object
'result' => false, // from <xt:sql>
'block' => false, // from <xt:block>/<xt:show>
)
This is the internal variable register.
$mode = 'normal'
$out = ''
$action = 'none'
$buffer = array ()
$outputMode = 'path'
$defaultMode = 'path'
$previousMode = 'string'
$path = ''
The path to the template directory.
$output = ''
The output of the current fill() call.
$cache = array ()
A cache for templates read from files, so if they are
called a second or third time XT doesn't have to read them from
the file system again.
$nodeCache = array ()
A cache of the node array of parsed templates. Used to
reduce the number of XML parsers that need to be executed during
a template with loops and complex structures in it.
$sql = array ()
An internal structure built to buffer SQL command blocks
prior to executing them.
$loop = array ()
An internal structure built to buffer loop command blocks
prior to executing them.
$if = array ()
An internal structure built to buffer condition command blocks
prior to executing them.
$block = array ()
An internal structure built to store template blocks
so that they can be reused later in the same or even another
script (via an include call).
$_ignoreUntilLevel = array ()
Tell XT to stop output until the closing of a certain
tag has been found. This is managed via the ignoreUntilLevel()
method.
$openUntilLevel = false
Used by the condition loop and condition blocks to tell
XT to continue buffering the loop or condition body until the
proper closing tag has been found.
$isLoop = false
Used to distinguish between xt:loop and xt:condition
attributes by the $openUntilLevel logic.
$prefix = 'xt:'
The current XML namespace XT is looking for to find
command tags and attributes.
$isHtml = true
Determines whether the template should be treated as
HTML or a different kind of markup. This affects tags such
as xt:intl where an HTML span tag can be added to surround
the string.
$selfClosing = array (
'img',
'br',
'hr',
'meta',
'link',
'area',
)
Contains a list of tags that are self-closing (ie.
they do not contain any data, such as a br tag).
This list is only referenced if $isHtml is true.
$buildToc = false
Determines whether the template should build a
table of contents (TOC) based on HTML header tags found within.
Defaults to false, and must be set to true in order to
generate TOCs.
$toc = array ()
The list of HTML headers found in the document.
$_addToHeader = false
$_bind_list = array ()
$_bind_attrs = array ()
$_bind_parts = array ()
$cacheLocation = 'store:cache/templates/'
Location to store cached contents in. Defaults to
'store:cache/templates/'. Note that the scope will be
appended to the $cacheLocation for each cacheable element.
$cacheDuration = 3600
How long in seconds to store the cached elements
before regenerating them. May be overridden with the duration
attribute of the cache tag. Defaults to 3600 which is one hour.
$cacheCount = 0
Used to generate an auto-incrementing ID value for
cache elements that are missing an "id" attribute (so as
to make the attribute optional).
$file = false
Contains the name of the file currently being processed.
This is set in the getDoc() method, so technically it will set
the current file even when you're just retrieving its contents.
This shouldn't affect its validity for most uses, but when you
want to retrieve the last parsed file, it means you have to do
so prior to calling getDoc() again, either directly or indirectly.
$exp
The XTE object used to evaluate expressions in XT
tags.
$rows = 0
Rows from an xt:sql statement.
$transformations = array ()
Transformations to perform on a variable.
Return to Top
Methods
XT ($path = '', $prefix = XT_DEFAULT_PREFIX)
Constructor method. $prefix is either XT_DEFAULT_PREFIX,
XT_POST_PREFIX, or a custom prefix. The prefix is essentially
the XML namespace XT is to recognize. The use of multiple
namespaces can allow you to partially parse a template, cache
that, then parse the rest which might contain user-specific content
such as personal information. XT_DEFAULT_PREFIX and XT_POST_PREFIX
are constants defined by this package.
getDoc ($data)
- Access: private
- Return: string
Retrieves a template from the appropriate location,
such as the $cache array, $nodeCache array, a file, or if
the string is the template itself, it returns that. Also
handles caching to $cache and $nodeCache of the appropriate
templates.
path ()
- Access: public
- Return: string
Returns either the contents of the $path property,
or the current working directory, which should be used as
the path instead.
ignoreUntilLevel ($level = false)
validate ($data)
- Access: public
- Return: boolean
Validates a template to see if it is a valid XML
document.
fill ($data, $obj = '', $carry = false)
- Access: public
- Return: string
Executes a template. $obj is an optional object you
can pass to the template, which makes its properties immediately
available to the template. $carry is used internally to determine
whether to reset the object register before executing.
bind ($path, $data)
Bind some content to the specified tag.
bindAttr ($path, $attr, $value)
Bind an attribute to the specified tag.
messy ($data, $obj = '', $carry = false)
- Access: public
- Return: string
Uses the saf.HTML.Messy package to implement a "messy"
parser in XT, allowing for invalid markup in templates (ie.
HTML instead of XHTML). Of course since the markup accepted is
invalid, your mileage may vary. This method is discouraged
unless you have a good reason for using it.
box ($name, $parameters = array ())
- Access: public
- Return: string
Executes the specified box using the Sitellite box API,
which is essentially just an include. Note: This is now an alias
for the loader_box() function.
form ($name)
- Access: public
- Return: string
Executes the specified form using the Sitellite form API,
which is essentially just an include of a file that defines a
subclass of saf.MailForm. Note: This is now an alias
for the loader_form() function.
inline ($data)
- Access: private
- Return: string
Evaluates PHP code embedded into a template. Currently
not used, because there's really no reason why embedded PHP
should be needed.
makeMethod ($name, $type, $level)
- Access: private
- Return: string
Determines which callback function to call for the
specified node.
_output ($str)
Determines where to send the output of a tag callback.
wrap ($str)
- Access: public
- Return: string
Wraps $str in xt:tpl tags and returns it.
setVal ($name, $value)
- Access: private
- Return: string
Sets the value of a property of the default object
in the register. Always returns an empty string.
getVal ($val, $node, $type = 'path', $transform = true)
- Access: private
- Return: string
Gets the value of a property in the register.
Returns that value, which may be transformed, if a
transformation has been defined for that property name.
reverseEntities ($data)
- Access: public
- Return: string
Reverses the conversion of HTML entities to XT-compatible ch:entity
tags.
convertEntities ($data)
- Access: public
- Return: string
Converts HTML entities into XT-compatible ch:entity
tags.
_default ($node)
- Access: private
- Return: string
Default open and complete tag handler.
_default_end ($node)
- Access: private
- Return: string
Default close tag handler.
_default_cdata ($node)
- Access: private
- Return: string
Default cdata node handler.
_ch_handler ($node)
- Access: private
- Return: string
Handler for xmlchar tags. See
http://xmlchar.sf.net/ for more information.
_header_handler ($node)
- Access: private
- Return: string
Handler for header tags, if $makeToc is true.
_header_end ($node)
- Access: private
- Return: string
Handler for end header tags, if $makeToc is true.
makeToc ($title = '')
- Access: public
- Return: string
Generates a table of contents as an HTML unordered
list, based on the $toc property. Note: Also requires
$buildToc to be set to true.
_tpl ($node)
- Access: private
- Return: string
Open tpl tag handler.
_tpl_end ($node)
- Access: private
- Return: string
Close tpl tag handler.
_tpl_cdata ($node)
- Access: private
- Return: string
Cdata tpl tag handler.
_doctype ($node)
- Access: private
- Return: string
Creates a doctype declaration from an xt:doctype
tag.
_xmldecl ($node)
- Access: private
- Return: string
Creates an xml declaration tag from an xt:xmldecl
tag.
_xmlstyle ($node)
- Access: private
- Return: string
Creates an xml stylesheet declaration tag from an
xt:xmlstyle tag.
_comment ($node)
- Access: private
- Return: string
Creates an xml comment tag from an xt:comment
tag.
_comment_end ($node)
- Access: private
- Return: string
Creates an xml comment tag from an xt:comment
tag.
_comment_cdata ($node)
- Access: private
- Return: string
Creates an xml comment tag from an xt:comment
tag.
_note ($node)
- Access: private
- Return: string
Creates an xml comment tag from an xt:note
tag.
_note_end ($node)
- Access: private
- Return: string
Creates an xml comment tag from an xt:note
tag.
_note_cdata ($node)
- Access: private
- Return: string
Creates an xml comment tag from an xt:note
tag.
_import ($node)
- Access: private
- Return: string
Import tag handler.
_set_obj ($node)
- Access: private
- Return: string
Set-obj tag handler.
_set ($node)
- Access: private
- Return: string
Set tag handler.
_exec ($node)
- Access: private
- Return: string
Exec tag handler.
_register ($node)
- Access: private
- Return: string
Register tag handler.
_inc ($node)
- Access: private
- Return: string
Open inc tag handler.
_inc_end ($node)
- Access: private
- Return: string
Close inc tag handler.
_box ($node)
- Access: private
- Return: string
Open box tag handler.
_box_end ($node)
- Access: private
- Return: string
Close box tag handler.
_form ($node)
- Access: private
- Return: string
Open form tag handler.
_form_end ($node)
- Access: private
- Return: string
Close form tag handler.
_intl ($node)
- Access: private
- Return: string
Intl tag handler.
_translate ($node)
- Access: private
- Return: string
Alias of _intl tag handler.
_i18n ($node)
- Access: private
- Return: string
Alias of _intl tag handler.
_var ($node)
- Access: private
- Return: string
Var tag handler.
_code ($node)
- Access: private
- Return: string
Code tag handler.
_transform ($node)
- Access: private
- Return: string
Transform tag handler.
_sql ($node)
- Access: private
- Return: string
Open sql tag handler.
_sql_end ($node)
- Access: private
- Return: string
Close sql tag handler.
_bind ($node)
- Access: private
- Return: string
Bind tag handler.
_sub ($node)
- Access: private
- Return: string
Open sub tag handler.
_sub_end ($node)
- Access: private
- Return: string
Close sub tag handler.
_else ($node)
- Access: private
- Return: string
Open else tag handler.
_else_end ($node)
- Access: private
- Return: string
Close else tag handler.
_condition ($node)
- Access: private
- Return: string
Open condition tag handler.
_condition_end ($node)
- Access: private
- Return: string
Close condition tag handler.
_if ($node)
- Access: private
- Return: string
Open if tag handler.
_if_end ($node)
- Access: private
- Return: string
Close if tag handler.
_elseif ($node)
- Access: private
- Return: string
Open elseif tag handler.
_elseif_end ($node)
- Access: private
- Return: string
Close elseif tag handler.
_elsif ($node)
- Access: private
- Return: string
Open elsif tag handler. Alias of _elseif.
_elsif_end ($node)
- Access: private
- Return: string
Close elsif tag handler. Alias of _elseif_end.
_loop ($node)
- Access: private
- Return: string
Open loop tag handler.
_loop_end ($node)
- Access: private
- Return: string
Close loop tag handler.
_block ($node)
- Access: private
- Return: string
Open block tag handler.
_block_end ($node)
- Access: private
- Return: string
Close block tag handler.
_show ($node)
- Access: private
- Return: string
Open show tag handler.
_show_end ($node)
- Access: private
- Return: string
Close show tag handler.
_cache ($node)
- Access: private
- Return: string
Open cache tag handler.
_cache_end ($node)
- Access: private
- Return: string
Close cache tag handler.
Return to Top