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.
Namespace
Reprezentuje jmenný prostor XML elementu či atributu.
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}"
.
Atributy
- Namespace.prototype
- Prototypový objekt, je jím objekt Namespace s
uri
iprefix
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í.
Metody
- toString()
- Vrací hodnotu
uri
jmenného prostoru.
QName
Reprezentuje kvalifikované jméno XML elementu či atributu.
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.
Atributy
- QName.prototype
- Prototypový objekt, je jím objekt QName s vlastnostmi
uri
alocalName
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.
Metody
- toString()
- Řetězcová hodnota ve tvaru
uri::localName
. Pokud jeuri
null
, je vrácena hodnota ve tvaru*::localName
.
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á.
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.
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>;
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.
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í funkceNamespace()
. 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 naundefined
. - 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 prvekchild1
. Pokud jechild1
rovnonull
, jechild2
vloženo před všechny prvky tohoto objektu. Pokudchild1
není prvkem tohoto objektu, potom metoda neprovede nic. - insertChildBefore(child1, child2)
- Vloží "hlubokou" kopii
child2
do tohoto objektu před prvekchild1
. Pokud jechild1
rovnonull
, vložíchild2
za všechny prvky tohoto objektu. Pokudchild1
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ácenoundefined
. - 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 jeP
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
hodnotouvalue
. AtributpropertyName
může být číslicový index prvku, řetězcové jméno prvku či kvalifikované jméno. Pokud jepropertyName
nekvalifikované jméno, jsou nahrazeny všechny prvky s daným jménem s výchozím jmenným prostorem. Argumentvalue
může být objekt XML, XMLList, řetězec či jakákoli hodnota převeditelná na řetězec pomocí metodytoString
. Metoda vrátí objekt, na kterém je volána.
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.
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é.
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ů.
Příklad
var xmllist = <><item1/></item2/></>;
Atributy
- XMLList.prototype
- Prototyp objektu.
- constructor
- Konstruktor objektu.
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ázvemP
. - 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 prvekP
bude iterováno při použití tohoto objektu v cyklu for in. - toString()
- Pokud vrací metoda
hasSimpleContent()
hodnotutrue
, 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í metodytoXMLString()
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.
Informace o původním dokumentu
- Autor: Jan Matoušek