Document#
Document.createProcessingInstruction()#
Metoda createProcessingInstruction() tworzy nowy węzeł typu ProcessingInstruction (pochodna węzłów znakowych) z określonym celem i danymi tekstowymi, którego właścicielem jest dany dokument.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_pi = document.createProcessingInstruction(target, data);gdzie poszczególne człony oznaczają:
- new_pi - referencja do nowej instrukcji przetwarzania.
- document - dokument będący obiektem kontekstu.
- target - łańcuch znakowy reprezentujący cel w nowej instrukcji przetwarzania.
- data - dane tekstowe będące instrukcjami do wykonania dla konkretnego modułu, wskazywanego przez cel w nowej instrukcji przetwarzania.
Algorytm wywołania metody createProcessingInstruction(target, data) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Jeśli target nie pasuje do wzorca
Namez XML, to zrzuć wyjątek"InvalidCharacterError". - Jeśli data zawiera łańcuch znakowy "
?>", to zrzuć wyjątek"InvalidCharacterError". - Zwróć nowy węzeł typu
ProcessingInstruction, z celem ustawionym na target, danymi tekstowymi ustawionymi na data oraz właścicielem będącym obiektem kontekstu.
Metoda nie weryfikuje poprawności przekazanych danych tekstowych wymaganych dla instrukcji przetwarzania w przypadku XML-a, np. pod względem dopasowania do wzorca Char lub prawidłowego stosowania znaków "xml" czy ":" w jej celu.
Nowa instrukcja przetwarzania zwracana przez metodę createProcessingInstruction() nie jest częścią danego drzewa dokumentu dopóki nie zostanie dodana do innego węzła należącego do drzewa dokumentu. Dlatego nowa instrukcja przetwarzania nie będzie posiadał rodzica (wartość null), aczkolwiek dalej posiada jakiegoś właściciela.
Obiekt zwracany przez metodę createProcessingInstruction() implementuje interfejs ProcessingInstruction, dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia).
Więcej szczegółów związanych z instrukcjami przetwarzania umieściłem w zbiorczym dziale "Podstawy - Węzły znakowe".
Prosty przykład:
<!DOCTYPE html>
<html>
<head>
<script>
function addPI(target, data){
function getInfoPI(desc, whatDoc, whatPI){
info.innerHTML = desc
+ "<br>" + "Interfejs dokumentu: " + whatDoc
+ "<br>" + "Interfejs instrukcji przetwarzania: " + whatPI
+ "<br>" + "Pierwszy argument z metody: " + target
+ "<br>" + "Drugi argument z metody: " + data
+ "<br><br>" + "Właściwość nodeType: " + whatPI.nodeType
+ "<br>" + "Właściwość target: " + whatPI.target
+ "<br>" + "Właściwość nodeName: " + whatPI.nodeName
+ "<br>" + "Właściwość data: " + whatPI.data
+ "<br>" + "Właściwość nodeValue: " + whatPI.nodeValue
+ "<br>" + "Właściwość textContent: " + whatPI.textContent
+ "<br><br>" + "Testowy akapit po serializacji: " + "<br>";
p.appendChild(whatPI);
var newText = document.createTextNode("");
newText.data = new XMLSerializer().serializeToString(p);
info.appendChild(newText);
}
var info = document.getElementById("info");
var p = document.getElementById("tekst");
try{
var newDocXML = document.implementation.createDocument(null, null, null); // nowy dokument XML
var newPI1 = newDocXML.createProcessingInstruction(target, data);
getInfoPI("Parametry dla metody createProcessingInstruction() wywołanej na dokumencie XML:", newDocXML, newPI1);
}
catch(e){
info.innerHTML = "Przekazanie do metody createProcessingInstruction() argumentu niezgodnego z wymogami XML zrzuca błąd:"
+ "<br>" + e // opis zależny od przeglądarki
+ "<br>" + e.constructor; // function DOMException() { [native code] }
}
try{
var newPI2 = document.createProcessingInstruction(target, data);
info.innerHTML += "<br><br>" + "Istnieje możliwość wywołania metody createProcessingInstruction() na dokumencie HTML.";
}
catch(e){
if (e.name == "NotSupportedError"){
info.innerHTML += "<br><br>" + "Wywołanie metody createProcessingInstruction() na dokumencie HTML zrzuca błąd:"
+ "<br>" + e // opis zależny od przeglądarki
+ "<br>" + e.constructor; // function DOMException() { [native code] }
}
}
}
</script>
</head>
<body>
<p>Kliknij konkretny przycisk by dodać nową instrukcję przetwarzania do testowego akapitu.</p>
<input type="button" value="createProcessingInstruction('cel', 'instrukcje')" onclick="addPI('cel', 'instrukcje')">
<input type="button" value="createProcessingInstruction('xml-stylesheet', 'type=text/css href=style.css')" onclick="addPI('cel', 'type=text/css href=style.css')">
<input type="button" value="createProcessingInstruction('xml', 'instrukcje')" onclick="addPI('xml', 'instrukcje')">
<input type="button" value="createProcessingInstruction(':', 'instrukcje')" onclick="addPI(':', 'instrukcje')">
<input type="button" value="createProcessingInstruction('cel', '')" onclick="addPI('cel', '')">
<input type="button" value="createProcessingInstruction('cel', '?>')" onclick="addPI('cel', '?>')">
<input type="button" value="createProcessingInstruction('', 'instrukcje')" onclick="addPI('', 'instrukcje')">
<p id="tekst" >Węzeł tekstowy umieszczony w testowym akapicie.</p>
<p style="color: blue;">Szczegółowe informacje o akapicie i nowej instrukcji przetwarzania:</p>
<p id="info"></p>
</body>
</html>Na chwilę obecną jedynie przeglądarki Firefox i Chrome obsługują metodę createProcessingInstruction() zgodnie z najnowszymi wymaganiami specyfikacji DOM4. Pozostałe przeglądarki mają mniejsze lub większe problemy w tym obszarze.
Składnia Web IDL#
interface Document : Node { [NewObject] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data); };