Class: XMLNode
- 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: 3.8, 2003-07-11, $Id: Node.php,v 1.4 2007/10/06 00:06:30 lux Exp $
- Access: public
XMLNode stores all the XML nodes of your document.
New in 1.2:
- New $cdata property so that it knows to wrap the contents properly
in the write () method.
New in 1.4:
- Added method query (), which allows users to traverse a set of nodes more
easily and more legibly by using the most basic subset of XPath. Currently
supports only the most basic syntax (/node1/node2/node3).
New in 1.6:
- Added a space before the slash in self-closing tags, so as to be able to
work with cross-browser-compatible XHTML markup.
New in 1.8:
- Added line breaks and tabs to the write() method, so that XMLDoc produces
legible XML output. Set $level to -1 to signify no auto-indenting.
New in 2.0:
- Added a makeObj() method, which is helpful in passing nodes around like
one would database query results.
New in 2.2:
- Added a makeRefObj() method, which is similar to makeObj(), but takes
references to the document structure instead, so any modifications to the
object returned are actually being made to the XML structure as well.
New in 2.4:
- makeObj() and makeRefObj() now handle multiple child nodes with the same
name by turning them into an array of their $content properties.
New in 2.6:
- Added a new parameter to the query() method that lets you return an array
of references to the resulting nodes instead of copies. This makes it
easier to use the query() method in conjunction with document updates.
New in 3.0:
- Changed query() so that it uses saf.XML.Doc.Query instead of processing
the query itself.
- Added a path() method which returns the unique path (as understood by
saf.XML.Doc.Query) to the current node.
- Added a $parent property, which references the parent node (if not the
root node).
- Added a $number property, which keeps track of the position of this node
within similarly-named children of its parent.
- Added the makeMenu() and _makeMenu() methods, which turn the current node
and its children into a saf.GUI.Menu object, making it easy to display
a document as a hierarchy using templates.
New in 3.2:
- Added 4 new properties, two new methods, and a lot of power!
New properties:
- $callbackStart
- $callbackEnd
- $callbackObject
- $propagateCallback
New methods:
- setCallback()
- propagateCallback()
These new pieces add the ability to easily define custom callback functions
to handle the starting and ending tags of a node, essentially implementing
a form of XML transformations in pure PHP (read: EASY). For an example
of a simple callback usage, check out saf.XML.SLiP.Writer in saf/docs or
DocReader. This example package implements an XML to SLiP conversion.
SLiP is a simplified markup language that can be used to express
hierarchies in the same way that XML can, but is much quicker to read
and write making it ideal for pseudocode applications.
New in 3.4:
- Modified makeObj() so that empty child nodes would be set as properties
with a value of 'true' (boolean). This change was not made to makeRefObj()
however, because it is more proper in that case to refer to the empty
contents of the node, which is often the purpose of the reference to begin
with.
New in 3.6:
- Modified path() to start counting path numbers at 1 instead of 0.
- Added an $xquery property, and modified query() to work with the new
saf.XML.Doc.Query package.
New in 3.8:
- Added named aliases to each child, so that they may be referred to by
name for convenience. For example: $doc->_html->_head->_title->content
or $doc->_html->_body->_h1->content). Note the underscores,
used to prevent naming conflicts. In the case where there are more than
one child of the same name, the _name alias is turned into a numbered
array.
Usage Example
<?php
$foo =& new XMLNode ('foo');
$bar =& $foo->addChild ('bar', 'qwerty');
$foobar =& $foo->addChild ('foobar');
$foobar->setAttribute ('asdf', 'fdsa');
echo $foo->write ();
--- Output:
<foo><bar>qwerty</bar><foobar asdf="fdsa"/></foo>
?>
Return to Top
Properties
$doc
$error
Any internal error message involved in using this class.
$client
The XML-RPC client object.
$errno
The error number (faultCode) if an error occurs.
$name
Name of the node.
$value
Value of the attribute.
$version
XML version. Default is 1.0
$encoding
Encoding of the XML document. Default is 'utf-8'.
Please note: Actual encoding of data is not handled by these
classes.
$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 ()
Array of child node objects.
$attributes = array ()
Array of attribute objects.
$comment
Attach a comment to the node, which will appear as an XML comment
tag above the element.
$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 = false
Contains a reference to the parent of this node, or false if this
is the root node of the document.
$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.
Return to Top
Methods
XMLNode ($name, $content = '', $number, &$parent)
Constructor method. $content is optional.
&addChild ($name, $content = '')
- Access: public
- Return: resource
Creates a child node of the current element.
$content is optional.
setAttribute ($name, $value)
Adds an attribute to the current element.
setCallback ($startFunction, $endFunction = false, &$obj)
- Access: public
- Return: boolean
Sets the callback setting for the current node. $startFunction
and $endFunction are methods of an object, which must be provided
by $obj.
propagateCallback ($startFunction, $endFunction = false, &$obj)
- Access: public
- Return: boolean
Propagates a callback setting to the current node and all of its
child nodes as well. Useful for setting a "default" callback setting
which can then be overridden on a per-node basis, and for adding callbacks
to documents which were recreated from a pre-existing data source.
write ($level = 0)
- Access: public
- Return: string
Returns the XML for the current node, and calls its
children's write method to do the same.
query ($path, $ref = 0)
- Access: public
- Return: array
Returns a set of nodes, making it easier to traverse elements
in a loop, and making the code more legible as well. Accepts a very
elementary and minimal language based on XPath (see saf.XML.Doc.Query for
specifics and examples). Returns an array of references to matching
nodes. Note: The $ref parameter is deprecated and doesn't do anything.
Results are always returned as references.
path ()
- Access: public
- Return: string
Returns the full saf.XML.Doc.Query-compatible path to the
current node.
makeObj ()
- Access: public
- Return: object
Renders a node as an object of type StdClass, which is handy
for passing around the SAF libraries, such as saf.Template. The child
nodes of this node become properties of this new object, and their
values are the $content property of each child node. Attributes of
this node are placed in an associative array property of the new
object called $attrs. If there is more than one child node of the
same name, the corresponding property of the object will be an array
of their $content properties. If a child node is empty (ie.
self-closing), it's value will be a boolean 'true', even in an array.
&makeRefObj ()
- Access: public
- Return: object reference
This method is almost identical to makeObj(), except that
instead of the new object containing all of the values of the node's
children and attributes, makeRefObj() simply makes references to
their values, so when the resulting object is modified, you are
essentially modifying the values inside the XML document structure.
If there is more than one child node of the same name, the
corresponding property of the object will be an array of references
to their $content properties. There is one other difference between
this method and makeObj(), which is that empty nodes are not set as
properties with a 'true' value, but rather as references to the
empty contents. To evaluate whether such a property is set, instead
use the isset() PHP function.
_makeMenu (&$menu, $parent = '')
- Access: private
- Return: object
Turns the current node into a menu item and calls its
children to do the same. Note: This method adds several new
properties to each MenuItem object, which are: $content holds
the $content of this node, $path holds the path() of this node,
$encoded_path holds a urlencode()-ed copy of $path, and each
attribute in $attributes becomes a property of the new MenuItem.
Care must be taken though, or these can potentially overwrite
important existing properties of the MenuItem object, such as
its $id, $title, $parent, $children, or $colours.
makeMenu ()
- Access: public
- Return: object
Creates a new saf.GUI.Menu object and turns this node and its
children into items in that menu. Returns the menu object.
Return to Top