1=head1 NAME 2 3XML::DOM::Document - An XML document node in XML::DOM 4 5=head1 DESCRIPTION 6 7XML::DOM::Document extends L<XML::DOM::Node>. 8 9It is the main root of the XML document structure as returned by 10XML::DOM::Parser::parse and XML::DOM::Parser::parsefile. 11 12Since elements, text nodes, comments, processing instructions, etc. 13cannot exist outside the context of a Document, the Document interface 14also contains the factory methods needed to create these objects. The 15Node objects created have a getOwnerDocument method which associates 16them with the Document within whose context they were created. 17 18=head2 METHODS 19 20=over 4 21 22=item getDocumentElement 23 24This is a convenience method that allows direct access to 25the child node that is the root Element of the document. 26 27=item getDoctype 28 29The Document Type Declaration (see DocumentType) associated 30with this document. For HTML documents as well as XML 31documents without a document type declaration this returns 32undef. The DOM Level 1 does not support editing the Document 33Type Declaration. 34 35B<Not In DOM Spec>: This implementation allows editing the doctype. 36See I<XML::DOM::ignoreReadOnly> for details. 37 38=item getImplementation 39 40The DOMImplementation object that handles this document. A 41DOM application may use objects from multiple implementations. 42 43=item createElement (tagName) 44 45Creates an element of the type specified. Note that the 46instance returned implements the Element interface, so 47attributes can be specified directly on the returned object. 48 49DOMExceptions: 50 51=over 4 52 53=item * INVALID_CHARACTER_ERR 54 55Raised if the tagName does not conform to the XML spec. 56 57=back 58 59=item createTextNode (data) 60 61Creates a Text node given the specified string. 62 63=item createComment (data) 64 65Creates a Comment node given the specified string. 66 67=item createCDATASection (data) 68 69Creates a CDATASection node given the specified string. 70 71=item createAttribute (name [, value [, specified ]]) 72 73Creates an Attr of the given name. Note that the Attr 74instance can then be set on an Element using the setAttribute method. 75 76B<Not In DOM Spec>: The DOM Spec does not allow passing the value or the 77specified property in this method. In this implementation they are optional. 78 79Parameters: 80 I<value> The attribute's value. See Attr::setValue for details. 81 If the value is not supplied, the specified property is set to 0. 82 I<specified> Whether the attribute value was specified or whether the default 83 value was used. If not supplied, it's assumed to be 1. 84 85DOMExceptions: 86 87=over 4 88 89=item * INVALID_CHARACTER_ERR 90 91Raised if the name does not conform to the XML spec. 92 93=back 94 95=item createProcessingInstruction (target, data) 96 97Creates a ProcessingInstruction node given the specified name and data strings. 98 99Parameters: 100 I<target> The target part of the processing instruction. 101 I<data> The data for the node. 102 103DOMExceptions: 104 105=over 4 106 107=item * INVALID_CHARACTER_ERR 108 109Raised if the target does not conform to the XML spec. 110 111=back 112 113=item createDocumentFragment 114 115Creates an empty DocumentFragment object. 116 117=item createEntityReference (name) 118 119Creates an EntityReference object. 120 121=back 122 123=head2 Additional methods not in the DOM Spec 124 125=over 4 126 127=item getXMLDecl and setXMLDecl (xmlDecl) 128 129Returns the XMLDecl for this Document or undef if none was specified. 130Note that XMLDecl is not part of the list of child nodes. 131 132=item setDoctype (doctype) 133 134Sets or replaces the DocumentType. 135B<NOTE>: Don't use appendChild or insertBefore to set the DocumentType. 136Even though doctype will be part of the list of child nodes, it is handled 137specially. 138 139=item getDefaultAttrValue (elem, attr) 140 141Returns the default attribute value as a string or undef, if none is available. 142 143Parameters: 144 I<elem> The element tagName. 145 I<attr> The attribute name. 146 147=item getEntity (name) 148 149Returns the Entity with the specified name. 150 151=item createXMLDecl (version, encoding, standalone) 152 153Creates an XMLDecl object. All parameters may be undefined. 154 155=item createDocumentType (name, sysId, pubId) 156 157Creates a DocumentType object. SysId and pubId may be undefined. 158 159=item createNotation (name, base, sysId, pubId) 160 161Creates a new Notation object. Consider using 162XML::DOM::DocumentType::addNotation! 163 164=item createEntity (parameter, notationName, value, sysId, pubId, ndata) 165 166Creates an Entity object. Consider using XML::DOM::DocumentType::addEntity! 167 168=item createElementDecl (name, model) 169 170Creates an ElementDecl object. 171 172DOMExceptions: 173 174=over 4 175 176=item * INVALID_CHARACTER_ERR 177 178Raised if the element name (tagName) does not conform to the XML spec. 179 180=back 181 182=item createAttlistDecl (name) 183 184Creates an AttlistDecl object. 185 186DOMExceptions: 187 188=over 4 189 190=item * INVALID_CHARACTER_ERR 191 192Raised if the element name (tagName) does not conform to the XML spec. 193 194=back 195 196=item expandEntity (entity [, parameter]) 197 198Expands the specified entity or parameter entity (if parameter=1) and returns 199its value as a string, or undef if the entity does not exist. 200(The entity name should not contain the '%', '&' or ';' delimiters.) 201 202=item check ( [$checker] ) 203 204Uses the specified L<XML::Checker> to validate the document. 205If no XML::Checker is supplied, a new XML::Checker is created. 206See L<XML::Checker> for details. 207 208=item check_sax ( [$checker] ) 209 210Similar to check() except it uses the SAX interface to XML::Checker instead of 211the expat interface. This method may disappear or replace check() at some time. 212 213=item createChecker () 214 215Creates an XML::Checker based on the document's DTD. 216The $checker can be reused to check any elements within the document. 217Create a new L<XML::Checker> whenever the DOCTYPE section of the document 218is altered! 219 220=back 221