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ść
null
jest 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); };