DOMImplementation#
DOMImplementation.createDocument()#
Metoda createDocument() tworzy nowy węzeł typu XMLDocument (tzw. historyczny dokument XML) z określoną przestrzenią nazw i nazwą kwalifikowaną dla jego elementu dokumentowego oraz deklaracją typu dokumentu.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_XML = domImplementation.createDocument(namespace, qualifiedName [, doctype = null]);
gdzie poszczególne człony oznaczają:
- new_XML - referencja do nowego historycznego dokumentu XML.
- domImplementation - implementacja DOM będąca obiektem kontekstu.
- namespace - łańcuch znakowy reprezentujący przestrzeń nazw dla elementu dokumentowego w nowym historycznym dokumencie XML lub wartość
null. Pusty łańcuch znakowy ma identyczne działanie jak przekazanie wartościnull. Tylko w dwóch przypadkach można zmienić za jego pomocą domyślny typ zawartości w dokumencie z "application/xml" na:- "
application/xhtml+xml" - jeśli przekazano "http://www.w3.org/1999/xhtml" - "
image/svg+xml" - jeśli przekazano "http://www.w3.org/2000/svg"
- "
- qualifiedName - łańcuch znakowy reprezentujący nazwę kwalifikowaną dla elementu dokumentowego w nowym historycznym dokumencie XML. Wartość
nulljest traktowana jak pusty łańcuch znakowy i oznacza brak elementu dokumentowego. - doctype - referencja do deklaracji typu dokumentu dla nowego historycznego dokumentu XML. Parametr jest opcjonalny z domyślną wartością ustawianą na
null.
Algorytm wywołania metody createDocument(namespace, qualifiedName, doctype) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Niech document będzie nowym węzłem typu
XMLDocument. - Niech element będzie wartością
null. - Jeśli qualifiedName nie jest pustym łańcuchem znakowym, to ustaw element na wynik wywołania metody
createElementNS()na document, z argumentami namespace i qualifiedName. Zrzuć ponownie każdy wyjątek. - Jeśli doctype nie jest wartością
null, to dodaj doctype do document. - Jeśli element nie jest wartością
null, to dodaj element do document. - Pochodzeniem w document jest pochodzenie w dokumencie skojarzonym z obiektem kontekstu.
W zależności od namespace ustaw typ zawartości w document na:
- Dla przestrzeni nazw HTML
- "
application/xhtml+xml" - Dla przestrzeń nazw SVG
- "
image/svg+xml" - Dla każdej innej przestrzeni nazw
- "
application/xml"
- Zwróć document.
Analizując dokładnie wszystkie powiązane z metodą createDocument() algorytmy można zauważyć, że istnieje wiele kombinacji dla argumentów przekazywanych do metody, które najczęściej powodują zrzucenie wyjątku "NamespaceError", co jest konsekwencją niewłaściwego stosowania przestrzeni nazw.
Istotną sprawą jest to, że metoda createDocument() zwraca obiekt typu XMLDocument (wewnętrznie dokument XML) z opcjonalnym elementem dokumentowym oraz deklaracją typu dokumentu, w przeciwieństwie do konstruktora new Document(), który tworzy pusty obiekt typu Document (wewnętrznie też dokument XML), lub metody DOMImplementation.createHTMLDocument(), która tworzy obiekt typu Document (wewnętrznie dokument HTML), ale z cechami i podstawową zawartością właściwą dla dokumentów HTML.
Z praktycznego punktu widzenia sposób utworzenia dokumentu determinuje wiele jego poszczególnych cech, ale zachowanie to jest wyjątkowo niespójne i w głównej mierze zależy od danej przeglądarki internetowej (szczegóły).
Obiekt zwracany przez metodę createDocument() implementuje interfejs XMLDocument, dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia).
Prosty przykład:
<script>
function getInfoDoc(desc, whatDoc){
doc.write(desc + "<br>");
doc.write("Interfejs: " + whatDoc + "<br>");
doc.write("getElementsByTagName('*').length: " + whatDoc.getElementsByTagName('*').length + "<br>");
doc.write("contentType: " + whatDoc.contentType + "<br>");
doc.write("compatMode: " + whatDoc.compatMode + "<br>");
doc.write("doctype: " + whatDoc.doctype + "<br>");
if (whatDoc.doctype){
doc.write("doctype.name: " + whatDoc.doctype.name + "<br>");
doc.write("doctype.publicId: " + whatDoc.doctype.publicId + "<br>");
doc.write("doctype.systemId: " + whatDoc.doctype.systemId + "<br>");
}
doc.write("documentElement: " + whatDoc.documentElement + "<br>");
if (whatDoc.documentElement){
doc.write("documentElement.tagName: " + whatDoc.documentElement.tagName + "<br>");
doc.write("documentElement.namespaceURI: " + whatDoc.documentElement.namespaceURI + "<br>");
doc.write("documentElement.prefix: " + whatDoc.documentElement.prefix + "<br>");
}
doc.write("documentURI: " + whatDoc.documentURI + "<br>");
doc.write("URL: " + whatDoc.URL + "<br>");
doc.write("origin: " + whatDoc.origin + "<br>");
doc.write("characterSet: " + whatDoc.characterSet + "<br>");
doc.write("charset: " + whatDoc.charset + "<br>");
doc.write("inputEncoding: " + whatDoc.inputEncoding + "<br>");
doc.write("Nowy dokument po serializacji: " + "<br>");
var newText = document.createTextNode("");
newText.data = new XMLSerializer().serializeToString(whatDoc);
doc.getElementsByTagName("html")[0].lastChild.appendChild(newText);
doc.write("<br><br>");
}
var doc = document; // domyślny dokument tworzony przez parser HTML
var newDocXML = doc.implementation.createDocument(null, null, null); // nowy dokument XML
getInfoDoc("Parametry dla createDocument(null, null, null):", newDocXML);
newDocXML = doc.implementation.createDocument("", "", null); // nowy dokument XML
getInfoDoc("Parametry dla createDocument('', '', null):", newDocXML);
newDocXML = doc.implementation.createDocument("", "root", null); // nowy dokument XML
getInfoDoc("Parametry dla createDocument('', 'root', null):", newDocXML);
newDocXML = doc.implementation.createDocument("ns", "A:ROOT", null); // nowy dokument XML
getInfoDoc("Parametry dla createDocument('ns', 'A:ROOT', null):", newDocXML);
newDocXML = doc.implementation.createDocument("http://www.w3.org/2000/svg", "svg", null); // nowy dokument XML
getInfoDoc("Parametry dla createDocument('http://www.w3.org/2000/svg', 'svg', null):", newDocXML);
newDocXML = doc.implementation.createDocument("http://www.w3.org/1999/xhtml", "html", null); // nowy dokument XML
getInfoDoc("Parametry dla createDocument('http://www.w3.org/1999/xhtml', 'html', null):", newDocXML);
var dtd = doc.implementation.createDocumentType("HTML", "-//W3C//DTD HTML 4.01//EN", "http://www.w3.org/TR/html4/strict.dtd");
newDocXML = doc.implementation.createDocument("http://www.w3.org/1999/xhtml", "HTML", dtd); // nowy dokument XML
getInfoDoc("Parametry dla createDocument('http://www.w3.org/1999/xhtml', 'HTML', dtd):", newDocXML);
</script>Na chwilę obecną jedynie przeglądarki Firefox i Chrome obsługują (w pewnym stopniu) metodę createDocument() zgodnie z najnowszymi wymaganiami specyfikacji DOM4, gdyż faktycznie zezwalają na pominięcie ostatniego argumentu przy wywołaniu metody. Warto zaznaczyć, że Firefox potrafi zmienić rodzaj tworzonego dokumentu w oparciu o przekazaną deklarację typu dokumentu, co jest prawidłowym zachowaniem względem poprzedniej specyfikacji DOM3, ale w obecnej już nie (Mozilla - Bug 520969).
Składnia Web IDL#
interface DOMImplementation { [NewObject] XMLDocument createDocument(DOMString? namespace, [TreatNullAs=EmptyString] DOMString qualifiedName, optional DocumentType? doctype = null); };