ECMAScript pro XML:Nativní objekty

Z MDC

E4X přidává do specifikace 4 nové nativní objekty. Objekt XML reprezentuje XML uzel, objekt XMLList uspořádanou kolekci XML uzlů. Objekt Namespace reprezentuje jmenný prostor včetně jeho prefixu a objekt QName reprezentuje jméno XML elementu či atributu včetně jeho jmenného prostoru.

[editovat] Namespace

Reprezentuje jmenný prostor XML elementu či atributu.

[editovat] Konstruktor

new Namespace([[prefix,] uri])

Při vytvoření bez parametrů jsou vlastnosti prefix a uri nastavené na prázdné řetězce. Objekt Namespace s uri nastaveným na prázdný řetězec reprezentuje "žádný" jmenný prostor, který se používá u XML elementů či atributů, u nichž je explicitně řečeno, že do žádného jmenného prostoru nepatří, a že mohou být používány pouze s prefixem rovným prázdnému řetězci.

Pokud je předán jediný argument uri, který je typu Namespace, je vytvořena jeho kopie. Pokud je uri prázdný řetězec, prefix je také nastaven na prázdný řetězec. V ostatních případech, pokud je zadán jen jediný argument, je vrácena hodnota undefined.

Pokud jsou předány dva argumenty, a prefix je prázdný řetězec, je jmenný prostor považován za výchozí (default namespace). Pokud jsou prefix i uri neprázdné řetězce, je vytvořen objekt reprezentující jmenný prostor ve smyslu XML syntaxe xmlns:{prefix}="{uri}".

[editovat] Atributy

Namespace.prototype

Prototypový objekt, je jím objekt Namespace s uri i prefix nastavenými na prázdné řetězce.

constructor

Konstruktor objektu.

prefix

Řetězcová hodnota pouze pro čtení. Pokud je hodnota prázdný řetězec, je jmenný prostor označován jako výchozí (default namespace).

uri

Řetězcová hodnota pouze pro čtení.

[editovat] Metody

toString()

Vrací hodnotu uri jmenného prostoru.

[editovat] QName

Reprezentuje kvalifikované jméno XML elementu či atributu.

[editovat] Konstruktor

new QName([namespace,] name)

Pokud je name jediný argument typu QName, je vrácena jeho kopie.

Pokud jsou zadány oba argumenty, vlastnost localName nově vytvořeného objektu je nastaven podle argumentu name a vlastnost uri nově vytvořeného objektu je nastaven podle argumentu namespace . Pokud je argument name typu QName, je použita hodnota jeho vlastnost localName. Pokud je argument namespace typu Namespace, je použita hodnota jeho vlastnosti uri. Pokud je argument namespace roven null, nově vytvořený objekt bude mít vlastnost uri nastaven na null, což značí jméno, které patří do libovolného jmenného prostoru.

[editovat] Atributy

QName.prototype

Prototypový objekt, je jím objekt QName s vlastnostmi uri a localName nastavenými na prázdné řetězce.

constructor

Konstruktor objektu.

localName

Řetězcová hodnota pouze pro čtení. Pokud je hodnota rovna "*", reprezentuje objekt jakékoli jméno s daným jmenným prostorem.

uri

Řetězcová hodnota pouze pro čtení. Pokud je hodnota null, reprezentuje objekt jméno s jakýmkoli jmenným prostorem.

[editovat] Metody

toString()

Řetězcová hodnota ve tvaru uri::localName. Pokud je uri null, je vrácena hodnota ve tvaru *::localName.

[editovat] Objekt XML

Reprezentuje uzel v XML stromu.

XML uzel je reprezentován svým jménem, sadou prvků, sadou atributů, jmennými prostory a odkazem na předka v XML stromu.

Jméno XML objektu je ekvivalentní jménu XML elementu, a lze získat pomocí metod name a localName. Metoda name vrací typ QName, zatímco metoda localName vrací jméno bez jmenného prostoru.

Sada prvků XML objektu odpovídá potomkům v XML stromu. Je to vlastně pole objektů XML, které je indexováno jejich pořadím v rámci XML stromu. Prvky XML objektu mohou tedy být XML elementy, instrukce zpracování (processing instructions), textové uzly a komentáře. K prvkům XML objektu je možno přistupovat jednak jako k prvkům pole (xmlobject[3] určuje čtvrtý uzel v XML podstromu), nebo pomocí tečkové notace zadáním jména elementu, ke kterému chceme přistoupit. Více o tečkové notaci je v části o operátorech.

K atributům XML objektu je možné přistoupit přes "@" operátor, opět viz. část o operátorech, a pomocí metody attribute.

Objekty XML a XMLList obsahující jediný objekt jsou do značné míry zaměnitelné. Tato zaměnitelnost je záměrná.

[editovat] Konstruktor

new XML([value])

Pokud je konstuktor volán bez argumentů, je vrácen objekt reprezentující prázdný textový uzel. Jinak je argument value [[ECMAScript_pro_XML:Metody#XML|] převeden na typ XML]. Pokud je výsledek tohoto převodu typu XML či XMLList, je vrácena jeho kopie.

Objekt XML lze zapsat také jako literál, který do značné míry využívá syntaxe XML. Na místo textového obsahu elementu, jména elementu, jména atributu či hodnoty atributu lze vložit závorkový výraz - {expression}, ve kterém je expression libovolný výraz v JavaScriptu. Pro vložení složené závorky do XML kódu lze využít entit { a }. Závorkový výraz na místě hodnoty atributu se zapisuje bez uvozovek a na všech místech je výsledek výrazu správně ošetřen a speciální znaky jsou převedeny na entity. Nelze vkládat CDATA sekce. Nejlépe je vše vidět na příkladu.

[editovat] Příklad

var xml = <elementy>
<element>textový obsah</element>
<element>{"textový" + " výraz, <{klidně obsahující závorky}>"}</element>
<{"ele"+"ment"} {"atri"+"but"}={"hodno"+"ta"}/>
</elementy>;
 

[editovat] Atributy

XML.prototype

Prototyp objektu.

XML.ignoreComments

Pokud je nastaveno na true, což je výchozí hodnota, jsou při tvoření nových XML objektů ignorovány komentáře.

XML.ignoreProcessingInstructions

Pokud je nastaveno na true, což je výchozí hodnota, jsou při tvoření nových XML objektů ignorovány XML uzly typu processing instruction.

XML.ignoreWhitespace

Pokud je nastaveno na true, což je výchozí hodnota, jsou při tvoření nových XML objektů nedůležité "bílé" znaky. Pokud jsou dva XML elementy odděleny pouze sekvencí bílých znaků, jsou tyto znaky považovány za nedůležité. Za bílé znaky se považuje mezera (\u0020), CR (\u000D), nový řádek (\u000A) a tabulátor (\u0009).

XML.prettyPrinting

Pokud je nastaveno na true, což je výchozí hodnota, jsou při převádění XML na text ignorovány či přidávány bílé znaky tak, aby výsledné XML uspokojovalo estetické cíťění tvůrců jazyka.

XML.prettyIndent

Číselná hodnota vyjadřující, o kolik mezer se budou v režimu "hezkého tisku" povolovaného vlastností prettyPrinting odsazovat učité elementy oproti svým předkům. Výchozí hodnota je 2.

constructor

Konstruktor objektu.

[editovat] Metody

XML.settings()

Umožňuje snadné získání objektu představujícího nastavení statických vlastností XML a jejich opětovné nastavené. ===Příklad převzatý ze specifikace=== // Create a general purpose function that may need to save and restore XML settings

function getXMLCommentsFromString(xmlString) {
    // save previous XML settings and make sure comments are not ignored 
    var settings = XML.settings();
    XML.ignoreComments = false;
    var comments = XML(xmlString).comment();
    // restore settings and return result 
    XML.setSettings(settings);
    return comments;
}

XML.setSettings([Settings])

Obnoví nastavení statických vlastností XML podle objektu Settings nebo podle výchozího nastavení.

XML.defaultSettings()

Vrátí objekt obsahující výchozí nastavení statických vlastností XML.

addNamespace(namespace)

Přidá deklaraci dalšího jmenného prostoru do kontextu XML uzlu. Argument namespace je upraven stejně jako při použití funkce Namespace(). Pokud tento prvek již obsahuje jmenný prostor se stejným prefixem a jiným uri, bude prefix u již obsaženého jmeného prostoru nastaven na undefined.

appendChild(child)

Přidá "hlubokou" kopii argumentu child na konec seznamu prvků tohoto objektu.

childIndex()

Vrátí číslo reprezentující pozici tohoto objektu vůči jeho předku.

contains(value)

Totožné s object == value. Tato metoda je z důvodu záměrného setření rozdílu mezi objekty XML a XMLList obsahujícím pouze jeden objekt XML.

copy()

Vrátí "hlubokou" kopii tohoto objektu, jehož interní odkaz na předka je nastaven na null.

hasOwnProperty(P)

Vrací boolean, zda objekt obsahuje prvek se jménem P. Pokud je objekt prototypem objektu XML, vrací, zda objekt XML obsahuje metodu s daným názvem. ===Příklady=== <elem><child/></elem>.hasOwnProperty('child') // vrátí true

<elem attr='attr'/>.hasOwnProperty('attr')       // vrátí false
XML.prototype.hasOwnProperty('hasOwnProperty')   // vrátí true

hasComplexContent()

Návratová hodnota typu boolean. Vrací true právě tehdy, objekt obsahuje prvek reprezentující XML uzel typu element.

hasSimpleContent()

Návratová hodnota typu boolean. Vrací true právě tehdy, když objekt neobsahuje žádný prvek reprezentující XML uzel typu element.

inScopeNamespaces()

Vrací pole (typ Array) jmenných prostorů, které jsou platné v tomto uzlu v kontextu jeho předka. var xml = <root xmlns='url1'><elem1 xmlns:n2='url2'/></root>;

xml.inScopeNamespaces()                    // vrátí "url1"
var url1 = new Namespace('url1')           // vrátí "url1"
xml.url1::elem1.inScopeNamespaces()        // vrátí "url2,url1"

insertChildAfter(child1, child2)

Vloží "hlubokou" kopii child2 do tohoto objektu za prvek child1. Pokud je child1 rovno null, je child2 vloženo před všechny prvky tohoto objektu. Pokud child1 není prvkem tohoto objektu, potom metoda neprovede nic.

insertChildBefore(child1, child2)

Vloží "hlubokou" kopii child2 do tohoto objektu před prvek child1. Pokud je child1 rovno null, vloží child2 za všechny prvky tohoto objektu. Pokud child1 není prvkem tohoto objektu, metoda neprovede nic.

length()

Vrací 1. Metoda záměrně stírá rozdíl mezi objekty XML a XMLList.

localName()

Vrací jméno XML uzlu, který tento objekt reprezentuje, bez části jmenného prostoru.

name()

Vrací kvalikované jméno tohoto XML uzlu.

namespace([prefix])

Při volání bez argumentu vrací jmenný prostor tohoto XML uzlu. Pokud je předán argument prefix, je vrácen jmenný prostor patřící k tomuto prefixu. Pokud žádný jmenný prostor není nalezen, je vráceno undefined.

namespaceDeclarations()

Vrací pole (typ Array) jmenných prostorů, které jsou deklarovány v tomto XML uzlu.

nodeKind()

Vrací řetězec určující typ XML uzlu. Možné hodnoty jsou "element", "attribute", "comment", "processing-instruction" a "text".

parent()

Vrátí hodnotu interního odkazu na XML uzel předka.

prependChild(value)

Přidá nový prvek před všechny prvky tohoto objektu.

propertyIsEnumerable(P)

Vrací true, pokud je P rovno 0, false v jiných případech. Tato metoda záměrně stírá rozdíl mezi XMLList a XML.

removeNamespace(namespace)

Odstraní namespace ze seznamu deklarací jmenných prostorů tohoto XML uzlu. Poté vrátí kopii tohoto XML uzlu.

replace(propertyName, value)

Nahradí prvky tohoto objektu určené pomocí propertyName hodnotou value. Atribut propertyName může být číslicový index prvku, řetězcové jméno prvku či kvalifikované jméno. Pokud je propertyName nekvalifikované jméno, jsou nahrazeny všechny prvky s daným jménem s výchozím jmenným prostorem. Argument value může být objekt XML, XMLList, řetězec či jakákoli hodnota převeditelná na řetězec pomocí metody toString. Metoda vrátí objekt, na kterém je volána.

[editovat] Příklad

var xml = <elem><item>A</item><item>B</item></elem>;

xml.replace(0, <item>D</item>);
	Vrátí <elem><item>D</item><item>B</item></elem>

xml.replace("item", <item>C</item>);
	Vrátí <elem><item>C</item></elem>

setChildren(value)

Nahradí všechny prvky tohoto objektu. Argument value může být buďto objekt XML nebo XMLList.

setLocalName(name)

Nastaví nekvalifikované jméno XML objektu.

setName(name)

Nastaví kvalifikované jméno XML objektu. Atribut name je typu QName].

setNamespace(ns)

Nastaví jmenný prostor tohoto prvku. Argument ns je zkonvertován na typ Namespace.

toString()

Vrací textovou hodnotu objektu. Pokud má objekt jednoduchý typ (metoda hasSimpleContent vrací true), vrátí řetězcovou hodnotu textového prvku(ů) tohoto objektu. V ostatních případech vrací text formátovaný jako XML, včetně otevíracího tagu, atributů, deklarací jmených prostorů, XML podstromu a zavíracího tagu.

toXMLString()

Vrací text formátovaný jako XML stejně jako metoda toString, nezávisle na typu obsahu.

valueOf()

Vrátí tento objekt XML.

[editovat] Objekt XMLList

Objekt XMLList reprezentuje uspořádaný seznam XML objektů. Objekt typu XMLList obsahující jediný prvek a objekt typu XML jsou do značné míry vzájemně zaměnitelné.

[editovat] Konstruktor

new XMLList([value])

Pokud je konstruktor volán s žádným argumentem, je vytvořen nový objekt XMLList neobsahující žádný prvek. Pokud je value typu XMLList, je vytvořen nový objekt typu XMLList obsahující mělkou kopii value. V jiných případech je value [[ECMAScript_pro_XML:Metody#XMLList|zkonvertována na typ XMLList].

XMLList lze také zapsat jako literál, který je uvozen sekvencí "<>" a uzavřen sekvencí "</>", obsahujícící XML literály jednotlivých prvků.

[editovat] Příklad

var xmllist = <><item1/></item2/></>;

[editovat] Atributy

XMLList.prototype

Prototyp objektu.

constructor

Konstruktor objektu.

[editovat] Metody

contains(value)

Vrátí, zda tento XMLList obsahuje XML objekt, který by se rovnal argumentu value.

copy()

Vrátí hlubokou kopii tohoto objektu.

hasOwnProperty(P)

Vrátí true, pokud některý z obsažených XML objektů vrátí true při volání hasOwnProperty se stejným argumentem. Při volání na prototypovém objektu XMLList metoda vrací true v případě, že existuje metoda s názvem P.

hasComplexContent()

Návratová hodnota typu Boolean. Pokud XMLList obsahuje jediný objekt XML, vrátí výsledek volání metody hasComplexContent na tento objekt. V ostatních případech vrátí true, pokud obsahuje XML objekt reprezentující element.

hasSimpleContent()

Návratová hodnota typu Boolean. Pokud XMLList obsahuje jediný objekt XML, vrátí výsledek volání metody hasSimpleContent na tomto objektu. V jiném případě vrátí true, pokud neobsahuje žádný XML objekt reprezentující element.

length()

Vrátí počet obsažených XML objektů.

parent()

Vrátí XML objekt, pokud je otcem všech obsažených XML objektů. V jiném případě vrátí undefined.

propertyIsEnumerable(P)

Vrátí true, pokud přes prvek P bude iterováno při použití tohoto objektu v cyklu for in.

toString()

Pokud vrací metoda hasSimpleContent() hodnotu true, potom jsou návratovou hodnotou sloučené textové reprezentace jednotlivých uzlů. V opačném případě je výsledkem řetězec vzniklý sloučením výsledků volání metody toXMLString() na jednotlivé prvky seznamu.

toXMLString()

Návratovou hodnotou je řetězec vzniklý sloučením výsledků volání metod toXMLString() na jednotlivých prvcích seznamu.

valueOf()

Vrátí tento objekt.