Public Member Functions | Data Fields

ilDOMXML Class Reference

domxml wrapper class This class provides some more complex methods to access a domDocument via DOMXML. More...

Public Member Functions

 ilDOMXML ()
 Constructor init domxml handler You may (a) initiate this class with an existing domDocument OR (b) create a new domDocument depending on the parameters you pass to this constructor:
 _ilDOMXML ()
 initNewDocument ($a_version="", $a_encoding="", $a_charset="")
 init new domDocument private method.
 createRootElement ($a_element)
 wrapper for crating a root element this methods avoids creating multiple elements on root level.
 loadDocument ($a_filename, $a_filepath, $a_validate=false)
 loads a xml-document from file and build a DOM representation in $this->doc.
 trim ($a_node)
 traverse domDocument and removes all useless nodes that are created due to whitespaces in the source file
 trimDocument ($a_node= '')
 wrapper for $this->trim defaults to $this->doc if no node given and returns cleaned dom document
 transform ($node, $left2=-1, $lvl=0)
 traverse the domDocument and build a tree which contains additional information about domDocument's structure: $arr[id] = array( content (str) = node_value (only text nodes have a value) name (str) = tagname or entityname type (int) = element_type_id depth (int) = depth of node in tree parent (int) = id of parent node first (int) = id of first child node prev (int) = id of previous sibling node next (int) = id of next sibling node left (int) = left value (for traversing tree in relational DB) right (int) = right value (for traversing tree in relational DB)) The key is the internal id of the domDocument.
 buildTree ($a_node="")
 wrapper for $this->transform defaults to $this->doc if no node given and returns $this->tree
 dumpDocument ($a_stdout=-1, $a_compress=false, $a_format=false)
 wrapper for dump_mem() and dump_file() converts the entire DOM tree in $this->doc to a string optional: writes the string to a file if path & filename is specified.
 getTextFromElement ($a_element)
 fetch all text parts from an element even when the text is interupted by another element example: <paragraph>This text ispart of the same element.
 isLeafElement ($a_node, $a_elementname, $a_num=0)
 find leaf elements.
 getElementsByTagname ($a_elementname, $a_node="")
 wrapper for get_elements_by_tagname searches domDocument for specified elementname, starting at $a_node.
 appendReferenceNodeForLO ($a_node, $a_lo_id, $a_lm_id, $a_prev_sibling)
 creates an element entry for the removed LearningObject: <LO id=[obj_id of child LO] />
 appendChild ($a_node)
 wrapper for append_child Main purpose of this method is to simplify access of DOM-Functions.
 getRoot ()
 wrapper for document_element Main purpose of this method is to simplify access of DOM-Functions.
 createElement ($a_node)
 wrapper for create_element Main purpose of this method is to simplify access of DOM-Functions.
 addElement ($a_parent, $a_node)
 createText ($a_text)
 wrapper for create_element Main purpose of this method is to simplify access of DOM-Functions.
 createNode ($a_parent, $a_elementname, $a_attr_list=NULL, $a_text=NULL)
 creates a complete node of type element with a text_node within the element and attributes The node is append to domDocument under the given parent_node
 getElementId ($a_node)
 get internal reference id of a domNode
 getElementName ($a_node)
 get node_name
 setEncoding ($a_encode, $a_overwrite=false)
 set encoding of domDocument
 getEncoding ()
 get encoding of domDocument
 setCharset ($a_charset, $a_overwrite=false)
 set charset of domDocument
 getCharset ()
 get charset of domDocument
 getInfo ()
 fetch Title & Description from MetaData-Section of domDocument
 getReferences ()
 get all LO references in Learning Object

Data Fields

 $doc
 $tree
 $error

Detailed Description

domxml wrapper class This class provides some more complex methods to access a domDocument via DOMXML.

For basic tasks when building xml-documents please use the standard functions from the domxml extension of PHP

Author:
Sascha Hofmann <shofmann@databay.de>
Version:
Id:
class.ilDOMXML.php 1301 2003-05-16 13:39:22Z smeyer

Definition at line 35 of file class.ilDOMXML.php.


Member Function Documentation

ilDOMXML::_ilDOMXML (  ) 

Definition at line 93 of file class.ilDOMXML.php.

        {
                if (DEBUG)
                {
            printf("domxml destructor called, class=%s\n", get_class($this)."<br/>");
        }
        }

ilDOMXML::addElement ( a_parent,
a_node 
)

Definition at line 545 of file class.ilDOMXML.php.

        {
                $node = $this->doc->create_element($a_node);
                $node = $a_parent->append_child($node);
                
                return $node;
        }

ilDOMXML::appendChild ( a_node  ) 

wrapper for append_child Main purpose of this method is to simplify access of DOM-Functions.

Parameters:
object domNode
Returns:
object domNode public

Definition at line 515 of file class.ilDOMXML.php.

Referenced by createRootElement().

        {
                return $this->doc->append_child($a_node);
        }

Here is the caller graph for this function:

ilDOMXML::appendReferenceNodeForLO ( a_node,
a_lo_id,
a_lm_id,
a_prev_sibling 
)

creates an element entry for the removed LearningObject: <LO id=[obj_id of child LO] />

Parameters:
object domNode
integer object_id of removed LO public

TODO: Moved this method to class where it fits better (LearningObject? xml2sql?)

Definition at line 490 of file class.ilDOMXML.php.

References createElement().

        {
                $newnode = $this->createElement("LO");
                
                if (empty($a_prev_sibling))
                {
                        $node = $a_node->append_child($newnode);
                }
                else
                {
                        $node = $a_prev_sibling->append_sibling($newnode);
                }

                $node->set_attribute("id",$a_lo_id);
                $node->set_attribute("lm",$a_lm_id);
        }

Here is the call graph for this function:

ilDOMXML::buildTree ( a_node = ""  ) 

wrapper for $this->transform defaults to $this->doc if no node given and returns $this->tree

Parameters:
object domNode
Returns:
array tree structure of domDocument. Returns the array described in $this->transform public

Definition at line 364 of file class.ilDOMXML.php.

References transform().

        {
                if (empty($a_node)) {
                        $a_node = $this->doc;
                }
                
                $this->transform($a_node,1);
                
                return $this->tree;
        }

Here is the call graph for this function:

ilDOMXML::createElement ( a_node  ) 

wrapper for create_element Main purpose of this method is to simplify access of DOM-Functions.

Parameters:
object domNode
Returns:
object domNode public

Definition at line 540 of file class.ilDOMXML.php.

Referenced by appendReferenceNodeForLO(), createNode(), and createRootElement().

        {
                return $this->doc->create_element($a_node);
        }

Here is the caller graph for this function:

ilDOMXML::createNode ( a_parent,
a_elementname,
a_attr_list = NULL,
a_text = NULL 
)

creates a complete node of type element with a text_node within the element and attributes The node is append to domDocument under the given parent_node

Parameters:
object domNode the place where the new created node will be inserted
string name of the element
array list of attributes (optional). syntax: $arr["attr_name"] = attr_value
string if any text is given a text_node will be created (optional).
Returns:
object domNode just created public

Definition at line 578 of file class.ilDOMXML.php.

References createElement().

        {
                // create new element node
                $node = $this->createElement($a_elementname);
                
                // set attributes
                if (is_array($a_attr_list)) {
                        foreach ($a_attr_list as $attr => $value) {
                                $node->set_attribute($attr, $value);
                        }
                }
                
                // create and add a text node to the new element node
                if (is_string($a_text)) {
                        $node_text = $this->doc->create_text_node($a_text);
                        $node_text = $node->append_child($node_text);
                }
                
                // add element node at at the end of the children of the parent
                $node = $a_parent->append_child($node);
                
                return $node;
        }

Here is the call graph for this function:

ilDOMXML::createRootElement ( a_element  ) 

wrapper for crating a root element this methods avoids creating multiple elements on root level.

This is necessary since PHP crashes if you try to create another element on top level of domDocument :-(

Parameters:
string taggname of root element public

Definition at line 151 of file class.ilDOMXML.php.

References appendChild(), createElement(), and getRoot().

        {
                // check if rootNode already exists
                if ($root = $this->getRoot()) {
                        return false;
                }
                
                return $this->appendChild($this->createElement($a_element));
        }

Here is the call graph for this function:

ilDOMXML::createText ( a_text  ) 

wrapper for create_element Main purpose of this method is to simplify access of DOM-Functions.

Parameters:
object domNode
Returns:
object domNode public

Definition at line 561 of file class.ilDOMXML.php.

        {
                return $this->doc->create_text_node($a_text);
        }

ilDOMXML::dumpDocument ( a_stdout = -1,
a_compress = false,
a_format = false 
)

wrapper for dump_mem() and dump_file() converts the entire DOM tree in $this->doc to a string optional: writes the string to a file if path & filename is specified.

Otherwise only the string is returned.

Parameters:
string path/filename
boolean compress XML content
boolean format XML content with whitespaces
Returns:
string XML content in a string public

Definition at line 387 of file class.ilDOMXML.php.

        {
                if ($a_stdout != -1) {
                        $this->doc->dump_file($a_stdout,$a_compress,$a_format);
                }
                
                return $this->doc->dump_mem();
        }

ilDOMXML::getCharset (  ) 

get charset of domDocument

Returns:
string charset public

Definition at line 680 of file class.ilDOMXML.php.

        {
                return $this->doc->charset;
        }

ilDOMXML::getElementId ( a_node  ) 

get internal reference id of a domNode

Parameters:
object domNode
Returns:
integer internal Id of domNode public

Definition at line 609 of file class.ilDOMXML.php.

        {
                $node = (array) $a_node;
                return $node[0];
        }

ilDOMXML::getElementName ( a_node  ) 

get node_name

Parameters:
object domNode
Returns:
string name of domNode public

Definition at line 622 of file class.ilDOMXML.php.

        {
                return $a_node->node_name();
        }

ilDOMXML::getElementsByTagname ( a_elementname,
a_node = "" 
)

wrapper for get_elements_by_tagname searches domDocument for specified elementname, starting at $a_node.

If no node was given searches the entire domDocument in $this->doc returns an array of all nodes found

Parameters:
string tagname of element
object domNode where to start searching (optional)
Returns:
array domNodes (object) which have specified elementname public

Definition at line 467 of file class.ilDOMXML.php.

Referenced by getInfo(), and getReferences().

        {
                if (empty($a_node)) {
                        $a_node = $this->doc;
                }
                
                if (count($node = $a_node->get_elements_by_tagname($a_elementname)) > 0) {
                        return $node;
                }
                
                return false;
        }

Here is the caller graph for this function:

ilDOMXML::getEncoding (  ) 

get encoding of domDocument

Returns:
string encoding charset public

Definition at line 651 of file class.ilDOMXML.php.

        {
                return $this->doc->encoding;
        }

ilDOMXML::getInfo (  ) 

fetch Title & Description from MetaData-Section of domDocument

Returns:
array Titel & Description public

Definition at line 691 of file class.ilDOMXML.php.

References getElementsByTagname().

        {
                $node = $this->getElementsByTagname("MetaData");

                if($node !== false)
                {
                        $childs = $node[0]->child_nodes();

                        foreach ($childs as $child)
                        {
                                        if (($child->node_type() == XML_ELEMENT_NODE) && ($child->tagname == "General"))
                                        {
                                                $childs2 = $child->child_nodes();

                                                foreach ($childs2 as $child2)
                                                {
                                                        if (($child2->node_type() == XML_ELEMENT_NODE) && ($child2->tagname == "Title" || $child2->tagname == "Description"))
                                                        {
                                                                $arr[$child2->tagname] = $child2->get_content();
                                                        }
                                                }

                                                // General-tag was found. Stop foreach-loop
                                                break;
                                        }
                        }
                }

                // for compatibility reasons:
                $arr["title"] = $arr["Title"];
                $arr["desc"] = $arr["Description"];

                return $arr;
        }

Here is the call graph for this function:

ilDOMXML::getReferences (  ) 

get all LO references in Learning Object

Returns:
array object ids of LearningObjects public

Definition at line 732 of file class.ilDOMXML.php.

References getElementsByTagname().

        {
                if ($nodes = $this->getElementsByTagname("LO"))
                {
                        foreach ($nodes as $node)
                        {
                                $attr[] = $node->get_attribute("id");
                        }
                }

                return $attr;
        }

Here is the call graph for this function:

ilDOMXML::getRoot (  ) 

wrapper for document_element Main purpose of this method is to simplify access of DOM-Functions.

Returns:
object domNode public

Definition at line 527 of file class.ilDOMXML.php.

Referenced by createRootElement().

        {
                return $this->doc->document_element();
        }

Here is the caller graph for this function:

ilDOMXML::getTextFromElement ( a_element  ) 

fetch all text parts from an element even when the text is interupted by another element example: <paragraph>This text ispart of the same element.

</paragraph> This method returns: This text is part of the same element.

Parameters:
object dom node of type ELEMENT (id:1)
Returns:
string text of entire element public

Definition at line 408 of file class.ilDOMXML.php.

References trim().

        {
                if ($a_element->node_type() == XML_ELEMENT_NODE) {
                        $value = "";
                
                        foreach ($a_element->child_nodes() as $child) {
                                if ($child->node_type() == XML_TEXT_NODE) {
                                        $value .= $child->content;
                                }
                        }
                
                        return trim($value);
                }
                
                die("<b>".$a_element."</b> is not a valid element node!");
        }

Here is the call graph for this function:

ilDOMXML::ilDOMXML (  ) 

Constructor init domxml handler You may (a) initiate this class with an existing domDocument OR (b) create a new domDocument depending on the parameters you pass to this constructor:

(a) init existing domDocument

Parameters:
object domDocument

(b) init new domDocument

Parameters:
string xml version (optional)
string encoding charset (optional)
string charset (optional) public

Definition at line 78 of file class.ilDOMXML.php.

References initNewDocument().

        {
                $num = func_num_args();
                $args = func_get_args();
                
                if (($num == 1) && is_object($args[0]))
                {
                        $this->doc = $args[0];
                }
                else
                {
                        $this->initNewDocument($args[0],$args[1],$args[2]);
                }
        }

Here is the call graph for this function:

ilDOMXML::initNewDocument ( a_version = "",
a_encoding = "",
a_charset = "" 
)

init new domDocument private method.

Please use constructor to init a new domDocument

Parameters:
string xml version (default: 1.0)
string encoding charset (default: UTF-8)
string charset (default: UTF-8) private

Definition at line 112 of file class.ilDOMXML.php.

References domxml_open_mem(), setCharset(), and setEncoding().

Referenced by ilDOMXML().

        {
                if (!$a_version) {
                        $a_version = "1.0";
                }

                if (!$a_encoding) {
                        $a_encoding = "UTF-8";
                }

                if (!$a_charset) {
                        $a_charset = "UTF-8";
                }

                // create the xml string (workaround for domxml_new_doc) ***
                $xmlHeader = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>". // *** ISO-8859-1
                                         "<root />"; // dummy node
                
                // create a domxml document object
                $this->doc = domxml_open_mem($xmlHeader); // *** Fehlerabfrage

                // delete dummy node 
                $root = $this->doc->document_element();
                $root->unlink_node();
                
                //$this->doc = new_xmldoc($a_version);
                $this->setEncoding($a_encoding);
                $this->setCharset($a_charset);
        }

Here is the call graph for this function:

Here is the caller graph for this function:

ilDOMXML::isLeafElement ( a_node,
a_elementname,
a_num = 0 
)

find leaf elements.

In this context leaf elements are defined as elements that don't contain other elements of the same type!

Parameters:
object domNode of type ELEMENT
string tagname your are looking for
integer auxilliary variable to avoid counting start node itself. must set to 1 for the first function call
Returns:
array domNodes (object) which are leaf elements public

Definition at line 435 of file class.ilDOMXML.php.

        {
                $var = true;
                
                if ($childs = $a_node->child_nodes()) {
                        foreach ($childs as $child) {
                                $var = $this->isLeafElement($child, $a_elementname);

                                if (!$var) {
                                        return false;
                                }
                        }
                }

                if (($a_node->node_type() == XML_ELEMENT_NODE) && ($a_node->tagname == $a_elementname) && ($a_num != 1)) {
                        return false;
                }
                
                return $var;
        }

ilDOMXML::loadDocument ( a_filename,
a_filepath,
a_validate = false 
)

loads a xml-document from file and build a DOM representation in $this->doc.

The xml-document is parsed automatically. You may also validate it against a DTD by setting the 3rd parameter to 'true'

Parameters:
string filename
string filepath
boolean set mode: parsing (false,default) or validating (true) public

Definition at line 172 of file class.ilDOMXML.php.

References $error, domxml_open_file(), exit, setCharset(), and setEncoding().

        {
                if ($a_validate) {
                        $mode = DOMXML_LOAD_VALIDATING;
                } else {
                        $mode = DOMXML_LOAD_PARSING;
                } 

                $this->doc = domxml_open_file($a_filepath . "/" . $a_filename, $mode, $this->error);

                // stop parsing if an error occured
                if ($this->error) {
                        $error_msg = "Error(s) while parsing the document!<br><br>";

                        foreach ($this->error as $error) {
                                $error_msg .= $error["errormessage"]." in line: ".$error["line"]."<br>";
                        }
                        
                        // error handling with ilias object?
                        echo $error_msg;
                        exit();
                }
                
                // set encoding to UTF-8 if empty
                $this->setEncoding("iso-8859-1",true);
                // set charset to UTF-8
                $this->setCharset("iso-8859-1");

                return $this->doc; 
        }

Here is the call graph for this function:

ilDOMXML::setCharset ( a_charset,
a_overwrite = false 
)

set charset of domDocument

Parameters:
string charset
boolean overwrite existing charset (true) or not (false)
Returns:
boolean returns true when charset was sucessfully changed public

Definition at line 664 of file class.ilDOMXML.php.

Referenced by initNewDocument(), and loadDocument().

        {
                if (is_integer($this->doc->charset) or ($a_overwrite)) {
                        $this->doc->charset = $a_charset;
                        return true;
                }
                
                return false;
        }

Here is the caller graph for this function:

ilDOMXML::setEncoding ( a_encode,
a_overwrite = false 
)

set encoding of domDocument

Parameters:
string encoding charset
boolean overwrite existing encoding charset (true) or not (false)
Returns:
boolean returns true when encoding was sucessfully changed public

Definition at line 635 of file class.ilDOMXML.php.

Referenced by initNewDocument(), and loadDocument().

        {
                if (empty($this->doc->encoding) or ($a_overwrite)) {
                        $this->doc->encoding = $a_encode;
                        return true;
                }
                
                return false;
        }

Here is the caller graph for this function:

ilDOMXML::transform ( node,
left2 = -1,
lvl = 0 
)

traverse the domDocument and build a tree which contains additional information about domDocument's structure: $arr[id] = array( content (str) = node_value (only text nodes have a value) name (str) = tagname or entityname type (int) = element_type_id depth (int) = depth of node in tree parent (int) = id of parent node first (int) = id of first child node prev (int) = id of previous sibling node next (int) = id of next sibling node left (int) = left value (for traversing tree in relational DB) right (int) = right value (for traversing tree in relational DB)) The key is the internal id of the domDocument.

Also the ids of other nodes are internal references. The array is written to $this->tree. Use $this->buildTree() to return the variable.

Parameters:
object domNode
integer left value (optional; only needed for recursion))
integer depth of node in tree (optional, default is 0) private

Definition at line 266 of file class.ilDOMXML.php.

References $data, $left, and trim().

Referenced by buildTree().

        { 
                static $left;
                
                // set depth
                $lvl++;

                // start value given from outside?
                if ($left2 > 0) {
                        $left = $left2;
                } 
                // set default value 1 if no value given
                if (!$left) {
                        $left = 1;
                } 

                $node2 = (array)$node;
                
                // init structure data
                // provides additional information about document structure
                // bitwise:
                // 1: has attributes
                // 2: has text element 
                $this->tree[$node2[0]]["struct"] = 0;

                if ($parent = $node->parent_node()) {
                        $parent = (array)$parent;
                } 

                if ($first = $node->first_child())
                {
                        $first = (array)$first;
                } 

                if ($prev = $node->previous_sibling()) {
                        $prev = (array)$prev;
                } 

                if ($next = $node->next_sibling()) {
                        $next = (array)$next;
                } 

                $this->tree[$node2[0]]["content"] = trim($node->node_value());
                $this->tree[$node2[0]]["name"] = $node->node_name();
                $this->tree[$node2[0]]["type"] = $node->type;
                $this->tree[$node2[0]]["depth"] = $lvl;
                $this->tree[$node2[0]]["parent"] = $parent[0];
                $this->tree[$node2[0]]["first"] = $first[0];
                $this->tree[$node2[0]]["prev"] = $prev[0];
                $this->tree[$node2[0]]["next"] = $next[0];
                $this->tree[$node2[0]]["left"] = $left;
                $left++;

                // write attributes to sub-array
                if ($node->has_attributes())
                {
                        $data = "";
                        
                        foreach ($node->attributes() as $attribute)
                        {
                                $data[$attribute->name] = $attribute->value;
                        }

                        $this->tree[$node2[0]]["attr_list"] = $data;
                        $this->tree[$node2[0]]["struct"] += 1;
                }

                // check if one child is a text_node
                foreach ($node->child_nodes() as $child)
                {
                        if ($child->node_type() == XML_TEXT_NODE)
                        {
                                $this->tree[$node2[0]]["struct"] += 2;
                                break;
                        }
                }
                
                // recursive call
                // please don't merge this loop with the one above together! 
                foreach ($node->child_nodes() as $child)
                {
                        $this->transform($child, $left, $lvl);
                }
                
                $this->tree[$node2[0]]["right"] = $left;
                $left++;
        }

Here is the call graph for this function:

Here is the caller graph for this function:

ilDOMXML::trim ( a_node  ) 

traverse domDocument and removes all useless nodes that are created due to whitespaces in the source file

Parameters:
object domNode private

Definition at line 210 of file class.ilDOMXML.php.

Referenced by getTextFromElement(), transform(), and trimDocument().

        {
                if ($a_node->has_child_nodes()) {
                        $childs = $a_node->child_nodes();

                        foreach ($childs as $child) {
                                $content = trim($child->get_content());

                                if (empty($content)) {
                                        $child->unlink_node();
                                } else {
                                        $this->trim($child);
                                } 
                        } 
                } 
        }

Here is the caller graph for this function:

ilDOMXML::trimDocument ( a_node = ''  ) 

wrapper for $this->trim defaults to $this->doc if no node given and returns cleaned dom document

Parameters:
object domNode (optional) public

Definition at line 235 of file class.ilDOMXML.php.

References trim().

        {
                if (empty($a_node))     {
                        $a_node = $this->doc;
                }
        
                $this->trim($a_node);
                return $a_node;
        }

Here is the call graph for this function:


Field Documentation

ilDOMXML::$doc

Definition at line 43 of file class.ilDOMXML.php.

ilDOMXML::$error

Definition at line 60 of file class.ilDOMXML.php.

Referenced by loadDocument().

ilDOMXML::$tree

Definition at line 51 of file class.ilDOMXML.php.


The documentation for this class was generated from the following file: