From 2b1af939e43524b36b2d1b71461c994e5e9731f7 Mon Sep 17 00:00:00 2001 From: Mehdi Achour Date: Mon, 20 Dec 2004 15:57:49 +0000 Subject: [PATCH] Used the new documentation format in the documented functions Documented, reviewed and added examples to DOMDocument->__construct(), createEle ment*, load, loadXML, save*. Also documented DOMDocument->xinclude() and found bug #31200 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@175146 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/dom/functions/dom-domattr-isid.xml | 79 ++++++---- .../functions/dom-domdocument-construct.xml | 96 +++++++++--- .../dom-domdocument-createelement.xml | 132 +++++++++++----- .../dom-domdocument-createelementns.xml | 147 +++++++++++++----- .../dom/functions/dom-domdocument-load.xml | 112 +++++++------ .../dom/functions/dom-domdocument-loadxml.xml | 111 ++++++++----- .../dom/functions/dom-domdocument-save.xml | 124 +++++++++------ .../functions/dom-domdocument-saveHTML.xml | 108 +++++++------ .../dom-domdocument-saveHTMLFile.xml | 123 ++++++++++----- .../dom/functions/dom-domdocument-saveXML.xml | 143 +++++++++++------ .../functions/dom-domdocument-validate.xml | 104 +++++++------ .../functions/dom-domdocument-xinclude.xml | 131 +++++++++++++--- .../dom/functions/dom-domxpath-query.xml | 121 ++++++++------ 13 files changed, 1021 insertions(+), 510 deletions(-) diff --git a/reference/dom/functions/dom-domattr-isid.xml b/reference/dom/functions/dom-domattr-isid.xml index 07543efb25..aae592cf88 100644 --- a/reference/dom/functions/dom-domattr-isid.xml +++ b/reference/dom/functions/dom-domattr-isid.xml @@ -1,34 +1,44 @@ - - - - DOMAttr->isId - - Checks if attribute is a defined ID - - - - &reftitle.description; - - DOMAttr - - bool - isId - - - - - This function checks if the attribute is a defined ID. &return.success; - - - According to the DOM standard this requires a DTD which defines the - attribute ID to be of type ID. You need to validate your document with - DOMDocument->validate() - or DOMDocument::validateOnParse before using this function. - - - DOMAttr->isId() Example - + + + + DOMAttr->isId + + Checks if attribute is a defined ID + + + + &reftitle.description; + + DOMAttr + + bool + isId + + + + + This function checks if the attribute is a defined ID. + + + According to the DOM standard this requires a DTD which defines the + attribute ID to be of type ID. You need to validate your document with + DOMDocument->validate() + or DOMDocument::validateOnParse before using this function. + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + + DOMAttr->isId() Example + isId()); // bool(true) ?> ]]> - - - - + + + + + - - - DOMDocument->__construct - - Creates a new DOMDocument object - - - - &reftitle.description; - - DOMDocument - - __construct - stringversion - stringencoding - - - - Creates a new DOMDocument object. - - - + + + + DOMDocument->__construct + + Creates a new DOMDocument object + + + + &reftitle.description; + + DOMDocument + + __construct + stringversion + stringencoding + + + + Creates a new DOMDocument object. + + + + &reftitle.parameters; + + + + version + + + The version number of the document as part of the XML declaration. + + + + + encoding + + + The encoding of the document as part of the XML declaration. + + + + + + + + &reftitle.examples; + + + Creating a new DOMDocument + +saveXML(); /* */ + +?> +]]> + + + + + + &reftitle.seealso; + + + DOMImplementation-createDocument() + + + + - - - DOMDocument->createElement - Create new element node - - - &reftitle.description; - - DOMDocument - - DOMElement - createElement - stringname - stringvalue - - - - This function returns a new instance of class - DOMElement. The tag name of the element is the - value of the name parameter. Optionally, a value for the new element may - also be passed in. &dom.node.inserted; - - - The return value is &false; if an error occurred. - - - See also DOMDocument->createElementNS(), - DOMNode->appendChild(), - DOMDocument->createTextNode(), - DOMDocument->createComment(), - DOMDocument->createAttribute(), - DOMDocument->createProcessingInstruction(). - - - + + + + DOMDocument->createElement + Create new element node + + + &reftitle.description; + + DOMDocument + + DOMElement + createElement + stringname + stringvalue + + + + This function creates a new element node. &dom.node.inserted; + + + + &reftitle.parameters; + + + + name + + + The tag name of the element. + + + + + value + + + The value of the element. By default, an empty element will be created. + You can also set the value later with DOMElement->nodeValue. + + + + + + + + &reftitle.returnvalues; + + Returns a new instance of class DOMElement or &false; + if an error occured. + + + + &reftitle.examples; + + + Creating a new element and inserting it as root + +createElement('test', 'This is the root element!'); + +// We insert the new element as root (child of the document) +$dom->appendChild($element); + +echo $dom->saveXML(); +?> +]]> + + &example.outputs; + + +This is the root element! +]]> + + + + + + &reftitle.seealso; + + + DOMDocument->createElementNS() + DOMNode->appendChild() + DOMDocument->createTextNode() + DOMDocument->createComment() + DOMDocument->createAttribute() + DOMDocument->createProcessingInstruction() + + + + - - - DOMDocument->createElementNS - - Create new element node with an associated namespace - - - - &reftitle.description; - - DOMDocument - - DOMElement - createElementNS - stringnamespaceURI - stringqualifiedName - stringvalue - - - - This function returns a new instance of class - DOMElement. The tag name and prefix of the element - is determined by the value of the passed parameter qualifiedName. - The URI of the namespace is the value of the passed parameter - namespaceURI. &dom.node.inserted; - - - The return value is &false; if an error occurred. - - - See also DOMNode->appendChild(), - DOMDocument->createAttributeNS(), - DOMDocument->createElement(), - DOMDocument->createAttribute() and - DOMDocument->createComment(). - - - + + + + DOMDocument->createElementNS + + Create new element node with an associated namespace + + + + &reftitle.description; + + DOMDocument + + DOMElement + createElementNS + stringnamespaceURI + stringqualifiedName + stringvalue + + + + This function creates a new element node with an associated namespace. + &dom.node.inserted; + + + + &reftitle.parameters; + + + + namespaceURI + + + The URI of the namespace. + + + + + qualifiedName + + + The qualified name of the element, as prefix:tagname + + + + + value + + + The value of the element. By default, an empty element will be created. + You can also set the value later with DOMElement->nodeValue. + + + + + + + + &reftitle.returnvalues; + + Returns a new instance of class DOMElement or &false; + if an error occured. + + + + &reftitle.examples; + + + Creating a new element and inserting it as root + +createElementNS('http://www.example.com/XFoo', 'xfoo:test', 'This is the root element!'); + +// We insert the new element as root (child of the document) +$dom->appendChild($element); + +echo $dom->saveXML(); +?> +]]> + + &example.outputs; + + +This is the root element! +]]> + + + + + + &reftitle.seealso; + + + DOMDocument->createElement() + DOMNode->appendChild() + DOMDocument->createTextNode() + DOMDocument->createComment() + DOMDocument->createAttribute() + DOMDocument->createProcessingInstruction() + + + + - - - DOMDocument->load - - Load XML from a file - - - - &reftitle.description; - - DOMDocument - - mixed - load - stringfilename - - - - The function parses the XML document in the file named - filename. This function may also be called - statically to load and create a DOMDocument object. - The static invocation may be used when no - DOMDocument properties need to be set prior to - loading. - - - - Creating a Document - + + + + DOMDocument->load + + Load XML from a file + + + + &reftitle.description; + + DOMDocument + + mixed + load + stringfilename + + + + Loads an XML document from a file. + + + This method may also be called statically to load and create a + DOMDocument object. The static invocation may be + used when no DOMDocument properties need to be set + prior to loading. + + + + &reftitle.parameters; + + + + filename + + + The path to the XML document. + + + + + + + + &reftitle.examples; + + + Creating a Document + saveXML(); +$doc = DOMDocument::load('book.xml'); +echo $doc->saveXML(); $doc = new DOMDocument(); -$doc->load("filename"); -print $doc->saveXML(); +$doc->load('book.xml'); +echo $doc->saveXML(); ?> ]]> - - - - - See also DOMDocument->loadXML(), - DOMDocument->save() and - DOMDocument->saveXML(). - - - + + + + + + &reftitle.seealso; + + + DOMDocument->loadXML() + DOMDocument->save() + DOMDocument->saveXML() + + + + - - - DOMDocument->loadXML - - Load XML from a string - - - - &reftitle.description; - - DOMDocument - - mixed - loadXML - stringsource - - - - The function parses the XML contained in the string source. - This function may also be called statically to load and create a - DOMDocument object. The static invocation may be - used when no DOMDocument properties need to be - set prior to loading. - - - - Creating a Document - + + + + DOMDocument->loadXML + + Load XML from a string + + + + &reftitle.description; + + DOMDocument + + mixed + loadXML + stringsource + + + + Loads an XML document from a string. + + + This method may also be called statically to load and create a + DOMDocument object. The static invocation may be + used when no DOMDocument properties need to be set + prior to loading. + + + + &reftitle.parameters; + + + + source + + + The string containing the XML. + + + + + + + + &reftitle.examples; + + + Creating a Document + "); -print $doc->saveXML(); +$doc = DOMDocument::loadXML(''); +echo $doc->saveXML(); $doc = new DOMDocument(); -$doc->loadXML(""); -print $doc->saveXML(); +$doc->loadXML(''); +echo $doc->saveXML(); ?> ]]> - - - - - See also DOMDocument->load(), - DOMDocument->save() and - DOMDocument->saveXML(). - - - + + + + + + &reftitle.seealso; + + + DOMDocument->load() + DOMDocument->save() + DOMDocument->saveXML() + + + + - - - DOMDocument->save - - Dumps the internal XML tree back into a file - - - - &reftitle.description; - - DOMDocument - - int - save - stringfilename - - - - Creates an XML document from the dom representation. The number of bytes - written is returned. This function is usually called after building a new dom - document from scratch as in the example below. - - - - Creating a simple HTML document header - + + + + DOMDocument->save + + Dumps the internal XML tree back into a file + + + + &reftitle.description; + + DOMDocument + + mixed + save + stringfilename + + + + Creates an XML document from the DOM representation. This function is usually + called after building a new dom document from scratch as in the example below. + + + + &reftitle.parameters; + + + + filename + + + The path to the saved XML document. + + + + + + + + &reftitle.returnvalues; + + Returns the number of bytes written or &false; if an error occured. + + + + &reftitle.examples; + + + Saving a DOM tree into a file + createElement("HTML"); + +$doc = new DOMDocument('1.0'); +// we want a nice output +$doc->formatOutput = true; + +$root = $doc->createElement('book'); $root = $doc->appendChild($root); -$head = $doc->createElement("HEAD"); -$head = $root->appendChild($head); -$title = $doc->createElement("TITLE"); -$title = $head->appendChild($title); -$text = $doc->createTextNode("This is the title"); + +$title = $doc->createElement('title'); +$title = $root->appendChild($title); + +$text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); -$doc->save("/tmp/test.xml"); + +echo 'Wrote: ' . $doc->save("/tmp/test.xml") . ' bytes'; // Wrote: 72 bytes + ?> ]]> - - - - - See also DOMDocument->load(), - DOMDocument->loadXML() - and DOMDocument->saveXML(). - - - + + + + + + &reftitle.seealso; + + + DOMDocument->saveXML() + DOMDocument->load() + DOMDocument->loadXML() + + + + - - - DOMDocument->saveHTML - - Dumps the internal document into a string using HTML formatting - - - - &reftitle.description; - - DOMDocument - - string - saveHTML - - - - - Creates an HTML document from the dom representation. This function - usually is called after building a new dom document from scratch - as in the example below. - - - - Creating a simple HTML document header - + + + + DOMDocument->saveHTML + + Dumps the internal document into a string using HTML formatting + + + + &reftitle.description; + + DOMDocument + + string + saveHTML + + + + + Creates an HTML document from the DOM representation. This function is usually + called after building a new dom document from scratch as in the example below. + + + + &reftitle.returnvalues; + + Returns the HTML, or &false; if an error occured. + + + + &reftitle.examples; + + + Saving a HTML tree into a string + createElement("HTML"); + +$doc = new DOMDocument('1.0'); +// we want a nice output +$doc->formatOutput = true; + +$root = $doc->createElement('html'); $root = $doc->appendChild($root); -$head = $doc->createElement("HEAD"); + +$head = $doc->createElement('head'); $head = $root->appendChild($head); -$title = $doc->createElement("TITLE"); + +$title = $doc->createElement('title'); $title = $head->appendChild($title); -$text = $doc->createTextNode("This is the title"); + +$text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); -echo "
";
+
 echo $doc->saveHTML();
-echo "
"; + ?> ]]> - - - - - See also DOMDocument->loadHTML(), - DOMDocument->loadHTMLFile() - and DOMDocument->saveHTMLFile(). - - - + + + + + + &reftitle.seealso; + + + DOMDocument->saveHTMLFile() + DOMDocument->loadHTML() + DOMDocument->loadHTMLFile() + + + + - - - DOMDocument->saveHTMLFile - - Dumps the internal document back into a file using HTML formatting - - - - &reftitle.description; - - DOMDocument - - string - saveHTMLFile - stringfilename - - - - Creates an HTML document from the dom representation. This function - usually is called after building a new dom document from scratch - as in the example below. - - - - Creating a simple HTML document header - + + + + DOMDocument->saveHTML + + Dumps the internal document into a file using HTML formatting + + + + &reftitle.description; + + DOMDocument + + int + saveHTMLFile + stringfilename + + + + Creates an HTML document from the DOM representation. This function is usually + called after building a new dom document from scratch as in the example below. + + + + &reftitle.parameters; + + + + filename + + + The path to the saved HTML document. + + + + + + + + &reftitle.returnvalues; + + Returns the number of bytes written or &false; if an error occured. + + + + &reftitle.examples; + + + Saving a HTML tree into a file + createElement("HTML"); + +$doc = new DOMDocument('1.0'); +// we want a nice output +$doc->formatOutput = true; + +$root = $doc->createElement('html'); $root = $doc->appendChild($root); -$head = $doc->createElement("HEAD"); + +$head = $doc->createElement('head'); $head = $root->appendChild($head); -$title = $doc->createElement("TITLE"); + +$title = $doc->createElement('title'); $title = $head->appendChild($title); -$text = $doc->createTextNode("This is the title"); + +$text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); -$doc->saveHTMLFile("/tmp/test.hmtl"); + +echo 'Wrote: ' . $doc->saveHTMLFile("/tmp/test.html") . ' bytes'; // Wrote: 129 bytes + ?> ]]> - - - - - See also DOMDocument->loadHTML(), - DOMDocument->loadHTMLFile() - and DOMDocument->saveHTML(). - - - + + + + + + &reftitle.seealso; + + + DOMDocument->saveHTML() + DOMDocument->loadHTML() + DOMDocument->loadHTMLFile() + + + + - - - DOMDocument->saveXML - Dumps the internal XML tree back into a string - - - &reftitle.description; - - DOMDocument - - string - saveXML - DOMNodenode - - - - Creates an XML document from the dom representation. This function is - usually called after building a new dom document from scratch - as in the example below. The - node is used to output only the node rather than the entire document. - - - - Creating a simple HTML document header - + + + + DOMDocument->saveXML + + Dumps the internal XML tree back into a string + + + + &reftitle.description; + + DOMDocument + + string + saveXML + DOMNodenode + + + + Creates an XML document from the DOM representation. This function is usually + called after building a new dom document from scratch as in the example below. + + + + &reftitle.parameters; + + + + node + + + Use this parameter to output only a specific node without XML declaration + rather than the entire document. + + + + + + + + &reftitle.returnvalues; + + Returns the XML, or &false; if an error occured. + + + + &reftitle.examples; + + + Saving a DOM tree into a file + createElement("HTML"); + +$doc = new DOMDocument('1.0'); +// we want a nice output +$doc->formatOutput = true; + +$root = $doc->createElement('book'); $root = $doc->appendChild($root); -$head = $doc->createElement("HEAD"); -$head = $root->appendChild($head); -$title = $doc->createElement("TITLE"); -$title = $head->appendChild($title); -$text = $doc->createTextNode("This is the title"); + +$title = $doc->createElement('title'); +$title = $root->appendChild($title); + +$text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); -echo "
";
-echo htmlentities($doc->saveXML());
-echo "
"; + +echo "Retrieving all the document:\n"; +echo $doc->saveXML() . "\n"; + +echo "Retrieving only the title part:\n"; +echo $doc->saveXML($title); + ?> ]]> - - - - - See also DOMDocument->load(), - DOMDocument->loadXML() - and DOMDocument->save(). - - - + + &example.outputs; + + + + This is the title + + +Retrieving only the head part: +This is the title +]]> + + + + + + &reftitle.seealso; + + + DOMDocument->save() + DOMDocument->load() + DOMDocument->loadXML() + + + + - - - DOMDocument->validate - - Validates the document based on its DTD - - - - &reftitle.description; - - DOMDocument - - bool - validate - - - - - Validates the document based on its DTD. &return.success; - If the document have no DTD attached, this method will return &false;. - - - You can also use the validateOnParse property of - DOMDocument to make a DTD validation. - - - Example of DTD validation - + + + + DOMDocument->validate + + Validates the document based on its DTD + + + + &reftitle.description; + + DOMDocument + + bool + validate + + + + + Validates the document based on its DTD. + + + You can also use the validateOnParse property of + DOMDocument to make a DTD validation. + + + + &reftitle.returnvalues; + + &return.success; + If the document have no DTD attached, this method will return &false;. + + + + &reftitle.examples; + + + Example of DTD validation + validate()) { } ?> ]]> - - - You can also validate your XML file while loading it: - - + + + You can also validate your XML file while loading it: + + validateOnParse = true; $dom->Load('book.xml'); ?> ]]> - - - - See also DOMDocument->schemaValidate(), - DOMDocument->schemaValidateSource(), - DOMDocument->relaxNGValidate(), - DOMDocument->relaxNGValidateSource(). - - - + + + + + + &reftitle.seealso; + + + DOMDocument->schemaValidate() + DOMDocument->schemaValidateSource() + DOMDocument->relaxNGValidate() + DOMDocument->relaxNGValidateSource() + + + + - - - DOMDocument->xinclude - - Substitutes XIncludes in a DOMDocument Object - - - - &reftitle.description; - - DOMDocument - - int - xinclude - - - - - Substitutes XIncludes in a DOMDocument Object. - - - + + + + DOMDocument->xinclude + + Substitutes XIncludes in a DOMDocument Object + + + + &reftitle.description; + + DOMDocument + + int + xinclude + + + + + This method substitutes XIncludes in a DOMDocument object. + + + + Due to libxml2 automatically resolving entities, this method will produce + unexpected results if the included XML file have an attached DTD. + + + + + &reftitle.returnvalues; + + Returns the number of XIncludes in the document. + + + + &reftitle.examples; + + + DOMDocument->xinclude() example + + + + Books of the other guy.. + + + + xinclude: book.xml not found + + + + +EOD; + +$dom = new DOMDocument; + +// let's have a nice output +$dom->preserveWhiteSpace = false; +$dom->formatOutput = true; + +// load the XML string defined above +$dom->loadXML($xml); + +// substitute xincludes +$dom->xinclude(); + +echo $dom->saveXML(); + +?> +]]> + + &example.outputs.similar; + + + + Books of the other guy.. + + + The Grapes of Wrath + John Steinbeck + en + 0140186409 + + + The Pearl + John Steinbeck + en + 014017737X + + + Samarcande + Amine Maalouf + fr + 2253051209 + + + +]]> + + + + + - - - DOMXPath->query - - Evaluates the given XPath expression - - - - &reftitle.description; - - DOMXPath - - DOMNodeList - query - stringexpression - DOMNodecontextnode - - - - Returns a DOMNodeList containing all nodes matching - the given XPath expression. Any expression which do - not return nodes will return an empty DOMNodeList. - - - - Getting all the english books - + + + + DOMXPath->query + + Evaluates the given XPath expression + + + + &reftitle.description; + + DOMXPath + + DOMNodeList + query + stringexpression + DOMNodecontextnode + + + + Excutes the given XPath expression and returns a + set of nodes as result. + + + + &reftitle.parameters; + + + + expression + + + The XPath expression to execute. + + + + + contextnode + + + The optional contextnode can be specified for + doing relative XPath queries. By default, the queries are relative to + the root element. + + + + + + + + &reftitle.returnvalues; + + Returns a DOMNodeList containing all nodes matching + the given XPath expression. Any expression which do + not return nodes will return an empty DOMNodeList. + + + + &reftitle.examples; + + + Getting all the english books + ]]> - - &example.outputs; - + + &example.outputs; + - - - + - The optional contextnode can be specified for doing - relative XPath queries. By default, the queries are relative to the root - element. Knowing that, we can rewrite our previous example as follow: + We can also use the contextnode parameter to shorten + our expression: - - - Using the context node - + ]]> - - - - - + + + + +