07 April 2004

1. Núcleo del Modelo de Objetos del Documento

Redactores:
Arnaud Le Hors, IBM
Philippe Le Hégaret, W3C
Gavin Nicol, Inso EPS (para Nivel 1 de DOM)
Lauren Wood, SoftQuad, Inc. (para Nivel 1 de DOM)
Mike Champion, Arbortext y Software AG (para Nivel 1 de DOM desde el 20 de Noviembre, 1997)
Steve Byrne, JavaSoft (para Nivel 1 de DOM hasta el 19 de Noviembre, 1997)

Tabla de contenidos

Esta especificación define un conjunto de objetos e interfaces para acceder y manipular objetos del documento. La funcionalidad especificada (la funcionalidad del Núcleo) es suficiente para permitir a los desarrolladores de software y autores de scripts de Webs acceder y manipular contenido HTML [HTML 4.01] y XML [XML 1.0] analizado dentro de productos conformes. El API del Núcleo del DOM permite también crear y poblar un objeto de un Documento usando únicamente llamadas al API de DOM. Una solución para cargar un Documento y almacenarlo continuamente se da en [Cargar y Guardar en DOM Nivel 3].

1.1 Descripción de las Interfaces del Núcleo del DOM

1.1.1 Modelo de Estructura de DOM

El DOM presenta los documentos como una jerarquía de objetos Node (Nodos) que a su vez implementan otras interfaces más especializadas. Algunos tipos de nodos pueden tener nodos child (hijos) de varios tipos, y otros son nodos hoja que no pueden tener nada bajo ellos en la estructura del documento. Para XML y HTML, los tipos de nodos, y los tipos de nodos que estos pueden tener como hijos son los siguientes:

El DOM especifica además una interfaz NodeList para manejar listas ordenadas de Nodes (Nodos), como los hijos de un Node (Nodo), o los Elements (Elementos) devueltos por el método Element.getElementsByTagNameNS(URI espacios de nombres, Nombre local), y también una interfaz NamedNodeMap para manejar listas no ordenadas de nodos referenciados por su atributo de nombre, como los atributos de un Element (Elemento). En DOM, los objetos NodeList y NamedNodeMap están vivos, es decir, los cambios en la estructura subyacente del documento son reflejados en todos los objetos NodeList y NamedNodeMap relevantes. Por ejemplo, si un usuario del DOM obtiene un objeto NodeList que contenga los hijos de un Element, y a continuación añade más hijos a ese element (o los elimina, o modifica), estos cambios se reflejan automáticamente en el NodeList, sin que el usuario tenga que realizar ninguna otra acción. Asimismo, los cambios de un Node en el árbol se reflejan en todas las referencias a ese Node desde los objetos NodeList y NamedNodeMap.

Finalmente, toda interfaz Text, Comment, y CDATASection heredan del interfaz CharacterData.

1.1.2 Gestión de Memoria

La mayoría de los APIs definidos por esta especificación son interfaces más que clases. Eso significa que una implementación concreta solo necesita exponer los métodos con los nombres definidos y la operación especificada, no implementar las clases que corresponden directamente a las interfaces. Esto permite que los APIs del DOM se implementen como una fina capa encima de aplicaciones antiguas con sus propias estructuras de datos, o encima de aplicaciones jerarquías de clases diferentes. Esto también significa que los constructores ordinarios (en el sentido de Java o C++) no pueden usarse para crear objetos del DOM, ya que los objetos subyacentes que deben ser construidos pueden tener muy poca relación con las interfaces del DOM. La solución convencional a esto en el diseño orientado a objetos es definir métodos constructores que creen ejemplares de objetos que implementen las diferentes interfaces. Los objetos que implementan una interfaz "X" se crean con un método "createX()" de la interfaz Document; Esto es así porque todos los objetos del DOM habitan en el contexto de un documento específico.

Las APIs del Núcleo del DOM están diseñadas para ser compatibles con un amplio espectro de lenguajes, incluyendo tanto lenguajes de scripts de uso general como los lenguajes más complejos usados principalmente por programadores profesionales. Así, las APIs del DOM necesitan trabajar bajo distintas filosofías de gestión de memoria, desde plataformas de lenguaje que no exponen al usuario a la gestión de la memoria en absoluto, a aquellos (especialmente Java) que proporcionan constructores explícitos pero también un mecanismo de recogida automática de basura para reclamar la memoria libre, pasando por aquellas (especialmente C/C++) que generalmente exigen al programador que reserve explícitamente la memoria para el objeto, que controle dónde se usa, y que la libere explícitamente para su reutilización. Para asegurar que el API es consistente en todas las plataformas, el DOM no contempla en absoluto las cuestiones de gestión de memoria, sino que deja éstas a cada implementación. Ninguno de los enlaces explícitos para los lenguajes definidos por la API del DOM (para ECMAScript y Java) requieren de ningún método de gestión de memoria, pero los enlaces con el DOM que se crean para otros lenguajes (especialmente C o C++) probablemente necesitarán dicho soporte. Estas extensiones serán responsabilidad de aquellos que adapten el API del DOM a un lenguaje específico, no el Grupo de Trabajo de DOM.

1.1.3 Convenciones de Nombres

Si bien sería deseable tener nombres de atributos y métodos que fueran cortos, informativos, con consistencia interna, y familiares para los usuarios de APIs similares, los nombres tampoco deberían entrar en conflicto con los nombres de APIs antiguas soportadas por las implementaciones del DOM. Además tanto el IDL del DMO (OMG) [OMG IDL] y ECMAScript [ECMAScript] tienen limitaciones significativas a la hora de eliminar las ambigüedades en los nombres provenientes de espacios de nombres (namespaces) diferentes, de modo que es difícil evitar conflictos con nombres cortos y familiares. Así, los nombres del DOM tienden a ser largos y bastante descriptivos con el fin de ser únicos en todas las plataformas.

El Grupo de Trabajo ha intentado también ser consistente internamente al usar los diferentes términos, incluso cuando en otras APIs ciertas distinciones pueden no ser comunes. Por ejemplo, la API de DOM utiliza el método de nombre "remove" ("quitar") cuando el método cambia el modelo estructural, y el método de nombre "delete" ("borrar") cuando el método suprime algo dentro del modelo estructural. La cosa que se borra no se devuelve. La cosa que se quita puede ser devuelta, cuando tenga sentido devolverla.

1.1.4 La Herencia frente a las Visiones Planas del API

Las APIs del Núcleo del DOM presentan dos conjuntos un tanto diferentes de interfaces para un documento XML/HTML: uno presenta una aproximación "orientada a objetos" con una jerarquía de herencia, y una visión "simplificada" que permite que todas las manipulaciones se realicen a través de la interfaz Node sin requerir interfaces de conversión (casts) (en Java o en otros lenguajes C) o interfaz de petición de llamadas en entornos COM. Estas operaciones son bastante costosas en Java y COM, y el DOM pude ser utilizado en entornos de rendimiento crítico, por lo que añadimos una funcionalidad significativa usando simplemente la interfaz Node. Como muchos otros usuarios encontrarán la jerarquía hereditaria más fácil de entender que la aproximación de que en DOM "todo es un Node", también soportamos las interfaces completas de alto nivel para aquellos que prefieran un API más orientado a objetos.

En la práctica, esto significa que hay una cierta carga de redundancia en el API. El Grupo de Trabajo considera que la aproximación "hereditaria" es la visión primaria del API, y que el conjunto completo de funcionalidades de Node es un "extra" que los usuarios pueden emplear, pero que no elimina la necesidad de métodos que un análisis orientado a objetos consideraría necesario en otras interfaces. (Por supuesto, cuando el análisis orientado a objetos (O-O) conduce a un método que es idéntico a otro existente en la interfaz Node, no especificamos uno completamente redundante). Así, aunque hay un atributo genérico Node.nodeName (nodo.nombredenodo) en la interfaz Node, sigue habiendo un atributo Element.tagName en la interfaz Element; ambos atributos deben contener el mismo valor, pero ellos consideran que vale la pena soportar ambos, dadas las diferentes exigencias que debe satisfacer la API del DOM.

1.2 Tipos Básicos

Para asegurar la interoperatibilidad, esta especificación especifica los siguientes tipos básicos utilizados en varios módulos del DOM. Incluso aunque el DOM utiliza los tipos básicos en las interfaces, los enlaces pueden usar diferentes tipos y los enlaces normativos solo son dados para Java y ECMAScript en esta especificación.

1.2.1 El Tipo DOMString

El tipo DOMString se usa para almacenar caracteres [Unicode] como una secuencia de unidades de 16-bit usando UTF-16 como se define en [Unicode] y en la Enmienda 1 de [ISO/IEC 10646].

Los caracteres son normalizados totalmente como se define en el apéndice B de [XML 1.1] si:

Observe que, con excepción de Document.normalizeDocument() y Node.normalize(), en la manipulación de caracteres utilizando métodos DOM no se garantiza que se preserve un texto totalmente normalizado.

Definición del Tipo DOMString

Un DOMString es una secuencia de unidades de 16-bit.


Definición IDL
valuetype DOMString sequence<unsigned short>;

La codificación UTF-16 fue elegida debido a su amplia extensión en programación. Observe que tanto para HTML y XML, el conjunto de caracteres del documento (y por lo tanto la notación de las referencias numéricas de caracteres) está basado en UCS [ISO/IEC 10646]. Una referencia a un carácter numérico simple en un documento fuente pude por lo tanto en algunos casos corresponder a dos unidades de 16-bit en un DOMString (una sustitución de mayor peso y una sustitución de menor peso). Para cuestiones relacionadas con comparaciones de cadenas, dirigirse a Comparación de Cadenas en el DOM.

Para Java y ECMAScript, DOMString está destinado al tipo Cadena (String) porque ambos lenguajes utilizan también UTF-16 para su codificación.

Nota: En Agosto del 2000, la especificación OMG IDL ([OMG IDL]) incluyó el tipo wstring. Sin embargo, esa definición no encontrón la interoperatibilidad con los criterios de la API del DOM ya que ello requiere de negociación para decidir el ancho y la codificación de un carácter.

1.2.2 El Tipo DOMTimeStamp

El Tipo DOMTimeStamp se utiliza para almacenar una fecha absoluta o relativa.

Definición del Tipo DOMTimeStamp

Un DOMTimeStamp representa un número de milisegundos.


Definición IDL
typedef unsigned long long DOMTimeStamp;

Para Java, DOMTimeStamp está destinado al tipo long (largo). Para ECMAScript, DOMTimeStamp está destinado al tipo Date (Fecha) porque el rango del tipo integer (entero) es más pequeño.

1.2.3 El Tipo DOMUserData

El tipo DOMUserData se utiliza para almacenar datos de la aplicación.

Definición del Tipo DOMUserData

Un DOMUserData representa una referencia a un dato de la aplicación.


Definición IDL
typedef any DOMUserData;

Para Java, DOMUserData está destinado al tipo Object (objeto). Para ECMAScript, DOMUserData está destinado al tipo any type (cualquier tipo).

1.2.4 El Tipo DOMObject

El tipo DOMObject se utiliza para representar un objeto.

Definición del Tipo DOMObject

Un DOMObject representa una referencia a un objeto.


Definición IDL
typedef Object DOMObject;

Para Java y ECMAScript, DOMObject está reservado al tipo Object (Objeto).

1.3 Consideraciones Generales

1.3.1 Comparación de Cadenas en el DOM

EL DOM tiene muchas interfaces que implican un emparejamiento de cadenas. Para XML, la comparación de cadenas son sensibles a mayúsculas y minúsculas (case-sensitive) y realizadas con una comparación binaria de las unidades de 16-bit del DOMStrings. Sin embargo, para lenguajes insensibles a mayúsculas y minúsculas (case-insensitive), como HTML 4.01 o anteriores, estas comparaciones son insensibles a mayúsculas y minúsculas (case-insensitive) son apropiadas.

Observe que los procesadores HTML a menudo realizan una normalización de marcas en mayúsculas (con menor frecuencia en minúsculas) después de que la estructura del DOM sea construida. Este típicamente utiliza las mayúsculas para los nombres de element (elementos) y las minúsculas para los nombres de atributos. Por esta razón, las aplicaciones deben también comparar los nombres de elementos y atributos devueltos por la implementación DOM de una manera insensible a mayúsculas y minúsculas (case-insensitive).

La normalización del carácter, es decir, la transformación en su forma totalmente normalizada como se define en [XML 1.1], es asumida para pasarla en tiempo de serialización. El módulo del DOM Nivel 3 Cargar y Guardar [DOM Nivel 3 Cargar y Guardar] proporciona un mecanismo de serialización. (ver la interfaz DOMSerializer, sección 2.3.1) y utiliza los parámetros de DOMConfiguration "normalize-characters" (normalizar caracteres) y "check-character-normalion " (test de normalización de caracteres) para asegurar que el texto es totalmente normalizado [XML 1.1]. Otros mecanismos de serialización construidos sobre el Núcleo del DOM Nivel 3 tienen que asegurar que el texto es totalmente normalizado.

1.3.2 DOM URIs

La especificación DOM confía en los valores DOMString como identificadores de recursos, tal que se cumplan las siguientes condiciones:

  1. Un identificador absoluto identifica completamente un recurso en la Web;
  2. La equivalencia de cadena simple establece la equivalencia de identificadores de recursos absolutos, y ninguna otra equivalencia de identificadores de recursos es considerada significativa para la especificación del DOM;
  3. Un identificador relativo fácilmente es detectado y hecho absoluto en relación a un identificador absoluto;
  4. La recuperación de contenido de un recurso pude ser llevada a cabo donde sea requerido.

El termino "URI absoluta" se refiere a un identificador de recurso completo y el termino "URI relativa" se refiere a un identificador de recuro incompleto.

Dentro de las especificaciones del DOM, estos identificadores son denominados URIs, "Uniform Resource Identifiers" (Identificadores de Recurso Uniformes), pero esto es en sentido absoluto. La implementación del DOM no procesa necesariamente estas URIs conforme a la especificación del URI [IETF RFC 2396]. Generalmente la forma particular de estos identificadores debe ser ignorada.

Cuando no es posible ignorar completamente el tipo de un URI del DOM, debido a que un identificador relativo tiene que ser pasado a absoluto o porque el contenido debe ser recuperado, la implementación del DOM debe al menos soportar tipos de identificadores apropiados para procesar el contenido. [HTML 4.01], [XML 1.0], y la especificación de espacio de nombre (namespace) asociados [Espacios de Nombres XML] sostenidos sobre [IETF RFC 2396] determinan caracteres permitidos y resuelven las URIs relativas. Otras especificaciones tales como espacios de nombre (namespaces) en XML [Espacios de Nombres XML 1.1] pueden confiar en la alternativa de tipos de identificadores de recursos que pueden, por ejemplo, incluir caracteres no ASCII (non-ASCII), necesitando apoyo para los tipos de identificadores de recursos alternativos donde sea requerido por la especificación aplicable.

1.3.3 Espacios de Nombres XML (XML Namespaces)

DOM Nivel 2 y 3 soportan espacios de nombres XML [Espacio de Nombres XML] mediante el aumento de varios interfaces del Núcleo del DOM Nivel 1 para permitir crear y manipular elementos y atributos asociados a los espacios de nombre. Cuando [XML 1.1] está en uso (vea Document.xmlVersion), el DOM Nivel 3 también soporta [Espacios de Nombres XML 1.1].

DOM está preocupado, por los atributos especiales utilizados para la declaración de espacios de nombres XML que aun son expuestos y pueden ser manipulados justamente como cualquier otro atributo. Sin embargo, los nodos permanentemente son enlazados a URIs de espacios de nombre cuando son creados. Consecuentemente, mover un nodo dentro de un documento, usando un prefijo de espacio de nombre DOM o un URI espacio de nombre. Asimismo, creando un nodo con un prefijo espacio de nombre y URI espacio de nombre, o cambiando el prefijo espacio de nombre o el nodo, no termina en una adición, retirada o modificación de cualquier atributo especial para declarar espacios de nombres apropiados en XML. La validación de espacios de nombre no se cumple; la aplicación DOM es la responsable. En particular, ya que el mapeo entre prefijos y URIs de espacios de nombre no se cumple, el resultado del documento no puede ser ingenuamente seriado. Por ejemplo, las aplicaciones deberían declarar cada espacio de nombre en uso cuando un documento es serializado.

En general, la implementación del DOM (y superiores) no realizan ninguna normalización o conversión (canonicalización) del URI. Los URIs dados a DOM son asumidos para ser validos (Ej., caracteres como espacios en blanco son escapados/evitados correctamente), y no se realiza ninguna comprobación léxica. Las referencias absolutas de URI son tratadas como cadenas y comparadas literalmente. Las referencias a URIs de espacios de nombres relativas son tratadas como indefinidas. Para asegurar la interoperatibilidad solo se deberían utilizar las referencias de URI de espacios de nombres absolutas (es decir, referencias URI que empiezan con un nombre de esquema y dos puntos). Las aplicaciones deberían utilizar el valor null (nulo) como el parámetro de namespaceURI para los métodos que no desean tener ningún espacio de nombre. En lenguajes de programación donde las cadenas vacías pueden ser diferentes a nulo (null), las cadenas vacías, cuando son dadas como un URI de espacio de nombre, son convertidas a null. Esto es verdadero aun cuando DOM no haga ninguna comprobación léxica de URIs.

Nota: Element.setAttributeNS(null, ...) pone el atributo en la partición por tipo de elemento como se define en Particiones de Espacio de Nombres XML en [Espacios de Nombres XML].

Nota: En el DOM, todos los atributos de espacio de nombre declarados están por definición atados al URI de espacio de nombre: "http://www.w3.org/2000/xmlns/". Estos son los atributos cuyo prefijo de espacio de nombre o nombre cualificado es "xmlns" como se presenta en [Espacios de Nombres XML 1.1].

En un documento sin espacios de nombres, la lista hija de una Referencia de Entidad de un nodo es siempre la misma que la corresponde a la Entidad. Esto no es verdadero en un documento donde una entidad contiene a prefijos de espacio de nombre sin vincular. En tal caso, el descendente de la correspondiente Referencia de Entidad de nodos puede ser atado a diferentes URIs de espacio de nombre, dependiendo de donde sean las referencias de entidad. También, porque, en el DOM, los nodos siempre permanecen vinculados al mismo URI de espacio de nombre, moviendo la Referencia de Entidad los nodos pueden llevar a documentos que no puedan ser serializados. Esto es verdad cuando el método Document.createEntityReference(name) se utiliza para crear referencias de entidades que correspondan a tales identidades, donde los descendentes devueltos de la (EntityReference) Referencia de Entidad no est6acute;n vinculados. Mientras DOM Nivel 3 tiene soporte para la resolución de prefijos de espacios de nombres, el uso de tales entidades y referencias de entidad deberían ser evitados o utilizarse en caso extremo.

Los métodos "NS" (NameSpace - Espacio de Nombre), tales como Document.createElementNS(namespaceURI, qualifiedName) y Document.createAttributeNS(namespaceURI, qualifiedName), son propuestos para ser utilizados por aplicaciones de espacio de nombre consistentes. Las aplicaciones simples que no utilizan espacios de nombres pueden utilizar los métodos del DOM Nivel 1, tales como Document.createElement(tagName) y Document.createAttribute(name). Los elementos y atributos creados por este sistema no tienen ningún prefijo de espacio de nombre, URI de espacio de nombre, o nombre local.

Nota: Los métodos de espacios de nombre del DOM Nivel 1 son ignorados. Por lo tanto, mientras que por fuerza se utilizan estos métodos cuando no se trata con espacios de nombres, la utilización de estos y los nuevos al mismo tiempo deberían ser evitados. Los métodos de DOM Nivel 1 únicamente identifican nodos de atributos para su Node.nodeName. Al contrario, los métodos del DOM Nivel 2 relacionados con espacios de nombres, identifican nodos de atributos para su Node.namespaceURI y Node.localName. Por esta diferencia fundamental, mezclar ambos conjuntos de métodos puede conducir a resultados imprevisibles. En particular, utilizando Element.setAttributeNS(URI espacio de nombre, Nombre cualificado, valor), un elemento (element) puede tener dos atributos (o más) que tengan el mismo Node.nodeName, pero diferente Node.namespaceURIs. Llamando a Element.getAttribute(nombre) con ese nodeName podría entonces devolver cualquiera de esos atributos. El resultado depende de la implementación. Igualmente, utilizando Element.setAttributeNode(nuevo atributo), uno puede obtener dos atributos (o más) que tengan diferente Node.nodeNames pero el mismo Node.prefix y Node.namespaceURI. En este caso Element.getAttributeNodeNS(URI espacio de nombre, Nombre local) devolverá uno u otro atributo, dependiendo de la implementación. La única garantía en tales casos es que todos los métodos que tienen acceso a un elemento llamado por su nodeName accederá al mismo elemento, y todos los métodos que acceden a un nodo (node) por su URI y nombre local (localname) accederá al mismo nodo. Por ejemplo, Element.setAttribute(nombre, valor) y Element.setAttributeNS(URI espacio de nombre, Nombre cualificado, valor) afectan al nodo devuelto igual que Element.getAttribute(nombre) y Element.getAttributeNS(URI espacio de nombre, Nombre local), respectivamente.

1.3.4 URIs Base

El DOM Nivel 3 añade soporte para la propiedad [URI Base] definida en [Conjunto de Información XML] para proporcionar un nuevo atributo sobre la interfaz del Nodo que expone esta información. Sin embargo, a diferencia del atributo Node.namespaceURI, el atributo Node.baseURI no es una pieza estática de la información que cada nodo lleva. En cambio, este es un valor que dinámicamente es calculado de acuerdo a [Base XML]. Esto significa que este valor depende de la localización del nodo en el árbol y moverlo de un lugar a otro en el árbol puede afectar a su valor. Otros cambios, como agregar o cambiar un atributo xml:base en un nodo que es preguntado o de uno de sus ascendentes puede también afectar a su valor.

Una consecuencia de esto es que cuando referencias de entidad externa son expandidas en la construcción del Documento uno puede tener que añadir, o modificar, un atributo xml:base al Elemento de los nodos al principio del contenido en la entidad que será expandida para que el Node.baseURI devuelva el valor correcto. En el caso de Instrucción de Procesado de los nodos originales contenidos en la entidad que será expandida perderán la información. [DOM Nivel 3 Cargar y Guardar] mantiene elementos aquí descritos y generan una advertencia en el último caso.

1.3.5 Implementación Mixta en DOM

Como nuevos vocabularios de XML son desarrollados, para estas definiciones de vocabularios se está empezando también a definir APIs especializadas para manipular las instancias XML de estos vocabularios. Esto generalmente está hecho por la ampliación del DOM que proporciona interfaces y métodos que realizan operaciones frecuentemente necesarias para sus usuarios. Por ejemplo, las especificaciones MathML (funciones matemáticas) [MathML 2.0] y SVG [SVG 1.1] han desarrollado extensiones DOM para permitir a los usuarios manipular los casos de esos vocabularios usando la semántica apropiada para matemáticas e imágenes, respectivamente, así como la semántica genérica del DOM XML. Los casos de SVG y MathML a menudo son embebidos en los Documentos XML conformados de forma diferente a XHTML.

Mientras que los Espacios de Nombres (Namespaces) en la especificación de XML [Espacios de Nombres XML] proporcionan mecanismos para integrar estos documentos a nivel de sintaxis, está claro que la Recomendación DOM Nivel 2 [Núcleo del DOM Nivel 2] no es bastante rico para cubrir todas las cuestiones que se han encontrado haciendo estas diferentes implementaciones DOM siendo utilizadas juntas en una sola aplicación. DOM Nivel 3 trata con las exigencias causadas por fragmentos embebidos escritos según lenguajes de marcas específicos (el componente embebido) en un documento donde el resto de marcas no se escriben según a al lenguaje de marcas especifico (el documento anfitrión). Este no trata con fragmentos embebidos por referencias o unión.

Una implementación DOM que soporta el Núcleo del DOM Nivel 3 deberá ser capaz de colaborar con subcomponentes que implementen DOMs específicos para ensamblar un documento compuesto que puede ser leído y manipulado vía interfaces de DOM como si esto fuese un todo.

La operación normal de tipo de conversión (typecast) sobre un objeto debería soportar las interfaces esperadas por el código heredado para un tipo de documento dado. Las técnicas de conversión de tipos (Typecasting) pueden no ser adecuadas para la selección entre múltiples especificaciones de DOM de un objeto el cual fue combinado en tiempo de ejecución, porque todos estos no pueden ser parte del mismo objeto que se definió por el modelo de objetos de enlace. Los conflictos son los más obvios con el objeto Documento, ya que este es compartido como propietario por el resto del documento. En un documento homogéneo, los elementos confían en el documento para servicios especializados y construcción de nodos especializados. En un documento heterogéneo, los elementos de diferentes módulos esperan servicios diferentes y APis del mismo objeto del Documento, ya que solo puede haber un dueño y una raí en la jerarquía del documento.

1.3.6 Funcionalidades del DOM

Cada módulo DOM define una o más funcionalidades, listadas en la sección de conformidad (Conformidad). Las funcionalidades son insensibles a mayúsculas y minúsculas (case-insensitive) y son definidas también por un conjunto específico de versiones. Por ejemplo, esta especificación define las funcionalidades "Núcleo" y "XML", para la versión "3.0". Las versiones "1.0" y "2.0" pueden ser utilizadas también para definir las funcionalidades en el correspondiente nivel de DOM. Para evitar posibles conflictos, por convención los nombres referidos a funcionalidades definidos fuera de la especificación DOM deberían hacerse únicos. Las aplicaciones entonces podrían requerir para las funcionalidades que sean soportados por una implementación DOM utilizando los métodos DOMImplementationSource.getDOMImplementation(funcionalidades) o DOMImplementationSource.getDOMImplementationList(funcionalidades), comprueba las funcionalidades soportados por una implementación DOM usando el método DOMImplementation.hasFeature(funcionalidad, versión), o por un nodo especificado utilizando Node.isSupported(funcionalidad, versión). Observe que cuando se utilizan los métodos que toman una funcionalidad y una versión como parámetros, las aplicaciones pueden usar null (nulo) o una cadena vacía para el parámetro versión si no desean especificar una versión en particular para la funcionalidad especificada.

Hasta los módulos de DOM Nivel 2, todas las interfaces, que eran una extensión de otra existente, era accesible utilizando modelos de mecanismos de enlaces específicos si la funcionalidad asociada a la extensión era soportada. Por ejemplo, un caso de interfaz EventTarget podría ser obtenido desde una interfaz del Nodo si la funcionalidad "Events" era soportada por el nodo.

Como se comento en implementaciones Mixtas del DOM, el Núcleo del DOM Nivel 3 debería ser capaz de colaborar con subcomponentes específicos DOMs implementados. Para ese efecto, se introdujeron los métodos DOMImplementation.getFeature(funcionalidad, versión) y Node.getFeature(funcionalidad, versión). En el caso de DOMImplementation.hasFeature(funcionalidad, versión) y Node.isSupported(funcionalidad, versión), si un signo más "+" precede a cualquier nombre de funcionalidad, las implementaciones están considerando que la funcionalidad especificada no puede ser convertida directamente pero requiere el descubrimiento por DOMImplementation.getFeature(funcionalidad, versión) y Node.getFeature(funcionalidad, versión). Sin el más, solo son consideradas las funcionalidades cuyas interfaces son convertibles directamente.

// ejemplo 1, sin precedencia del "+"
if (myNode.isSupported("Events", "3.0")) {
    EventTarget evt = (EventTarget) myNode;
    // ...
}
// ejemplo 2, con el "+"
if (myNode.isSupported("+Events", "3.0")) {
    // (el signo más "+" es irrelevante para el método getFeature en sí mismo
    // y es ignorado por este método de todos modos)
    EventTarget evt = (EventTarget) myNode.getFeature("Events", "3.0");
    // ...
}

1.3.7 Bootstrapping

Como las versiones anteriores de la especificación del DOM solo definieron un conjunto de interfaces, las aplicaciones tuvieron que confiar en algunas implementaciones dependientes del código en un principio. Sin embargo, la codificación estricta de la aplicación en una implementación específica impide que la aplicación funcione en otras implementaciones y que se utilice la implementación más conveniente disponible. Al mismo tiempo, las implementaciones también pueden necesitar cargar módulos o realizar otras instalaciones para adaptarse eficientemente a un conjunto de carácterísticas/funcionalidades diferentes y a veces mutuamente excluyentes.

Para solucionar estos problemas esta especificación presenta un objeto DOMImplementationRegistry con una función que deja que una aplicación encuentre implementaciones, basadas en las carácterísticas/funcionalidades específicas que esta requiere. Como se encuentra este objeto y a que se parece exactamente no se define aquí, porque esto no puede ser realizado en un lenguaje de manera independiente. En cambio, cada lenguaje vinculado define su propia forma de hacer esto. Vea Vínculo con el Lenguaje Java y Vínculo con el Lenguaje ECMAScript para las especificaciones.

En todos los casos, aunque, el DOMImplementationRegistry proporciona un método getDOMImplementation que acepta una cadena de funcionalidades, que es pasada a cada DOMImplementationSource conocido hasta que un DOMImplementation adecuado sea encontrado y devuelto. El DOMImplementationRegistry también proporciona un método getDOMImplementationList que acepta una cadena de funcionalidades, que es pasada a cada DOMImplementationSource conocido, y devuelve una lista de DOMImplementations adecuados. Estos dos métodos son iguales que los encontrados en la interfaz DOMImplementationSource.

Cualquier número de objetos DOMImplementationSource pueden ser registrados. Una fuente pude devolver uno o más DOMImplementation únicos (singletons) o construir objetos DOMImplementation, dependiendo según de si la funcionalidad requiere un estado específico en el objeto DOMImplementation.

1.4 Interfaces Fundamentales: Módulo Núcleo

Las interfaces dentro de esta sección son consideradas fundamentales, y debe ser completamente implementado para todas las implementaciones con conformidad del DOM, incluyendo todas las implementaciones DOM HTML [HTML DOM Nivel 2], a menos que no sea especificado.

Una aplicación DOM debe utilizar el método DOMImplementation.hasFeature(funcionalidad, versión) con los valores de Parámetros "Core" (Núcleo) y "3.0" (respectivamente) para determinar si este módulo es o no realmente soportado por la implementación. Cualquier aplicación con conformidad a DOM Nivel 3 o módulo del DOM Nivel 3 debe conformarse al módulo Núcleo. Por favor referirse a conformidad para más información en esta misma especificación. El módulo del Núcleo del DOM Nivel 3 es compatible con el módulo del Núcleo del DOM Nivel 2 [Núcleo del DOM Nivel 2], es decir, una implementación con el Núcleo DOM Nivel 3 que devuelve verdadero con el número de versión "3.0" debe también devolver verdadero para esta funcionalidad cuando el número de versión es "2.0", "" o, null (nulo).

Excepción DOMException

Las operaciones del DOM sólo provocan excepciones en circunstancias "excepcionales", es decir, cuando una operación es imposible de realizar (también por razones lógicas, porque se pierden datos, o porque la implementación se vuelve inestable). En general, los métodos del DOM devuelven valores de error específico en situaciones ordinarias de procesamiento, tales como errores de exceso de rango al utilizar NodeList.

Las implementaciones deben provocar otras excepciones bajo otras circunstancias. Por ejemplo, las implementaciones deben provocar una excepción dependiendo de la implementación si se pasa un argumento null cuando null no era esperado.

Algunos lenguajes y sistemas de objetivo no soportan el concepto de excepción. Para tales sistemas, las condiciones de error pueden ser indicadas utilizando mecanismos de información de errores nativos. Para algunos vinculados, por ejemplo, los métodos pueden devolver códigos de error similares los enumerados en las descripciones de los métodos correspondientes.


Definición IDL
Excepción DOMException {
  unsigned short   code;
};
// ExceptionCode (Código de Excepción)
const unsigned short      INDEX_SIZE_ERR                 = 1;
const unsigned short      DOMSTRING_SIZE_ERR             = 2;
const unsigned short      HIERARCHY_REQUEST_ERR          = 3;
const unsigned short      WRONG_DOCUMENT_ERR             = 4;
const unsigned short      INVALID_CHARACTER_ERR          = 5;
const unsigned short      NO_DATA_ALLOWED_ERR            = 6;
const unsigned short      NO_MODIFICATION_ALLOWED_ERR    = 7;
const unsigned short      NOT_FOUND_ERR                  = 8;
const unsigned short      NOT_SUPPORTED_ERR              = 9;
const unsigned short      INUSE_ATTRIBUTE_ERR            = 10;
// Introducido en DOM Nivel 2:
const unsigned short      INVALID_STATE_ERR              = 11;
// Presentado en DOM Nivel 2:
const unsigned short      SYNTAX_ERR                     = 12;
// Introducido en DOM Nivel 2:
const unsigned short      INVALID_MODIFICATION_ERR       = 13;
// Introducido en DOM Nivel 2:
const unsigned short      NAMESPACE_ERR                  = 14;
// Introducido en DOM Nivel 2:
const unsigned short      INVALID_ACCESS_ERR             = 15;
// Introducido en DOM Nivel 3:
const unsigned short      VALIDATION_ERR                 = 16;
// Introducido en DOM Nivel 3:
const unsigned short      TYPE_MISMATCH_ERR              = 17;

Grupo de Definiciones ExceptionCode

Un entero que indica el tipo de error generado.

Nota: Otros códigos numéricos son reservados por W3C para posibles usos futuros.

Definición de Constantes
DOMSTRING_SIZE_ERR
Si el tamaño de texto especificado no cabe en un DOMString.
HIERARCHY_REQUEST_ERR
Si algún Nodo es insertado en algún sitio al que no pertenece.
INDEX_SIZE_ERR
Si el índice o el tamaño son negativos, o mayores que el valor permitido.
INUSE_ATTRIBUTE_ERR
Si se intenta añadir un atributo que ya está siendo utilizado en algún otro lugar.
INVALID_ACCESS_ERR, introducido en DOM Nivel 2.
Si un parámetro o una operación no es soportado por el objeto subyacente.
INVALID_CHARACTER_ERR
Si se especifica un carácter no válido o ilícito, como por ejemplo en un nombre XML.
INVALID_MODIFICATION_ERR, introducido en DOM Nivel 2.
Si se intenta modificar el tipo de objeto subyacente.
INVALID_STATE_ERR, introducido en DOM Nivel 2.
Si se intenta hacer un objeto que no es, o no es más largo.
NAMESPACE_ERR, introducido en DOM Nivel 2.
Si se intenta crear o cambiar un objeto en una ruta que es incorrecta con respecto a los espacios de nombre.
NOT_FOUND_ERR
Si se intenta hacer referencia a un Nodo en un contexto en el que no existe.
NOT_SUPPORTED_ERR
Si la implementación no soporta el tipo de objeto u operación requerido.
NO_DATA_ALLOWED_ERR
Si se especifican datos para un Nodo que no soporta datos.
NO_MODIFICATION_ALLOWED_ERR
Si se intenta modificar un objeto que no admite modificaciones.
SYNTAX_ERR, introducido en DOM Nivel 2.
Si una cadena no válida o ilícita es especificada.
TYPE_MISMATCH_ERR, introducido en DOM Nivel 3.
Si el tipo de un objeto es incompatible con el tipo de parámetro esperado asociado al objeto.
VALIDATION_ERR, introducido en DOM Nivel 3.
Si una llamada a un método como insertBefore o removeChild hiciera al Nodo no válido con respecto a una "validez parcial", esta excepción sería provocada y la operación no se realizaría. Este código es usado en [Validación del DOM Nivel 3]. Vea está especificación para información adicional.
WRONG_DOCUMENT_ERR
Si un Nodo es usado en un documento diferente del que lo creó (que no lo soporte).

Interfaz DOMStringList (introducido en DOM Nivel 3)

La interfaz DOMStringList proporciona la abstracción de un conjunto ordenado de valores DOMString, sin definir o restringir como se implementa este conjunto. Los elementos (items) en el DOMStringList son accesibles por un índice entero que empieza en el 0.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz DOMStringList {
  DOMString          item(in unsigned long index);
  readonly attribute unsigned long   length;
  boolean            contains(in DOMString str);
};

Atributos
length of type unsigned long, readonly
El número de DOMStrings en la lista. El rango de índices válidos de nodos hijos va desde 0 hasta length-1 ambos inclusive.
Métodos
contains
Comprueba si una cadena es parte de este DOMStringList.
Parámetros
str of type DOMString
La cadena a buscar.
Valor devuelto

boolean

true si la cadena ha sido encontrada, false si no lo ha sido.

Sin Excepciones
item
Devuelve el elemento del conjunto indexth. Si index es mayor o igual que el número de DOMStrings en la lista, esto devuelve null (nulo).
Parámetros
index of type unsigned long
El índice en el conjunto.
Valor Devuelto

DOMString

El DOMString en la posición indexth en el DOMStringList, o null si ese no es un index válido.

Sin Excepciones

Interfaz NameList (introducido en DOM Nivel 3)

La interfaz NameList proporciona la abstracción de un conjunto ordenado de pares paralelos de valores de nombre y espacio de nombre (que podrían ser valores nulos), sin definir o establecer como se implementa este conjunto. Los elementos en el NameList son accesibles por un índice entero, comenzando desde 0.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz NameList {
  DOMString          getName(in unsigned long index);
  DOMString          getNamespaceURI(in unsigned long index);
  readonly attribute unsigned long   length;
  boolean            contains(in DOMString str);
  boolean            containsNS(in DOMString namespaceURI, 
                                in DOMString name);
};

Atributos
length of type unsigned long, readonly
El número de pares (nombre y URI espacio de nombre) en la lista. El rango de índices válidos de nodos hijos va desde 0 a length-1 ambos inclusive.
Métodos
contains
Comprueba si un nombre es parte de este NameList.
Parámetros
str of type DOMString
El nombre a buscar.
Valor Devuelto

boolean

true si el nombre ha sido encontrado, false en caso contrario.

Sin Excepciones
containsNS
Comprueba si el par URI de espacio de nombre/nombre (namespaceURI/name) es parte de esta NameList.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre a buscar.
name of type DOMString
El nombre a buscar.
Valor Devuelto

boolean

true si el par namespaceURI/name ha sido encontrado, false en caso contrario.

Sin Excepciones
getName
Devuelve el nombre del elemento indexth en el conjunto.
Parámetros
index of type unsigned long
El índice del conjunto.
Valor Devuelto

DOMString

El nombre de la posición indexth en el NameList, o null si no hay nombre para el índice especificado o si el índice está fuera del rango.

Sin Excepciones
getNamespaceURI
Devuelve el elemento URI espacio de nombre indexth en el conjunto.
Parámetros
index of type unsigned long
Indice dentro del conjunto.
Valor Devuelto

DOMString

El URI de espacio de nombre en la posición indexth en el NameList, o null si no hay nombre para el índice especificado o si el índice está fuera del rango.

Sin Excepciones

Interfaz DOMImplementationList (introducido en DOM Nivel 3)

La interfaz DOMImplementationList proporciona la abstracción de un conjunto ordenado de implementaciones DOM, sin definir o establecer como es implementado este conjunto. Los elementos en el DOMImplementationList son accesibles por un índice entero, comenzando desde 0.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz DOMImplementationList {
  DOMImplementation  item(in unsigned long index);
  readonly attribute unsigned long   length;
};

Atributos
length of type unsigned long, readonly
El número de DOMImplementations (implementaciones DOM) en la lista. El rango de índices validos de nodos hijos va desde 0 a length-1 ambos inclusive.
Métodos
item
Devuelve el elemento indexth en el conjunto. Si index es mayor o igual que el número de DOMImplementations en la lista, este devuelve null.
Parámetros
index of type unsigned long
El índice en el conjunto.
Valor Devuelto

DOMImplementation

El DOMImplementation en la posición indexth en el DOMImplementationList, o null si ese índice no es válido.

Sin Excepciones

Interfaz DOMImplementationSource (introducido en DOM Nivel 3)

Esta interfaz permite a DOM implementar soporte de una o más implementaciones, basado en rasgos de funcionalidades requeridas y versiones, como se especificó en Funcionalidades del DOM. Cada objeto DOMImplementationSource implementado es listado en la lista de enlace específica de fuentes disponibles para que sus objetos DOMImplementation estén disponibles.


Definición IDL

Métodos
getDOMImplementation
Un método que solicita la primera implementación DOM que soporta la funcionalidad especificada.
Parámetros
features of type DOMString
Una cadena que especifica que funcionalidades y versiones son requeridas. Esta es una lista separada por espacios en la que cada funcionalidad es especificada por su nombre opcionalmente seguido por un espacio y un número de versión.
Este método devuelve el primer elemento de la lista devuelta por getDOMImplementationList.
Por ejemplo, la cadena "XML 3.0 Traversal +Events 2.0" solicitará una implementación DOM que soporte el módulo "XML" para su versión 3.0, un módulo que soporte el módulo "Traversal" para cualquier versión, y el módulo "Events" para su versión 2.0. El módulo "Events" debe ser accesible utilizando el método Node.getFeature() y DOMImplementation.getFeature().
Valor Devuelto

DOMImplementation

La primera implementación DOM que soporte las funcionalidades designadas, o null si esta fuente no tiene ninguno.

Sin Excepciones
getDOMImplementationList
Un método para solicitar una lista de implementaciones DOM que soporten las funcionalidades y versiones especificadas, como lo especificado en Funcionalidades del DOM.
Parámetros
features of type DOMString
Una cadena que especifica que funcionalidades y versiones son solicitadas. Esta es una lista separada por espacios en la que cada funcionalidad es especificada por su nombre opcionalmente seguido por un espacio y un número de versión. Es algo como: "XML 3.0 Traversal +Events 2.0"
Valor Devuelto

DOMImplementationList

Una lista de implementaciones DOM que soportan las funcionalidades deseadas.

Sin Excepciones

Interfaz DOMImplementation

La interfaz DOMImplementation proporciona un conjunto de métodos para realizar operaciones que son independientes de cualquier ejemplo particular del modelo de objetos del documento.


Definición IDL
interfaz DOMImplementation {
  boolean            hasFeature(in DOMString feature, 
                                in DOMString version);
  // Introducido en DOM Nivel 2:
  DocumentType       createDocumentType(in DOMString qualifiedName, 
                                        in DOMString publicId, 
                                        in DOMString systemId)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  Document           createDocument(in DOMString namespaceURI, 
                                    in DOMString qualifiedName, 
                                    in DocumentType doctype)
                                        raises(DOMException);
  // Introducido en DOM Nivel 3:
  DOMObject          getFeature(in DOMString feature, 
                                in DOMString version);
};

Métodos
createDocument introducido en DOM Nivel 2
Crea un objeto Documento DOM del tipo especificado con su elemento documento.
Observe que se basa en DocumentType dado para crear el documento, la implementación puede concretar que objetos Document soportan funcionalidades adicionales en el "Núcleo", como "HTML" [HTML DOM Nivel 2]. De otra parte, poniendo el DocumentType después de que el documento fuese creado hace que esto sea muy poco probable de que ocurra. Alternativamente, los métodos de creación Document especificados, como createHTMLDocument [HTML DOM Nivel 2], pueden ser usados para obtener los tipos específicos de objetos Document.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del elemento documento a crear o null.
qualifiedName of type DOMString
El nombre idóneo de un elemento documento que será creado o null.
doctype of type DocumentType
El tipo de documento que será creado o null.
Cuando doctype no es null, su atributo Node.ownerDocument se pone al documento que está siendo creado.
Valor Devuelto

Document

Un nuevo objeto Document con su elemento documento. si el NamespaceURI, qualifiedName, y doctype son null, el Document devuelto está vacío sin elemento de documento.

Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el nombre cualificado especificado no es un nombre XML de acuerdo con [XML 1.0].

NAMESPACE_ERR: provocada si el qualifiedName está mal hecho, si el qualifiedName tiene un prefijo y el namespaceURI es null, o si el qualifiedName es null y el namespaceURI es diferente de null, o si el qualifiedName tiene un prefijo que es "xml" y el namespaceURI es diferente de "http://www.w3.org/XML/1998/namespace" [Espacios de Nombres XML], o si la implementación DOM no soporta la funcionalidad "XML" pero un URI de espacio de nombre no nulo fue proporcionado, desde espacios de nombres fueron definidos por XML.

WRONG_DOCUMENT_ERR: provocada si doctype ha sido utilizado ya con un documento diferente o fue creado de una implementación diferente.

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto por el documento no soporta Espacios de Nombres XML (tal como [HTML 4.01]).

createDocumentType introducido en DOM Nivel 2
Crea un nodo DocumentType vacío. Las declaraciones de entidad y las notaciones no están disponibles. Las extensiones de entidades de referencia y los atributos adicionales predefinidos no ocurren.
Parámetros
qualifiedName of type DOMString
El nombre cualificado del tipo de documento que será creado.
publicId of type DOMString
El identificador público del subconjunto externo.
systemId of type DOMString
El identificador de sistema del subconjunto externo.
Valor Devuelto

DocumentType

Un nuevo nodo DocumentType con Node.ownerDocument se fija a null.

Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el nombre cualificado especificado no es un nombre XML de acuerdo con [XML 1.0].

NAMESPACE_ERR: provocada si qualifiedName está mal formado.

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML y el lenguaje expuesto por el documento no soporta Espacios de Nombres de XML (como [HTML 4.01]).

getFeature introducido en DOM Nivel 3
Este método devuelve un objeto especializado que implementa las APIs especializadas de la funcionalidad y version especificada, como se especifica en Funcionalidades del DOM. El objeto especializado puede también se obtenido utilizando el método de conversión especifico de enlazado pero no es necesariamente esperado, como se comenta en implementaciones Mixtas del DOM. Este método también permite a la implementación proporcionar objetos especializados que no soporte la interfaz DOMImplementation.
Parámetros
feature of type DOMString
El nombre de la funcionalidad requerida. Observe que un signo más "+" precediendo el nombre de la funcionalidad será ignorado ya que no es significativo en el contexto de este método.
version of type DOMString
Este es el número de versión de la funcionalidad a comprobar.
Valor Devuelto

DOMObject

Devuelve un objeto que implementa las APIs especializadas de la funcionalidad y versión especificadas, si lo hay, o null si no hay objeto que implementa las interfaces asociadas con la implementación. Si el DOMObject devuelto por este método implementa la interfaz DOMImplementation, este debe delegar al núcleo primario DOMImplementation y no devolver resultados inconsistentes con el núcleo primario DOMImplementation como con hasFeature, getFeature, etc.

Sin Excepciones
hasFeature
Comprueba si la implementación DOM implementa una funcionalidad y versión especifica, como se establece en Funcionalidades del DOM.
Parámetros
feature of type DOMString
El nombre de la funcionalidad a comprobar.
version of type DOMString
Este es el número de versión de la funcionalidad a comprobar.
Valor Devuelto

boolean

true si la funcionalidad es implementada en la versión especificada, false en caso contrario.

Sin Excepciones

interfaz DocumentFragment

DocumentFragment es un objeto Document "aligerado" o "mínimo". Es muy común querer extraer una porción del árbol de un documento o crear un nuevo fragmento de un documento. Imaginemos la implementación de un comando de usuario como cortar o reordenar un documento moviendo fragmentos. Es deseable tener un objeto que pueda contener dichos fragmentos y resulta bastante natural utilizar para este fin un Nodo. Si bien es cierto que un objeto Document podría realizar este papel, un objeto Document pude ser potencialmente un objeto pesado, dependiendo de la implementación subyacente. Lo que en realidad se necesita para esto es un objeto muy ligero. DocumentFragment es este objeto.

Además, ciertas operaciones -- tales como insertar nodos como hijos de otro Node -- pueden tomar objetos DocumentFragment como argumentos; esto hace que todos los nodos hijo del DocumentFragment sean movidos a la lista de hijos de este nodo.

Los hijos de un nodo DocumentFragment son cero o más nodos que representan las partes superiores de un número de sub-árboles que definen la estructura del documento. Los nodos DocumentFragment no necesitan ser documentos XML bien formados (aunque necesitan seguir las reglas impuestas sobre entidades analizadas XML bien formadas, las cuales pueden tener múltiples nodos superiores). Por ejemplo, un DocumentFragment podría tener un único hijo y ese nodo hijo podrí ser un nodo Text. Este modelo de estructura no representaría ni a un documento HTML ni a un documento XML bien formado.

Cuando un DocumentFragment es insertado dentro de un Document (o en cualquier otro Node que pueda tener hijos) los hijos del DocumentFragment y no el DocumentFragment son insertados en el Node. Esto hace que DocumentFragment sea muy útil cuando el usuario quiere crear nodos que sean hermanos; el DocumentFragment actúa como el padre de estos nodos de modo tal que el usuario puede usar los métodos estándar de la interfaz Node, como por ejemplo Node.insertBefore ("insertar Antes") y Node.appendChild ("insertar Hijo").


Definición IDL
interfaz DocumentFragment : Node {
};

Interfaz Document

La interfaz Document representa el documento HTML o XML completo. Conceptualmente, es la raíz del árbol del documento, y proporciona el acceso primario a los datos del documento.

Como los elementos, nodos de texto, comentarios, instrucciones de procesamiento, etc., no pueden existir fuera del contexto de un Document, la interfaz Document también contiene los métodos constructores necesarios para crear estos objetos. Los objetos Node creados tienen un atributo ownerDocument que los asocia con el Document dentro de cuyo contexto fueron creados.


Definición IDL
interfaz Document : Node {
  // Modificado en DOM Nivel 3:
  readonly attribute DocumentType    doctype;
  readonly attribute DOMImplementation implementation;
  readonly attribute Element         documentElement;
  Element            createElement(in DOMString tagName)
                                        raises(DOMException);
  DocumentFragment   createDocumentFragment();
  Text               createTextNode(in DOMString data);
  Comment            createComment(in DOMString data);
  CDATASection       createCDATASection(in DOMString data)
                                        raises(DOMException);
  ProcessingInstruction createProcessingInstruction(in DOMString target, 
                                                    in DOMString data)
                                        raises(DOMException);
  Attr               createAttribute(in DOMString name)
                                        raises(DOMException);
  EntityReference    createEntityReference(in DOMString name)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString tagname);
  // Introducido en DOM Nivel 2:
  Node               importNode(in Node importedNode, 
                                in boolean deep)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  Element            createElementNS(in DOMString namespaceURI, 
                                     in DOMString qualifiedName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  Attr               createAttributeNS(in DOMString namespaceURI, 
                                       in DOMString qualifiedName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI, 
                                            in DOMString localName);
  // Introducido en DOM Nivel 2:
  Element            getElementById(in DOMString elementId);
  // Introducido en DOM Nivel 3:
  readonly attribute DOMString       inputEncoding;
  // Introducido en DOM Nivel 3:
  readonly attribute DOMString       xmlEncoding;
  // Introducido en DOM Nivel 3:
           attribute boolean         xmlStandalone;
                                        // raises(DOMException) on setting

  // Introducido en DOM Nivel 3:
           attribute DOMString       xmlVersion;
                                        // raises(DOMException) on setting

  // Introducido en DOM Nivel 3:
           attribute boolean         strictErrorChecking;
  // Introducido en DOM Nivel 3:
           attribute DOMString       documentURI;
  // Introducido en DOM Nivel 3:
  Node               adoptNode(in Node source)
                                        raises(DOMException);
  // Introducido en DOM Nivel 3:
  readonly attribute DOMConfiguration domConfig;
  // Introducido en DOM Nivel 3:
  void               normalizeDocument();
  // Introducido en DOM Nivel 3:
  Node               renameNode(in Node n, 
                                in DOMString namespaceURI, 
                                in DOMString qualifiedName)
                                        raises(DOMException);
};

Atributos
doctype of type DocumentType, readonly, modificado en DOM Nivel 3
La Declaración del Tipo de Documento (ver DocumentType) asociada con este documento. Para documentos XML sin una declaración del tipo de documento esto devuelve null. Para documentos HTML, un objeto DocumentType puede ser devuelto, independientemente de la presencia o ausencia de la declaración del tipo de documento en el documento HTML.
Esto proporciona acceso directo al nodo DocumentType, al nodo hijo de este Document. Este nodo puede ser fijado al tiempo que se crea el documento y cambiado posteriormente usando métodos de manipulación de nodos hijos, tales como Node.insertBefore, o Node.replaceChild. Observe, sin embargo, que mientras unas implementaciones pueden instanciar diferentes tipos de objeto Document soportando funcionalidades adicionales que las del "Núcleo", como "HTML" [DOM Level 2 HTML], basado en el DocumentType especificado en tiempo de creación, cambiándolo después es muy improbable que resulte en el cambio una funcionalidad soportada.
documentElement of type Element, readonly
Este es un atributo de conveniencia que permite acceder directamente al nodo hijo que es el elemento raíz del documento.
documentURI of type DOMString, introducido en DOM Nivel 3
La localización del documento o null si es indefinido o si el Document fue creado utilizando DOMImplementation.createDocument. No se realiza ninguna comprobación léxica cuando se fija este atributo; esto podría terminar en un valor null devuelto cuando se utiliza Node.baseURI.
Tenga cuidado cuando Document soporta la funcionalidad "HTML" [DOM Level 2 HTML], el atributo href del elemento BASE HTML toma precedencia sobre este atributo cuando se procesa Node.baseURI.
domConfig of type DOMConfiguration, readonly, introducido en DOM Nivel 3
La configuración utilizada cuando Document.normalizeDocument() es invocado.
implementation of type DOMImplementation, readonly
El objeto DOMImplementation que maneja este documento. Una aplicación DOM puede usar objetos de múltiples implementaciones.
inputEncoding of type DOMString, readonly, introducido en DOM Nivel 3
Un atributo que especifica la codificación usada para este documento en el momento de análisis. Este es null cuando no es conocido, como cuando Document fue creado en memoria.
strictErrorChecking of type boolean, introducido en DOM Nivel 3
Un atributo que especifica si la comprobación de errores se cumple o no. Cuando se fija a false, la implementación es libre de no comprobar cada caso posible definido normalmente sobre operaciones DOM, y no muestra ningún DOMException sobre operaciones DOM o reporta errores mientas se utiliza Document.normalizeDocument(). En caso de error, el comportamiento es indefinido. Este atributo es true por defecto.
xmlEncoding of type DOMString, readonly, introducido en DOM Nivel 3
Un atributo que especifica, como parte de la declaración XML, la codificación de este documento. Este es null cuando no se especifica o cuando no es conocido, como cuando el Document fue creado en memoria.
xmlStandalone of type boolean, introducido en DOM Nivel 3
Un atributo que especifica, como parte de la declaración XML, si este documento es independiente. Este es false cuando no se especifica.

Nota: La verificación no se realiza sobre el valor cuando se fijan estos atributos. Las aplicaciones deberían usar Document.normalizeDocument() con la "validación" de parámetros para verificar si el conjunto de valores obliga la validación para una declaración de documento independiente como se define en [XML 1.0].

Excepciones sobre lo establecido

DOMException

NOT_SUPPORTED_ERR: provocada si este documento no soporta la funcionalidad "XML".

xmlVersion of type DOMString, introducido en DOM Nivel 3
Un atributo que especifica, como parte de la declaración XML, el número de versión de este documento. Si no hay declaración y si este documento soporta funcionalidades "XML", el valor es "1.0". Si este documento no soporta funcionalidades "XML", el valor siempre es null. Cambiando este atributo se afectará a los métodos de comprobación para caracteres no válidos en nombres XML. La aplicación deberá invocar Document.normalizeDocument() para comprobar los caracteres no válidos en los Nodes que ya son parte de este Document.
Las aplicaciones DOM pueden usar el método DOMImplementation.hasFeature(funcionalidad, versión) con valores de parámetro "XMLVersion" y "1.0" (respectivamente) para determinar si una implementación soporta [XML 1.0]. Las aplicaciones DOM pueden usar el mismo método con valores de parámetro "XMLVersion" y "1.1" (respectivamente) para determinar si una aplicación soporta [XML 1.1]. En ambos casos, en orden para soportar XML, una implementación debe también soporta la funcionalidad "XML" definida en esta especificación. Los objetos Document que soportan una versión de la funcionalidad "XMLVersion" no deben mostrar una excepción NOT_SUPPORTED_ERR para el mismo número de versión cuando se utiliza Document.xmlVersion.
Excepciones sobre lo establecido

DOMException

NOT_SUPPORTED_ERR: provocada si la versión es fijada como un valor que no es soportado por este Document o si este documento no soporta funcionalidades "XML".

Métodos
adoptNode introducido en DOM Nivel 3
Intento de adoptar un nodo de otro documento al documento actual. Si es soportado, cambia el ownerDocument (propietario del documento) del nodo fuente, sus hijos, así como los atributos agregados al nodo si los hay. Si el nodo fuente tiene un padre, este es quitado primero de la lista hija del padre. Esto efectivamente permite mover un subárbol de un documento a otro (a diferencia de importNode() que crea una copia del nodo fuente en vez de moverlo). Cuando esto falla, las aplicaciones deberían usar Document.importNode() en su lugar. Observe que si el nodo adoptado es ya parte de este documento (es decir, el documento fuente y objetivo es el mismo), este método todavía tiene el efecto de quitar el nodo fuente de la lista hija de su padre, si lo hay. La siguiente lista describe los datos concretos para cada tipo de nodo.
ATTRIBUTE_NODE
El atributo ownerElement se fija a null y el flag (bandera) especificada es fijada a true en el Attr adoptado. El descendente del Attr fuente son adoptados recursivamente.
DOCUMENT_FRAGMENT_NODE
Los descendentes del nodo fuente son adoptados recursivamente.
DOCUMENT_NODE
Los nodos del Document no pueden ser adoptados.
DOCUMENT_TYPE_NODE
Los nodos DocumentType no pueden ser adoptados.
ELEMENT_NODE
Los atributos Especificados de nodos de un elemento fuente son adoptados. Los atributos predeterminados son descartados, aunque si el documento que está siendo adoptado define atributos por defecto (predeterminados) para ese nombre de elemento, estos son asignados. Los descendentes del elemento fuente son adoptados recursivamente.
ENTITY_NODE
Los nodos Entity no pueden ser adoptados.
ENTITY_REFERENCE_NODE
Solamente el nodo EntityReference es adoptado por si mismo, los descendentes son descartados, así que los documentos fuente y destino podían haber definido la entidad de manera diferente. Si el documento está siendo importado dentro de una definición proporcionada para este nombre de entidad, su valor es asignado.
NOTATION_NODE
Los nodos Notation no pueden ser adoptados.
PROCESSING_INSTRUCTION_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
Todos estos nodos pueden ser adoptados. Ninguna especificación.

Nota: Ya que esto no crea nodos nuevos a diferencia del método Document.importNode(), este método no muestra una excepción INVALID_CHARACTER_ERR, y la aplicación deberá utilizar el método Document.normalizeDocument() para comprobar si un nombre importado no es un nombre XML de acuerdo a la versión XML en uso.

Parámetros
source of type Node
El nodo a mover en este documento.
Valor Devuelto

Node

El nodo adoptado, o null si esta operación falla, igual que cuando el nodo fuente viene de una implementación diferente.

Excepciones

DOMException

NOT_SUPPORTED_ERR: provocada si el nodo fuente es del tipo DOCUMENT, DOCUMENT_TYPE.

NO_MODIFICATION_ALLOWED_ERR: provocada si el nodo fuente es de solo lectura.

createAttribute
Crea un Attr con el nombre dado. Observe que la instancia Attr puede ser fijada sobre un Element utilizando el método setAttributeNode.
Para crear un atributo con un nombre cualificado y URI de espacio de nombre, use el método createAttributeNS.
Parámetros
name of type DOMString
El nombre del atributo.
Valor Devuelto

Attr

Un nuevo objeto Attr con el atributo nodeName fijado a name, y localName, prefix, y namespaceURI fijados a null. El valor del atributo es un cadena vacía.

Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el nombre especificado no es un nombre XML de acuerdo a la versión en uso XML especificada en el atributo Document.xmlVersion.

createAttributeNS introducido en DOM Level 2
Crea un atributo del nombre cualificado y URI de espacio de nombre dado.
Por [XML Namespaces], las aplicaciones deben utilizar valor null como el parámetro namespaceURI para métodos en los que desean no tener espacio de nombre (namespace).
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del atributo a crear.
qualifiedName of type DOMString
El nombre cualificado del atributo a crear.
Valor Devuelto

Attr

Un nuevo objeto Attr con los siguientes atributos:

AtributoValor
Node.nodeName Nombre cualificado
Node.namespaceURI URI de espacio de nombre
Node.prefix prefijo, extraído de qualifiedName, o null si no hay prefijo
Node.localName nombre local, extraído de qualifiedName
Attr.name Nombre cualificado
Node.nodeValue la cadena vacía
Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el qualifiedName especificado no es un nombre XML conforme a la versión XML en uso especificada en el atributo Document.xmlVersion.

NAMESPACE_ERR: provocada si el qualifiedName es un nombre cualificado mal formado, si el qualifiedName tiene un prefijo y el namespaceURI es null, si el qualifiedName tiene un prefijo que es "xml" y el namespaceURI es diferente de "http://www.w3.org/XML/1998/namespace", si el qualifiedName o su prefijo es "xmlns" y el namespaceURI es diferente de "http://www.w3.org/2000/xmlns/", o si el namespaceURI es "http://www.w3.org/2000/xmlns/" y ningún qualifiedName ni su prefijo es "xmlns".

NOT_SUPPORTED_ERR: Provocado siempre que el documento actual no soporte la funcionalidad "XML", ya que los espacios de nombre eran definidos por XML.

createCDATASection
Crea un nodo CDATASection cuyo valor es la cadena especificada.
Parámetros
data of type DOMString
Los datos para el contenido CDATASection.
Valor Devuelto

CDATASection

El nuevo objeto CDATASection.

Excepciones

DOMException

NOT_SUPPORTED_ERR: provocada si este documento es un documento HTML.

createComment
Crea un nodo Comment considerando la cadena dada.
Parámetros
data of type DOMString
Los datos para el nodo.
Valor Devuelto

Comment

El nuevo objeto Comment.

Sin Excepciones
createDocumentFragment
Crea un objeto vacío DocumentFragment.
Valor Devuelto
Sin Parámetros
Sin Excepciones
createElement
Crea un elemento del tipo especificado. observe que la instancia devuelta implementa la interfaz Element, así los atributos pueden ser especificados directamente sobre el objeto devuelto.
Además, si hay atributos conocidos con valores por defecto, los nodos Attr que los representan son creados automáticamente y fijados al elemento.
Para crear un elemento con un nombre cualificado y URI de espacio de nombre, utilice el método createElementNS.
Parámetros
tagName of type DOMString
El nombre del tipo de elemento a instanciar. Para XML, este es sensible a mayúsculas y minúsculas, sino depende de la sensibilidad a mayúsculas y minúsculas del lenguaje de marcas en uso. En este caso, la implementación DOM debe transformar el nombre a la forma canónica de esa etiqueta.
Valor Devuelto

Element

Un nuevo objeto Element con el atributo nodeName fijado a tagName, y localName, prefix, y namespaceURI fijados a null.

Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el nombre especificado no es un nombre XML conforme a la versión de XML en uso especificada en el atributo Document.xmlVersion.

createElementNS introducido en DOM Level 2
Crea un elemento con nombre cualificado y URI de espacios de nombres dados.
Para [Espacios de nombres XML], las aplicaciones deben utilizar el valor null como el parámetro de URI de espacios de nombre (namespaceURI) para los métodos que deseen no tener espacios de nombres.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del elemento creado.
qualifiedName of type DOMString
El nombre cualificado del tipo de elemento a instanciar.
Valor Devuelto

Element

Un nuevo objeto Element con los siguientes atributos:

AtributoValor
Node.nodeName qualifiedName
Node.namespaceURI namespaceURI
Node.prefix prefijo, extraído de qualifiedName, o null si no hay prefijo
Node.localName nombre local, extraído de qualifiedName
Element.tagName qualifiedName
Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el qualifiedName especificado no es un nombre XML de acuerdo a la versión XML en uso especificada en el atributo Document.xmlVersion.

NAMESPACE_ERR: provocada si el qualifiedName es un nombre cualificado mal construido, si el qualifiedName tiene un prefijo y el namespaceURI es null, o si el qualifiedName tiene un prefijo que es "xml" y el namespaceURI es diferente de "http://www.w3.org/XML/1998/namespace" [XML Namespaces], o si el qualifiedName o su prefijo es "xmlns" y el namespaceURI es diferente de "http://www.w3.org/2000/xmlns/", o si el namespaceURI es "http://www.w3.org/2000/xmlns/" y ningún qualifiedName ni su prefijo es "xmlns".

NOT_SUPPORTED_ERR: Provocada siempre que el documento actual no soporte funcionalidades "XML", ya que los espacios de nombres eran definidos por XML.

createEntityReference
Crea un objeto EntityReference. Además, si la entidad referenciada es conocida, la lista de hijos del nodo EntityReference es la misma que la del nodo Entity correspondiente.

Nota: Si cualquier descendente del nodo Entity tiene un prefijo de espacio de nombre suelto, el descendente correspondiente del nodo EntityReference creado también está suelto; (Su namespaceURI es null). El DOM Nivel 2 y 3 no soportan ningún mecanismo que resuelva los prefijos de espacios de nombre en este caso.

Parámetros
name of type DOMString
El nombre para referirse a la entidad.
A diferencia de Document.createElementNS o Document.createAttributeNS, ninguna comprobación de formato de espacio de nombre es realizada sobre el nombre de la entidad. Las aplicaciones deberían invocar Document.normalizeDocument() con el parámetro "namespaces" establecido a true para asegurar que el nombre de la entidad es un espacio de nombre bien formado.
Valor Devuelto

EntityReference

El nuevo objeto EntityReference.

Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el nombre especificado no es un nombre XML conforme a la versión XML en uso especificada en el atributo Document.xmlVersion.

NOT_SUPPORTED_ERR: provocada si este documento es un documento HTML.

createProcessingInstruction
Crea un nodo ProcessingInstruction dando el nombre especificado y la cadena de datos.
Parámetros
target of type DOMString
La parte objetiva de la instrucción de tratamiento.
A diferencia de Document.createElementNS o Document.createAttributeNS, ninguna comprobación de formato de espacio de nombre es realizada sobre el nombre objetivo. Las aplicaciones deberían invocar Document.normalizeDocument() con el parámetro "namespaces" establecido a true para asegurar que el nombre objetivo es un espacio de nombre de formato correcto.
data of type DOMString
Los datos para el nodo.
Valor Devuelto
Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el objetivo especificado no es un nombre XML conforme a la versión XML en uso especificada en el atributo Document.xmlVersion

NOT_SUPPORTED_ERR: provocada si este documento es un documento HTML.

createTextNode
Crea un nodo Text dado la cadena especificada.
Parámetros
data of type DOMString
Los datos para el nodo.
Valor Devuelto

Text

El nuevo objeto Text.

Sin Excepciones
getElementById introducido en DOM Level 2
Devuelve el Element que tiene un atributo ID con el valor dado. Si no existe dicho elemento, este devuelve null. Si más de un elemento tiene un atributo ID con ese valor, se devuelve indefinido.
Se espera que la implementación DOM utilice el atributo Attr.isId para determinar si un atributo es del tipo ID.

Nota: Los atributos con el nombre "ID" o "id" no son del tipo ID a menos que así sea definido.

Parámetros
elementId of type DOMString
El valor id único para un elemento.
Valor Devuelto

Element

El elemento indicado o null si no hay ninguno.

Sin Excepciones
getElementsByTagName
Devuelve un NodeList de todos los Elements en el orden del documento con un nombre de etiqueta dado y que están contenidos en el documento.
Parámetros
tagname of type DOMString
El nombre de la etiqueta deseada. El valor especial "*" engloba todas las etiquetas. Para XML, el parámetro tagname es sensible a mayúsculas y minúsculas, sino depende de la sensibilidad a mayúsculas y minúsculas del lenguaje de etiquetas en uso.
Valor Devuelto

NodeList

Un nuevo objeto NodeList conteniendo todos los Elements indicados.

Sin Excepciones
getElementsByTagNameNS introducido en DOM Level 2
Devuelve un NodeList de todos los Elements con un nombre local y URI de espacio de nombre dado dentro del orden del documento.
Parámetros
namespaceURI of type DOMString
El URI de espacios de nombre de los elementos elegidos. El valor especial "*" abarca todos los espacios de nombres.
localName of type DOMString
El nombre local de los elementos elegidos. El valor especial "*" engloba todos los nombres locales.
Valor Devuelto

NodeList

Un nuevo objeto NodeList conteniendo todos los Elements referenciados.

Sin Excepciones
importNode introducido en DOM Level 2
Importa el nodo de otro documento a este documento, sin cambiar o eliminar el nodo fuente del documento original; este método crea una nueva copia del nodo fuente. El nodo devuelto no tiene padre; (parentNode es null).
Para todos los nodos, la importación de un nodo crea un objeto nodo propio por la importación del documento, con el un valor de atributo idéntico al nodeName y nodeType del nodo fuente, más los atributos relacionados con los espacios de nombres (prefix, localName, y namespaceURI). Como en la operación cloneNode, el nodo fuente no es alterado. Los datos asociados al nodo importado no son transferidos. Sin embargo, si algún UserDataHandlers ha sido especificado con el dato asociado dicha manipulación será llamada con el parámetro apropiado antes de que este método lo devuelva.
La información adicional es copiada conforme al nodeType (tipo de nodo), intentando reflejar el comportamiento esperado si un fragmento de código fuente de XML o HTML fuese copiado de un documento a otro, reconociendo que los dos documentos pueden tener diferentes DTDs en el caso de XML. La siguiente lista describe los datos concretos para cada tipo de nodo.
ATTRIBUTE_NODE
El atributo ownerElement es fijado a null y el bandera (flag) especificada es fijada a true en el Attr generado. Los descendentes del Attr fuente son importados recursivamente y los nodos resultantes reensamblados para formar el sub-árbol correspondiente.
Observe que el parámetro deep no tiene efectos sobre los nodos Attr; ellos siempre llevan a sus hijos cuando son importados.
DOCUMENT_FRAGMENT_NODE
Si la opción deep fue establecida a true, los descendentes del DocumentFragment fuente son recurrentemente importados y los nodos resultantes reensamblados bajo DocumentFragment importado para formar el sub-árbol correspondiente. Si no, esto simplemente genera un DocumentFragment vacío.
DOCUMENT_NODE
Los nodos Document no pueden ser importados.
DOCUMENT_TYPE_NODE
Los nodos DocumentType no pueden ser importados.
ELEMENT_NODE
Los nodos del atributo Especificado del elemento fuente son importados, y los nodos Attr generados son adjuntados al Element generado. Los atributos predeterminados no son copiados, aunque si el documento que está siendo importado define atributos predeterminados para este nombre de elemento, esos son asignados. Si el parámetro importNode deep fue fijado a true, los descendentes del elemento fuente son importados recursivamente y los nodos resultantes reensamblados para formar el sub-árbol correspondiente.
ENTITY_NODE
Los nodos Entity pueden ser importados, sin embargo en la liberación actual del DOM el DocumentType es de solo lectura. La capacidad para añadir estos nodos importados a un DocumentType. Será considerado para añadirlo a una futura liberación del DOM.
En la importación, los atributos publicId, systemId, y notationName son copiados. Si una importación deep es requerida, los descendentes del Entity fuente son importados recursivamente y los nodos resultantes reensamblados para formar el correspondiente sub-árbol.
ENTITY_REFERENCE_NODE
Solo el propio EntityReference es copiado, incluso si una importación deep es requerida, desde los documentos fuente y destino podrían tener definidos identidad diferente. Si el documento que está siendo importado proporciona una definición para este nombre de entidad, su valor se asigna.
NOTATION_NODE
Los nodos Notation pueden ser importados, sin embargo en la liberación actual del DOM el DocumentType es de solo lectura. La capacidad añadir estos nodos importados a un DocumentType será considerada para añadirlo en una futura liberación del DOM.
En la importación, los atributos publicId y systemId son copiados.
Observe que el parámetro deep no tiene efecto sobre este tipo de nodos ya que no pueden tener ningún hijo.
PROCESSING_INSTRUCTION_NODE
El nodo importado copia sus propios valores target y data de esos nodos fuente.
Observe que el parámetro deep no tiene efecto sobre este tipo de nodos ya que estos no pueden tener ningún hijo.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
Estos tres tipos de nodos heredan de la copia de CharacterData sus atributos data y length del nodo fuente.
Observe que el parámetro deep no tiene efecto sobre estos tipos de nodos ya que no pueden tener ningún hijo.
Parámetros
importedNode of type Node
El nodo a importar.
deep of type boolean
Si es true, se importa recursivamente el sub-árbol bajo el nodo especificado; si es false, solo se importa el nodo, como se explicó arriba. Esto no tiene efecto sobre el nodo que no puede tener ningún hijo, y sobre los nodos Attr, y EntityReference.
Valor Devuelto

Node

El nodo importado que pertenece a este Document.

Excepciones

DOMException

NOT_SUPPORTED_ERR: provocada si el tipo de nodo que está siendo importado no es soportado.

INVALID_CHARACTER_ERR: provocada si uno de los nombres importados no es un nombre XML conforme a la versión XML especificada en uso en el atributo Document.xmlVersion. Esto puede ocurrir, por ejemplo, cuando se importa un elemento XML 1.1 [XML 1.1] dentro de un documento XML 1.0.

normalizeDocument introducido en DOM Nivel 3
Este método actúa como si el documento fuese a través del ciclo de grabar y cargar, poniendo el documento en una forma "normal". Como consecuencia, este método actualiza el árbol reemplazado de los nodos normalizados EntityReference y Text, como se define en el método Node.normalize().
Si no, el resultado actual depende de las carácterísticas fijadas en el objeto Document.domConfig y gobernando que operaciones realmente ocurren. Perceptiblemente este método podría hacer también el documento de espacio de nombre bien formado de acuerdo al algoritmo descrito en Normalización de Espacio de Nombre, comprueba el carácter de normalización, quita los nodos CDATASection, etc. Vea DOMConfiguración para más detalles.
// Mantiene en el documento la información definida
// en el Conjunto de Información de XML (Java por ejemplo)
DOMConfiguration docConfig = myDocument.getDomConfig();
docConfig.setParameter("infoset", Boolean.TRUE);
myDocument.normalizeDocument();

Los eventos de mutación, cuando son soportados, son generados para reflejar los cambios ocurridos en el documento.
Si ocurren errores durante la invocación de este método, como intentar actualizar un nodo de solo lectura o un Node.nodeName que contiene caracteres no válidos de acuerdo con la versión de XML en uso, errores o advertencias (DOMError.SEVERITY_ERROR o DOMError.SEVERITY_WARNING) serán reportadas utilizando el objeto DOMErrorHandler asociado con el parámetro "error-handler". Observe que este método también podría reportar errores graves (DOMError.SEVERITY_FATAL_ERROR) si una implementación no puede reponerse de un error.

Sin Parámetros
Sin Valores Devueltos
Sin Excepciones
renameNode introducido en DOM Nivel 3
Renombra un nodo existente del tipo ELEMENT_NODE o ATTRIBUTE_NODE.
Cuando es posible esto simplemente cambia el nombre de un nodo dado, sino esto crea un nuevo nodo con el nombre especificado y reemplaza el nodo existente por el nuevo nodo como se describe a continuación.
Si no es posible el simple cambio del nombre de un nodo dado, las siguientes operaciones son realizadas: un nuevo nodo es creado, cualquier evento registrado a la escucha es registrado en el nuevo nodo que es creado, cualquier dato del usuario adjuntado al viejo nodo es quitado de ese nodo, el viejo nodo es quitado de su padre si tuviera uno, los hijos son movidos al nuevo nodo, si el nodo renombrado es un Element sus atributos son movidos al nuevo nodo, el nuevo nodo es insertado en la posición del viejo nodo usado teniendo la lista de los nodos hijos de su padre si lo tuviera, los datos del usuario que son adjuntados al nodo viejo son adjuntados al nuevo nodo.
Cuando el nodo que está siendo renombrado es un Element solo los atributos especificados son movidos, los atributos por defectos originados por el DTD son actualizados de acuerdo al nuevo nombre del elemento. Además, la implementación puede actualizar los atributos predeterminados de otros esquemas. Las aplicaciones pueden usar Document.normalizeDocument() para garantizar que estos atributos son actualizados.
Cuando el nodo que está siendo renombrado es un Attr que esta asociado (atado) a un Element, el nodo primero es eliminado del mapa de atributos de Element. Entonces, una vez renombrado, bien por modificación del nodo existente o por creación de uno nuevo como se describió arriba, se vuelve a poner.
Además,
  • Un evento de dato de usuario NODE_RENAMED es lanzado,
  • Cuando la implementación soporte la funcionalidad "MutationNameEvents", cada operación de mutación en vuelta en este método lanza el evento apropiado, y al final del evento {http://www.w3.org/2001/xml-events, DOMElementNameChanged} o {http://www.w3.org/2001/xml-events, DOMAttributeNameChanged} es lanzado.
Parámetros
n of type Node
El nodo a renombrar.
namespaceURI of type DOMString
El nuevo URI de espacio de nombre.
qualifiedName of type DOMString
El nuevo nombre cualificado.
Valor Devuelto

Node

El nodo renombrado. Este es el nodo especificado o el nuevo nodo que fue creado para reemplazar el nodo especificado.

Excepciones

DOMException

NOT_SUPPORTED_ERR: provocada cuando el tipo de nodo especificado no es ni ELEMENT_NODE ni ATTRIBUTE_NODE, o si la implementación no soporta renombrar document element.

INVALID_CHARACTER_ERR: provocada si el nuevo nombre cualificado (correcto) no es un nombre XML de acuerdo con la versión XML en uso especificada en el atributo Document.xmlVersion.

WRONG_DOCUMENT_ERR: provocada cuando el nodo especificado fue creado de un documento diferente al actual.

NAMESPACE_ERR: provocada si el qualifiedName es un nombre cualificado mal formado, si el qualifiedName tiene un prefijo y un namespaceURI null, o si el qualifiedName tiene un prefijo que es "xml" y el namespaceURI es diferente de "http://www.w3.org/XML/1998/namespace" [XML Namespaces]. También será provocada, cuando el nodo que está siendo renombrado es un atributo, si el qualifiedName, o su prefijo, es "xmlns" y el namespaceURI es diferente de "http://www.w3.org/2000/xmlns/".

Interfaz Node

La interfaz Node es el tipo de dato primario para la integridad del Modelo de Objetos del Documento. Representa un nodo individual del árbol del documento. Mientras que todos los objetos que implementan la interfaz Node exponen métodos para tratar con hijos, no todos los objetos que implementan la interfaz Node pueden tener hijos. Por ejemplo, los nodos Text no pueden tener hijos, y al añadir hijos a tales nodos provoca una excepción DOMException.

Los atributos nodeName, nodeValue y attributes se han incluido como un mecanismo para obtener información del nodo sin destruir la interfaz específica derivada. En los casos donde no hay un mapa obvio de estos atributos para un nodeType específico (Por Ejemplo, nodeValue para un Element o attributes para un Comment), esto devuelve null. Observe que las interfaces especializadas pueden contener mecanismos adicionales y convenientes para obtener y establecer la información relevante.


Definición IDL
interfaz Node {

  // NodeType
  const unsigned short      ELEMENT_NODE                   = 1;
  const unsigned short      ATTRIBUTE_NODE                 = 2;
  const unsigned short      TEXT_NODE                      = 3;
  const unsigned short      CDATA_SECTION_NODE             = 4;
  const unsigned short      ENTITY_REFERENCE_NODE          = 5;
  const unsigned short      ENTITY_NODE                    = 6;
  const unsigned short      PROCESSING_INSTRUCTION_NODE    = 7;
  const unsigned short      COMMENT_NODE                   = 8;
  const unsigned short      DOCUMENT_NODE                  = 9;
  const unsigned short      DOCUMENT_TYPE_NODE             = 10;
  const unsigned short      DOCUMENT_FRAGMENT_NODE         = 11;
  const unsigned short      NOTATION_NODE                  = 12;

  readonly attribute DOMString       nodeName;
           attribute DOMString       nodeValue;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  readonly attribute unsigned short  nodeType;
  readonly attribute Node            parentNode;
  readonly attribute NodeList        childNodes;
  readonly attribute Node            firstChild;
  readonly attribute Node            lastChild;
  readonly attribute Node            previousSibling;
  readonly attribute Node            nextSibling;
  readonly attribute NamedNodeMap    attributes;
  // Modificado en DOM Nivel 2:
  readonly attribute Document        ownerDocument;
  // Modificado en DOM Nivel 3:
  Node               insertBefore(in Node newChild, 
                                  in Node refChild)
                                        raises(DOMException);
  // Modificado en DOM Nivel 3:
  Node               replaceChild(in Node newChild, 
                                  in Node oldChild)
                                        raises(DOMException);
  // Modificado en DOM Nivel 3:
  Node               removeChild(in Node oldChild)
                                        raises(DOMException);
  // Modificado en DOM Nivel 3:
  Node               appendChild(in Node newChild)
                                        raises(DOMException);
  boolean            hasChildNodes();
  Node               cloneNode(in boolean deep);
  // Modificado en DOM Nivel 3:
  void               normalize();
  // Introducido en DOM Nivel 2:
  boolean            isSupported(in DOMString feature, 
                                 in DOMString version);
  // Introducido en DOM Nivel 2:
  readonly attribute DOMString       namespaceURI;
  // Introducido en DOM Nivel 2:
           attribute DOMString       prefix;
                                        // raises(DOMException) on setting

  // Introducido en DOM Nivel 2:
  readonly attribute DOMString       localName;
  // Introducido en DOM Nivel 2:
  boolean            hasAttributes();
  // Introducido en DOM Nivel 3:
  readonly attribute DOMString       baseURI;

  // DocumentPosition
  const unsigned short      DOCUMENT_POSITION_DISCONNECTED = 0x01;
  const unsigned short      DOCUMENT_POSITION_PRECEDING    = 0x02;
  const unsigned short      DOCUMENT_POSITION_FOLLOWING    = 0x04;
  const unsigned short      DOCUMENT_POSITION_CONTAINS     = 0x08;
  const unsigned short      DOCUMENT_POSITION_CONTAINED_BY = 0x10;
  const unsigned short      DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;

  // Introducido en DOM Nivel 3:
  unsigned short     compareDocumentPosition(in Node other)
                                        raises(DOMException);
  // Introducido en DOM Nivel 3:
           attribute DOMString       textContent;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  // Introducido en DOM Nivel 3:
  boolean            isSameNode(in Node other);
  // Introducido en DOM Nivel 3:
  DOMString          lookupPrefix(in DOMString namespaceURI);
  // Introducido en DOM Nivel 3:
  boolean            isDefaultNamespace(in DOMString namespaceURI);
  // Introducido en DOM Nivel 3:
  DOMString          lookupNamespaceURI(in DOMString prefix);
  // Introducido en DOM Nivel 3:
  boolean            isEqualNode(in Node arg);
  // Introducido en DOM Nivel 3:
  DOMObject          getFeature(in DOMString feature, 
                                in DOMString version);
  // Introducido en DOM Nivel 3:
  DOMUserData        setUserData(in DOMString key, 
                                 in DOMUserData data, 
                                 in UserDataHandler handler);
  // Introducido en DOM Nivel 3:
  DOMUserData        getUserData(in DOMString key);
};

Grupo de Definiciones NodeType

Un entero indicando que tipo de nodo es este.

Nota: Los códigos numéricos hasta el 200 son reservados por W3C para posibles usos futuros.

Definición de Constantes
ATTRIBUTE_NODE
El nodo es un Attr.
CDATA_SECTION_NODE
El nodo es un CDATASection.
COMMENT_NODE
El nodo es un Comment.
DOCUMENT_FRAGMENT_NODE
El nodo es un DocumentFragment.
DOCUMENT_NODE
El nodo es un Document.
DOCUMENT_TYPE_NODE
El nodo es un DocumentType.
ELEMENT_NODE
El nodo es un Element.
ENTITY_NODE
El nodo es un Entity.
ENTITY_REFERENCE_NODE
El nodo es un EntityReference.
NOTATION_NODE
El nodo es un Notation.
PROCESSING_INSTRUCTION_NODE
El nodo es un ProcessingInstruction.
TEXT_NODE
El nodo es un nodo Text.

Los valores de nodeName, nodeValue, y attributes varían de acuerdo al tipo de nodo como sigue:

Interfaz nodeName nodeValue atributos
Attr Igual que Attr.name, el nombre del atributo Igual que Attr.value, el valor del atributo null
CDATASection "#cdata-section" Igual que CharacterData.data, el contendido de la Sección CDATA null
Comment "#comment" Igual que CharacterData.data, el contenido del comentario null
Document "#document" null null
DocumentFragment "#document-fragment" null null
DocumentType Igual que DocumentType.name, nombre del tipo de documento null null
Element Igual que Element.tagName, nombre de la etiqueta null NamedNodeMap
Entity nombre de la entidad (entity) null null
EntityReference nombre de la entidad referenciada null null
Notation nombre de notación null null
ProcessingInstruction Igual que ProcessingInstruction.target, el destino Igual que ProcessingInstruction.data, el dato null
Text "#text" Igual que CharacterData.data, el contenido del nodo texto null
Grupo de Definición de DocumentPosition

Una mascara de bit (bitmask) indicando la posición relativa en el documento de un nodo con respecto a otro nodo.

Si los dos nodos comparados son el mismo nodo, entonces no se pone ninguna flags en el valor devuelto.

Sino, el orden de los dos nodos es determinado buscando contenedores comunes -- contenedores que contenga a ambos. Un nodo contiene directamente a cualquier nodo hijo. Un nodo también contiene directamente a cualquier otro nodo asociado así como los atributos contenidos en un elemento o entidades y notaciones contenidas en un tipo de documento. Los nodos contenidos en el contenido de un nodo también son contenidos, pero directamente menor al número de aumentos de contenedores que intervienen.

Si no hay nodo contenedor común, entonces el orden es basado en el orden entre el contenedor raíz de cada nodo que no está en ningún contenedor. En este caso, el resultado es deshabilitado e implementado específicamente. Este resultado es estable mientras estos contenidos de nodos exteriores permanecen en la memoria y no son insertados en algún contenido de otro nodo. Este sería el caso cuando los nodos pertenecen a diferentes documentos o fragmentos, y se clona el documento o se inserta un fragmento pudiendo cambiar el orden.

Si uno de los nodos que está siendo comparado contiene otro nodo, entonces el contenedor precede al nodo contenido, e inversamente el nodo contenido sigue al contenedor. Por ejemplo, cuando comparando un elemento con su propio atributo o hijo, el elemento nodo precede a su nodo atributo y a su nodo hijo, y ambos siguen al primero.

Si ninguno de los casos anteriores se aplica, entonces existe un contenedor más directo común para los nodos que son comparados. En este caso, el orden es determinado en base a la determinación de los dos nodos directamente contenidos en este contendor más directo común que es o contiene los correspondientes nodos que están siendo comparados.

Si estos dos nodos determinados son ambos nodos hijos, entonces el orden natural de DOM de estos nodos determinados dentro del nodo que los contiene es devuelto como el orden del los correspondientes nodos. Este podría ser el caso, por ejemplo, cuando comparamos dos elementos hijos de un mismo elemento.

Si uno de los dos nodos determinados es un hijo y el otro no, entonces el nodo correspondiente al nodo hijo sigue al nodo correspondiente del nodo no hijo. Este podría ser el caso, por ejemplo, cuando comparamos un atributo de un elemento con un elemento hijo del mismo elemento.

Si ninguno de los dos nodos determinados es un nodo hijo y un nodo determinado tiene un mayor valor de nodeType que el otro, entonces el nodo correspondiente precede al otro. Este podría ser el caso, por ejemplo, cuando comparamos una entidad de un tipo de documento con una notación de ese mismo tipo de documento.

Si ninguno de los dos nodos determinados son un nodo hijo y el nodeType es el mismo para ambos nodos determinados, entonces el orden devuelto entre los nodos determinados depende de la implementación. Este orden se estable mientras el mismo tipo de nodo (nodeType) no sea insertado dentro o borrado del contenedor directo. Este podría ser el caso, por ejemplo, cuando comparamos dos atributos de un mismo elemento, e insertamos o borramos atributos adicionales que implican cambios de orden entre los atributos existentes.

Definición de Constantes
DOCUMENT_POSITION_CONTAINED_BY
El nodo es contenido por el nodo referenciado. Un nodo que es contenido es también siempre seguido.
DOCUMENT_POSITION_CONTAINS
El nodo contiene el nodo referenciado. Un nodo que contiene es también siempre precedido.
DOCUMENT_POSITION_DISCONNECTED
Los dos nodos son desconectados (deshabilitados). El orden entre los nodos desconectados es siempre especificado por la implementación.
DOCUMENT_POSITION_FOLLOWING
El nodo sigue al nodo referenciado.
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
La determinación del precedente frente al siguiente es específico de la implementación.
DOCUMENT_POSITION_PRECEDING
El segundo nodo precede al nodo referenciado.
Atributos
attributes of type NamedNodeMap, readonly
Un NamedNodeMap contiene los atributos de este nodo (si este es un Element) o null si no.
baseURI of type DOMString, readonly, introducido en DOM Nivel 3
La URI base absoluta de este nodo o null si la implementación no fuera capaz de obtener la URI absoluta. Este valor es procesado como se describe en URIs Base. Sin embargo, cuando Document soporta una carácterística "HTML" [DOM Nivel 2 HTML], la URI base es completada utilizando primero el valor del atributo href del elemento BASE HTML, y el valor del atributo documentURI de la interfaz Document si no.
childNodes of type NodeList, readonly
Un NodeList contiene todos los hijos de este nodo. Si no hay hijos, este NodeList no contiene nodos.
firstChild of type Node, readonly
El primer hijo de este nodo. Si no existe tal nodo, devuelve null.
lastChild of type Node, readonly
El ultimo hijo de este nodo. Si no existe tal nodo, devuelve null.
localName of type DOMString, readonly, introducido en DOM Level 2
Devuelve la parte local del nombre cualificado (qualified name) de este nodo.
Para nodos de algún tipo diferente a ELEMENT_NODE y ATTRIBUTE_NODE y nodos creados con métodos de DOM Nivel 1, tales como Document.createElement(), esto siempre es null.
namespaceURI of type DOMString, readonly, introducido en DOM Level 2
El namespace URI de este nodo, o null si este no está especificado (ver XML Namespaces).
Este no es un valor calculado como resultado de una consulta al espacio de nombre basada sobre un examen de las declaraciones de espacios de nombre al alcance. Simplemente es el URI de espacio de nombres dado en tiempo de creación.
Para nodos de algún tipo diferente de ELEMENT_NODE y ATTRIBUTE_NODE y nodos creados con métodos de DOM Nivel 1, tales como Document.createElement(), esto siempre es null.

Nota: Por la Especificación de Espacios de Nombres en XML [XML Namespaces] un atributo no puede heredar su espacio de nombre (namespace) del elemento al que es adjuntado. Si un atributo no da explícitamente un espacio de nombre, este simplemente no tiene espacio de nombre.

nextSibling of type Node, readonly
El nodo inmediatamente siguiente a este nodo. Si no existe tal nodo, esto devuelve null.
nodeName of type DOMString, readonly
El nombre de este nodo, dependiendo de su tipo; vea la tabla de arriba.
nodeType of type unsigned short, readonly
Un código que representa el tipo de objeto adyacente, como fue definido arriba.
nodeValue of type DOMString
El valor de este nodo, dependiendo de su tipo; vea la tabla de arriba. Cuando este es definido para ser null, los ajustes sobre el no tienen efecto, incluido si el nodo es solo lectura (read-only).
Excepción al establecer

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada cuando el nodo es de solo lectura y si este no es definido para ser null.

Excepciones al leer

DOMException

DOMSTRING_SIZE_ERR: provocada cuando este devolvería más caracteres que los soportados en una variable DOMString sobre la plataforma de la implementación.

ownerDocument of type Document, readonly, modificado en DOM Level 2
El objeto Document asociado con este nodo. Este es también el objeto Document utilizado para crear un nuevo nodo. Cuando este nodo es un Document o un DocumentType que no se utiliza aun con ningún Document, este es null.
parentNode of type Node, readonly
El padre de este nodo. Todos los nodos, excepto Attr, Document, DocumentFragment, Entity, y Notation pueden tener un padre. Sin embargo, si el nodo acaba de ser creado y aun no ha sido añadido al árbol, o si ha sido retirado del árbol, esto es null.
prefix of type DOMString, introducido en DOM Level 2
Los prefijos de espacio de nombre de este nodo, o null si no está especificado. Cuando este es definido para ser null, los ajustes no tienen efectos, incluyendo si el nodo es de solo lectura.
Observe que fijando estos atributos, cuando son permitidos, cambia el atributo nodeName, que sostiene el nombre cualificado (qualified name), así como los atributos tagName y name de las interfaces Element y Attr, cuando es aplicable.
El ajuste del prefijo a null hace a este no especificado, estableciéndolo como una cadena vacía dependiendo de la implementación.
Observe también que el cambio del prefijo de un atributo que es conocido tiene un valor por defecto, no se crea un nuevo atributo con el valor por defecto y aparece el prefijo original, no cambiando el namespaceURI y localName.
Para nodos diferentes de ELEMENT_NODE y ATTRIBUTE_NODE y nodos creados con un método de DOM Level 1, tal como la interfaz createElement del Document, esto es siempre null.
Excepción sobre ajustes

DOMException

INVALID_CHARACTER_ERR: provocada si el prefijo especificado contiene un carácter ilegal de acuerdo con la versión de XML en uso especificado en el atributo Document.xmlVersion.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NAMESPACE_ERR: provocada si el prefijo especificado está mal formado por el Espacio de Nombres en la especificación XML, si el namespaceURI de este nodo es null, si el prefijo especificado es "xml" y el namespaceURI de este nodo es diferente de "http://www.w3.org/XML/1998/namespace", si este nodo es un atributo y el prefijo especificado es "xmlns" y el namespaceURI de este nodo es diferente de "http://www.w3.org/2000/xmlns/", o si este nodo es un atributo y el qualifiedName de este nodo es "xmlns" [XML Namespaces].

previousSibling of type Node, readonly
El nodo inmediatamente precedente a este nodo. Si no existe tal nodo, esto devuelve null.
textContent of type DOMString, introducido en DOM Nivel 3
Este atributo devuelve el contenido de texto de este nodo y de sus descendentes. Cuando este es definido para ser null, los ajustes no tienen efecto. Sobre el ajuste, cualquier hijo posible de este nodo puede ser quitado y, si la nueva cadena no está vacía o es null, se reemplaza por un simple nodo Text conteniendo la cadena estos atributos que son fijados.
Sobre la adquisición, no se realiza ninguna serialización, la cadena devuelta no contiene ningún margen. No se realiza ninguna normalización de espacios en blanco y la cadena devuelta no contiene los espacios en blanco en los elementos contenidos (Vea el atributo Text.isElementContentWhitespace). Igualmente, sobre el ajuste, no se realiza ningún análisis, la cadena de entrada es tomada como contenido de texto puro.
La cadena devuelta es construida del contenido de texto de este nodo según su tipo, como se define debajo:
Tipo de NodoContenido
ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE concatenación del valor de atributo textContent de cada nodo hijo, excluyendo los nodos COMMENT_NODE y PROCESSING_INSTRUCTION_NODE. Esto es una cadena vacía si el nodo no tiene hijos.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE nodeValue
DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE null
Excepciones sobre ajustes

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada cuando el nodo es de solo lectura.

Excepciones sobre recuperaciones

DOMException

DOMSTRING_SIZE_ERR: provocada cuando este devolviera más caracteres que los permitidos en una variable DOMString sobre la plataforma de la implementación.

Métodos
appendChild modificado en DOM Nivel 3
Añade el nodo newChild al final de la lista de hijos de este nodo. Si el newChild ya está en el árbol, este se retira primero.
Parámetros
newChild of type Node
El nodo a añadir.
Si este es un objeto DocumentFragment, el contenido entero del fragmento del documento es movido a la lista de hijos de este nodo.
Valor Devuelto

Node

El nodo a añadir.

Excepciones

DOMException

HIERARCHY_REQUEST_ERR: provocada si este nodo es de un tipo que no permite hijos del tipo de nodo newChild, o si el nodo a añadir es un ascendente del nodo, o este es el mismo nodo, o si este nodo es de tipo Document y la aplicación DOM intenta añadir un segundo nodo DocumentType o Element.

WRONG_DOCUMENT_ERR: provocada si newChild fue creado de un documento diferente del que creo este nodo.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura o si el padre anterior del nodo que esta siendo insertado es de solo lectura.

NOT_SUPPORTED_ERR: Si el nodo newChild es un hijo del nodo Document, esta excepción podría ser mostrada si la implementación DOM no soporta el borrado del hijo DocumentType o Element.

cloneNode
Devuelve un duplicado de este nodo, es decir, sirve como un constructor de copia genérica para nodos. El nodo duplicado no tiene padre (parentNode es null) y ningún dato de usuario. Los datos de usuario asociados al nodo importado no son transferidos. Sin embargo, si algún UserDataHandlers (manejador de datos de usuario) ha sido especificado con el dato asociado estos manejadores (handlers) podrán ser llamados con los parámetros apropiados después de que este método los devuelva.
La clonación de un Element copia todos los atributos y sus valores, incluyendo esos generados por el proceso XML para representar los atributos que falten, pero este método no copia algún hijo que contenga salvo que sea una clonación profunda. Este incluye el texto contenido en un Element ya que el texto está contenido en un nodo hijo Text. Clonando directamente un Attr, como opuesto para ser clonado como parte de una operación de clonación de un Element, devuelve un atributo específico (Especificado es true). Clonando un Attr siempre clona a sus hijos, ya que ellos representan sus valores, no importa si esta es una clonación profunda o no. Clonando un EntityReference automáticamente construye su sub-árbol si un Entity correspondiente está disponible, no importa si esta es una clonación profunda o no. La clonación de cualquier otro tipo de nodo simplemente devuelve una copia de este nodo.
Observe de la clonación de un sub-árbol inmutable termina en una copia mutable, pero los hijos clonados de un EntityReference son de solo lectura. Además, clonaciones de nodos Attr no especificados son especificados. Y, la clonación de nodos Document, DocumentType, Entity, y Notation dependen de la implementación.
Parámetros
deep of type boolean
Si es true, clona de forma recursiva el sub-árbol bajo el nodo especificado; si es false, clona solamente dicho nodo (y sus atributos, si es un Element).
Valor Devuelto

Node

El nodo duplicado.

Sin Excepciones
compareDocumentPosition introducido en DOM Nivel 3
Compara el nodo de referencia, es decir, el nodo que está siendo llamado por este método, con un nodo, es decir el que es pasado como parámetro, con respecto a su posición en el documento y de acuerdo al orden del documento.
Parámetros
other of type Node
El nodo a comparar con el nodo de referencia.
Valor Devuelto

unsigned short

Devuelve como el nodo es posicionado relativamente en el nodo de referencia.

Excepciones

DOMException

NOT_SUPPORTED_ERR: Cuando los nodos comparados son de diferentes implementaciones DOM que no coordinan devolver resultados constantes específicos de la implementación.

getFeature introducido en DOM Nivel 3
Este método devuelve un objeto especializado que implementa APIs especializadas de la funcionalidad/carácterística y versión especificada, como está especificado en Funcionalidades del DOM. El objeto especializado también puede ser obtenido utilizando métodos de enmarcado obligatorios específicos pero no es necesario esperarlo, como se comenta en implementaciones Mixtas de DOM. Este método también permite que la implementación proporcione objetos especializados que no soporten la interfaz Node.
Parámetros
feature of type DOMString
El nombre de la funcionalidad requerida. Observe que cualquier signo más "+" que preceda al nombre de la funcionalidad será ignorado ya que este no es significativo en el contexto de este método.
version of type DOMString
Este es el número de versión de la funcionalidad a testear.
Valor Devuelto

DOMObject

Devuelve un objeto que implementa las APIs especializadas de la funcionalidad y versión especificada, si existe, o null si no hay objetos que implementen las interfaces asociadas con esa funcionalidad. Si el DOMObject devuelto por este método implementa la interfaz Node, este debe delegar en el núcleo de Node primario y no devolver resultados inconsistentes con el núcleo Node primario tales como atributos, nodos hijos, etc.

Sin Excepciones
getUserData introducido en DOM Nivel 3
Recupera el objeto asociado a una clave (key) sobre este nodo. El objeto debe primero haber sido fijado a este nodo llamando al setUserData con la misma clave (key).
Parámetros
key of type DOMString
La clave asociada al objeto.
Valor Devuelto

DOMUserData

Devuelve el DOMUserData asociado a la clave dada sobre este nodo, o null si no hubiera ninguna.

Sin Excepciones
hasAttributes introducido en DOM Level 2
Devuelto si este nodo (si esto es un elemento) tiene algún atributo.
Valor Devuelto

boolean

Devuelve true si este nodo tiene algún atributo, false en caso contrario.

Sin Parámetros
Sin Excepciones
hasChildNodes
Devuelve si este nodo tiene algún hijo.
Valor Devuelto

boolean

Devuelve true si este nodo tiene algún hijo, false en caso contrario.

Sin Parámetros
Sin Excepciones
insertBefore modificado en DOM Nivel 3
Inserta el nodo newChild antes del nodo hijo refChild existente. Si refChild es null, inserta el newChild al final de la lista de hijos.
Si newChild es un objeto DocumentFragment, todos sus hijos son insertados, en el mismo orden, antes de refChild. Si el newChild ya está en el árbol, este es primero retirado.

Nota: Insertar un nodo antes de si mismo depende de la implementación.

Parámetros
newChild of type Node
El nodo a insertar.
refChild of type Node
El nodo de referencia, es decir, el nodo delante del cual debe ser insertado el nuevo nodo.
Valor Devuelto

Node

El nodo que se está insertando.

Excepciones

DOMException

HIERARCHY_REQUEST_ERR: provocada si este nodo es de un tipo que no permite hijos del tipo del nodo newChild, o si el nodo a insertar es uno de los ascendentes del nodo o si es el propio nodo, o si este nodo es del tipo Document y la aplicación DOM intenta insertar un segundo nodo DocumentType o Element.

WRONG_DOCUMENT_ERR: provocada si newChild fue creado a partir de un documento diferente del que creo este nodo.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura o si el padre del nodo que se está insertando es de solo lectura.

NOT_FOUND_ERR: provocada si refChild no es un hijo de este nodo.

NOT_SUPPORTED_ERR: Si este nodo es del tipo Document, esta excepción podría ser mostrada si la implementación DOM no soporta la inserción de un nodo DocumentType o Element node.

isDefaultNamespace introducido en DOM Nivel 3
Este método verifica si el namespaceURI especificado es el espacio de nombre predeterminado o no.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre a buscar.
Valor Devuelto

boolean

Devuelve true si el namespaceURI especificado es el espacio de nombre predeterminado, false en caso contrario.

Sin Excepciones
isEqualNode introducido en DOM Nivel 3
Testea si dos nodos son iguales.
Este método testea la igualdad de nodos, no la identidad (es decir, si los dos nodos son referencias del mismo objeto) que pueden ser testeadas con Node.isSameNode(). Todos los nodos que son los mismos van a ser también iguales, aunque lo contrario no puede ser verdad.
Dos nodos son iguales si y solo si las siguientes condiciones son satisfechas:
  • Los dos nodos son del mismo tipo.
  • Los atributos de cadenas siguientes son iguales: nodeName, localName, namespaceURI, prefix, nodeValue. Esto es: Ambos son null, o tengan la misma longitud y sean carácter a carácter idénticos.
  • Los atributos NamedNodeMaps son iguales. Esto es: Ambos son null, o tienen la misma longitud y para cada nodo existente en un mapa en el que hay un nodo que existe en el mapa del otro y es igual, aunque no es necesario que sea el mismo índice.
  • El childNodes NodeLists son iguales. Esto es: Ambos son null, o tienen la misma longitud y contienen nodos iguales en el mismo índice. Observe que la normalización puede afectar igualmente;, para evitar esto, los nodos deberían ser normalizados antes de ser comparados.

Para que dos nodos DocumentType sean iguales, las siguientes condiciones tienen que ser satisfechas:
  • Los atributos de cadenas siguientes son iguales: publicId, systemId, internalSubset.
  • Las entidades NamedNodeMaps son iguales.
  • Las notaciones NamedNodeMaps son iguales.

Por otra parte, lo siguiente no afecta a la igualdad: los atributos ownerDocument, baseURI, y parentNode, el atributo especificado para nodos Attr, el atributo schemaTypeInfo para nodos Attr y Element, el atributo Text.isElementContentWhitespace para nodos Text, así como cualquier otro dato de usuario o eventos a la escucha registrados sobre los nodos.

Nota: Como regla general, algo no mencionado en la descripción de arriba no es significativo en consideración con la verificación de igualdad. Observe que futuras versiones de esta especificación pueden tener en cuenta más atributos e implementaciones conforme a esta especificación esperando actualizarlas en consecuencia.

Parámetros
arg of type Node
El nodo con el que comparar la igualdad.
Valor Devuelto

boolean

Devuelve true si los nodos son iguales, false en caso contrario.

Sin Excepciones
isSameNode introducido en DOM Nivel 3
Devuelto si este nodo es el mismo nodo que el dado/indicado.
Este método proporciona una forma de determinar si dos referencias de Nodos devueltas por la implementación se refiere al mismo objeto. Cuando dos referencias de Nodos están referidas al mismo objeto, incluso si a través de un proxy, las referencias pueden ser utilizadas de manera completamente intercambiables, igual que todos los atributos tienen los mismos valores y llaman al mismo método DOM sobre una u otra referencia siempre tiene el mismo efecto.
Parámetros
other of type Node
El nodo contra el que probar.
Valor Devuelto

boolean

Devuelve true si los nodos son el mismo, false en caso contrario.

Sin Excepciones
isSupported introducido en DOM Level 2
Comprueba si la implementación DOM implementa una funcionalidad específica y que la funcionalidad es soportada por este nodo, como se especifica en Funcionalidades DOM.
Parámetros
feature of type DOMString
El nombre de la funcionalidad a testear.
version of type DOMString
Este es el número de versión de la funcionalidad a comprobar.
Valor Devuelto

boolean

Devuelve true si la funcionalidad especificada es soportada por este nodo, false en caso contrario.

Sin Excepciones
lookupNamespaceURI introducido en DOM Nivel 3
Busca el URI de espacio de nombre asociado al prefijo dado, comenzando desde este nodo.
Vea Búsqueda de URI de Espacios de Nombre para más detalles sobre el algoritmo utilizado por este método.
Parámetros
prefix of type DOMString
El prefijo a buscar. Si este parámetro es null, el método devolverá el URI de espacio de nombre por defecto si lo hay.
Valor Devuelto

DOMString

Devuelve el URI de espacio de nombre asociado o null si no ha encontrado alguno.

Sin Excepciones
lookupPrefix introducido en DOM Nivel 3
Busca el prefijo asociado al URI de espacio de nombre dado, comenzando desde este nodo. La declaración del espacio de nombre por defecto es ignorado por este método.
Vea Búsqueda de prefijos de Espacios de Nombre para más detalles sobre el algoritmo utilizado por este método.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre a buscar.
Valor Devuelto

DOMString

Devuelve un prefijo de espacio de nombre asociado si lo encuentra o null si no encuentra alguno. Si es asociado más de un prefijo al prefijo del espacio de nombre, el prefijo de espacio de nombre devuelto depende de la implementación.

Sin Excepciones
normalize modificado en DOM Nivel 3
Pone todos los nodos Text en el final del sub-árbol debajo de este Nodo, incluyendo los atributos de nodos, dentro de una forma "normal" donde solo la estructura (Por ejemplo, elementos, contenidos, instrucciones de procesado, secciones CDATA y referencias vacías) separa nodos Text, es decir, no hay ningún nodo Text adyacente ni nodos Text vacíos. Esto puede ser utilizado para asegurar que la representación de un documento DOM es el mismo si este es guardado y recargado, y es útil cuando operaciones (tales como buscar XPointer [XPointer]) que dependen de un documento con una estructura de árbol particular van a ser utilizadas. Si el parámetro "normalize-characters" del objeto DOMConfiguration adjuntado a Node.ownerDocument es true, este método también normalizará completamente los caracteres de los nodos Text.

Nota: En casos donde el documento contenga CDATASections, la operación de normalización no será suficiente, ya que XPointers no diferencia entre nodos Text y nodos CDATASection.

Sin Parámetros
Sin Valor Devuelto
Sin Excepciones
removeChild modificado en DOM Nivel 3
Quita el nodo hijo indicado por oldChild de la lista de hijos, y la devuelve.
Parámetros
oldChild of type Node
El nodo que se quitará.
Valor Devuelto

Node

El nodo quitado.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NOT_FOUND_ERR: provocada si oldChild no es un hijo de este nodo.

NOT_SUPPORTED_ERR: Si este nodo es del tipo Document, esta excepción debería ser mostrada si la implementación DOM no soporta quitar los hijos del DocumentType o el Element hijo.

replaceChild modificado en DOM Nivel 3
Reemplaza el nodo hijo oldChild por el newChild en la lista de hijos, y devuelve el nodo oldChild.
Si newChild es un objeto DocumentFragment, oldChild es reemplazado por todos los hijos del DocumentFragment, que son insertados en el mismo orden. Si el newChild está correctamente en el árbol, es primero quitado.

Nota: Reemplazar un nodo con sigo mismo depende de la implementación.

Parámetros
newChild of type Node
El nuevo nodo a poner en la lista de hijos.
oldChild of type Node
El nodo que será reemplazado en la lista.
Valor Devuelto

Node

El nodo reemplazado.

Excepciones

DOMException

HIERARCHY_REQUEST_ERR: provocada si este nodo es de un tipo que no permite hijos del tipo de nodo newChild, o si el nodo a poner es uno de estos nodos ascendentes o es el mismo nodo, o si este nodo es del tipo Document y el resultado de la operación de reemplazo agregaría un segundo DocumentType o Element en el nodo Document.

WRONG_DOCUMENT_ERR: provocada si newChild fue creado de un documento diferente del que creó este nodo.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo o el padre del nuevo nodo es de solo lectura.

NOT_FOUND_ERR: provocada si oldChild no es un hijo de este nodo.

NOT_SUPPORTED_ERR: Si este nodo es del tipo Document, esta excepción podría ser mostrada si la implementación DOM no soporta reemplazar hijos de DocumentType o Element hijo.

setUserData introducido en DOM Nivel 3
Asocia un objeto a una clave (key) sobre este nodo. El objeto puede ser luego recuperado de este nodo llamándolo con getUserData indicando la clave (key).
Parámetros
key of type DOMString
La clave (key) a asociar al objeto.
data of type DOMUserData
El objeto asociado a la clave (key) dada, o null si se quita cualquier asociación existente a esa clave (key).
handler of type UserDataHandler
El manipulador (handler) asociado a esa clave (key), o null.
Valor Devuelto

DOMUserData

Devuelve el DOMUserData previo asociado a la clave dada sobre este nodo, o null si no hubiera ninguno.

Sin Excepciones
interfaz NodeList

La interfaz NodeList proporciona la abstracción de un conjunto ordenado de nodos, sin definir o restringir como se implementa este conjunto. Los objetos NodeList en DOM son vivos.

Los elementos en NodeList son accesibles por un índice entero, que comienza en el 0.


Definición IDL
interfaz NodeList {
  Node               item(in unsigned long index);
  readonly attribute unsigned long   length;
};

Atributos
length of type unsigned long, readonly
El número de nodos de la lista. El rango de índices válidos de nodo hijos va desde 0 hasta length-1, ambos inclusive.
Métodos
item
Devuelve el elemento indexth del conjunto. Si index es mayor o igual que el número de nodos de la lista, este devuelve null.
Parámetros
index of type unsigned long
El índice dentro del conjunto.
Valor Devuelto

Node

El nodo en la posición indexth en el NodeList, o null si ese no es un índice válido.

Sin Excepciones
Interfaz NamedNodeMap

Los objetos que implementan la interfaz NamedNodeMap son utilizados para representar conjuntos de nodos a los que se pueden acceder por su nombre. Observe que NamedNodeMap no se hereda de un NodeList; en efecto, los NamedNodeMaps no se mantienen en ningún orden en particular. Los objetos contenidos en un objeto implementados en NamedNodeMap deben ser también accesibles por un índice ordinal, pero esto es simplemente para permitir una enumeración adecuada del contenido de un NamedNodeMap, y no implica que DOM especifique un orden para esos Nodos.

Los objetos NamedNodeMap en DOM son vivos.


Definición IDL
interfaz NamedNodeMap {
  Node               getNamedItem(in DOMString name);
  Node               setNamedItem(in Node arg)
                                        raises(DOMException);
  Node               removeNamedItem(in DOMString name)
                                        raises(DOMException);
  Node               item(in unsigned long index);
  readonly attribute unsigned long   length;
  // Introducido en DOM Nivel 2:
  Node               getNamedItemNS(in DOMString namespaceURI, 
                                    in DOMString localName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  Node               setNamedItemNS(in Node arg)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  Node               removeNamedItemNS(in DOMString namespaceURI, 
                                       in DOMString localName)
                                        raises(DOMException);
};

Atributos
length of type unsigned long, readonly
El número de nodos en ese mapa. El rango del índice de nodo hijo válido es de 0 a length-1 inclusive.
Métodos
getNamedItem
Recupera un nodo especificado por el nombre name.
Parámetros
name of type DOMString
El Nombre del nodo (nodeName) a recuperar.
Valor Devuelto

Node

Un Nodo (de cualquier tipo) con el nombre (nodeName) especificado, o null si el nombre especificado no identificó a ningún nodo del mapa.

Sin Excepciones
getNamedItemNS introducido en DOM Level 2
Recupera un nodo especificado por el nombre local y el URI de espacio de nombre.
Por [XML Namespaces], las aplicaciones deben utilizar el valor null (nulo) como el parámetro namespaceURI para métodos si estos no desean tener espacios de nombre.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del nodo a recuperar.
localName of type DOMString
El nombre local del nodo a recuperar.
Valor Devuelto

Node

Un Nodo (de cualquier tipo) con el nombre local y el URI de espacio de nombre especificado, o null si el nombre especificado no identificó a ningún nodo del mapa.

Excepciones

DOMException

NOT_SUPPORTED_ERR: Puede ser mostrada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el Documento no soporta Espacios de Nombre XML (tal como [HTML 4.01]).

item
Devuelve el elemento indexth del mapa. Si el índice es mayor o igual que el número de nodos en este mapa, esto devuelve null.
Parámetros
index of type unsigned long
Índice dentro del mapa.
Valor Devuelto

Node

El nodo en la posición indexth en el mapa, o null si no es un índice válido.

Sin Excepciones
removeNamedItem
Quita un nodo especificado por el nombre. Cuando este mapa contiene los atributos asociados a un elemento, si al atributo quitado se le conoce un valor por defecto, inmediatamente aparece un atributo que contiene el valor por defecto así como el URI de espacio de nombre correspondiente, el nombre local, y el prefijo cuando sea aplicable.
Parámetros
name of type DOMString
El Nombre del nodo (nodeName) a quitar.
Valor Devuelto

Node

El nodo quitado de este mapa si existe un nodo con tal nombre.

Excepciones

DOMException

NOT_FOUND_ERR: provocada si no hay ningún nodo llamado name en este mapa.

NO_MODIFICATION_ALLOWED_ERR: provocada si este mapa es de solo lectura.

removeNamedItemNS introducido en DOM Level 2
Quita un nodo especificado por el nombre local y el URI de espacio de nombre. De un atributo quitado se puede conocer el valor que tenga por defecto cuando este mapa contiene los atributos asociados a un elemento, como los atributos devueltos por la interfaz del atributo Node. Si es así, aparece inmediatamente un atributo conteniendo el valor por defecto así como el correspondiente URI de espacio de nombre, nombre local y prefijo cuando sea aplicable.
Por [XML Namespaces], las aplicaciones deben utilizar el valor nulo (null) como parámetro de URI de espacio de nombre para métodos que deseen no tener espacio de nombre.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del nodo a quitar.
localName of type DOMString
El nombre local del nodo a quitar.
Valor Devuelto

Node

El nodo quitado de este mapa si existe un nodo con dicho nombre local y URI de espacio de nombre.

Excepciones

DOMException

NOT_FOUND_ERR: provocada si no hay un nodo con el namespaceURI y localName especificado en este mapa.

NO_MODIFICATION_ALLOWED_ERR: provocada si este mapa es de solo lectura.

NOT_SUPPORTED_ERR: Pude ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el documento no soporta Nombres de espacio XML (tal como [HTML 4.01]).

setNamedItem
Añade un nodo utilizando su atributo nodeName. Si un nodo con este nombre existe ya en este mapa, este es reemplazado por el nuevo. Reemplazar un nodo por si mismo no tiene efecto.
Como el atributo nodeName se utiliza para determinar el nombre con el cual debe ser almacenado, los nodos múltiples de determinados tipos (aquellos que tienen un valor de cadena "especial") no pueden almacenarse ya que los nombres entrarían en conflicto. Esto es preferible en lugar de permitir asignar alias a los nodos.
Parámetros
arg of type Node
Un nodo a almacenar en este mapa. El nodo que más tarde será accesible utilizando el valor de su atributo nodeName.
Valor Devuelto

Node

Si el nuevo Node reemplaza a un nodo existente con el mismo nombre, se devuelve el Node que existía previamente, sino se devuelve null.

Excepciones

DOMException

WRONG_DOCUMENT_ERR: provocada si arg fue creado de un documento diferente del que creo este mapa.

NO_MODIFICATION_ALLOWED_ERR: provocada si este mapa es de solo lectura.

INUSE_ATTRIBUTE_ERR: provocada si arg es un Attr que ya es un atributo válido de otro objeto Element. El usuario de DOM necesita clonar explícitamente los nodos Attr para reutilizarlos en otros elementos.

HIERARCHY_REQUEST_ERR: provocada si se intenta añadir un nodo no perteneciente a este NamedNodeMap. Los ejemplos incluyen intentar insertar algún otro nodo Attr dentro del mapa de atributos de elementos o un nodo no vacío dentro del mapa de tipo de documento (DocumentType) de Entidades.

setNamedItemNS introducido en DOM Nivel 2
Añade un nodo utilizando su namespaceURI y localName. Si el nodo con ese URI de espacio de nombre y ese nombre local ya existe en este mapa, este es reemplazado por el nuevo. Reemplazar un nodo por si mismo no tiene efecto.
Por [XML Namespaces], las aplicaciones deben utilizar el valor nulo (null) como parámetro namespaceURI para estos métodos si estos no desean tener espacio de nombre.
Parámetros
arg of type Node
Un nodo a almacenar en este mapa. El nodo será más tarde accesible utilizando el valor de sus atributos namespaceURI y localName.
Valor Devuelto

Node

Si el nuevo Node reemplaza a un nodo existente el Node reemplazado es devuelto, en caso contrario se devuelve null.

Excepciones

DOMException

WRONG_DOCUMENT_ERR: provocada si arg fue creado de un documento diferente del que creo este mapa.

NO_MODIFICATION_ALLOWED_ERR: provocada si este mapa es de solo lectura.

INUSE_ATTRIBUTE_ERR: provocada si arg es un Attr que es un atributo válido de otro objeto Element. El usuario de DOM necesita clonar explícitamente nodos Attr para reutilizarlos en otros elementos.

HIERARCHY_REQUEST_ERR: provocada si se intenta añadir un nodo no perteneciente a este NamedNodeMap. Los ejemplos incluyen intentar insertar algún otro nodo Attr dentro del mapa de atributos de elementos o un nodo no vacío dentro del mapa de tipo de documentos (DocumentType) de Entidades.

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el Documento no soporta Espacios de Nombre XML (tal como [HTML 4.01]).

Interfaz CharacterData

La interfaz CharacterData extiende al Nodo con un conjunto de atributos y métodos para acceder a datos de caracteres DOM. Por claridad este conjunto es definido aquí en lugar de hacerlo sobre cada objeto que utilice estos atributos y métodos. Ningún objeto DOM corresponde directamente a CharacterData, sin embargo Text y otros hereden su interfaz de él. Todos los offsets (posiciones) en esta interfaz comienzan desde 0.

Como se explica en la interfaz DOMString, las cadenas de texto en DOM son representadas en UTF-16, es decir, como una secuencia de unidades de 16-bit. En lo siguiente, el termino unidades 16-bit es usado siempre que es necesario indicar que la indexación en CharacterData está hecha en unidades de 16-bit.


Definición IDL
interfaz CharacterData : Node {
           attribute DOMString       data;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  readonly attribute unsigned long   length;
  DOMString          substringData(in unsigned long offset, 
                                   in unsigned long count)
                                        raises(DOMException);
  void               appendData(in DOMString arg)
                                        raises(DOMException);
  void               insertData(in unsigned long offset, 
                                in DOMString arg)
                                        raises(DOMException);
  void               deleteData(in unsigned long offset, 
                                in unsigned long count)
                                        raises(DOMException);
  void               replaceData(in unsigned long offset, 
                                 in unsigned long count, 
                                 in DOMString arg)
                                        raises(DOMException);
};

Atributos
data of type DOMString
Los datos de caracteres del nodo que implementa esta interfaz. La implementación DOM no puede poner arbitrariamente límites sobre la cantidad de datos que pueden ser almacenados en un nodo CharacterData. Sin embargo, los límites de una implementación pueden hacer que no quepa en un solo DOMString la totalidad de los datos de un nodo. En tal caso, el usuario puede llamar a substringData para recuperar los datos en bloques de tamaño apropiado.
Excepciones al establecer

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada cuando el nodo es de solo lectura.

Excepciones al leer

DOMException

DOMSTRING_SIZE_ERR: provocada cuando este devolviera más caracteres que los que caben en una variable DOMString en la plataforma de la implementación.

length of type unsigned long, readonly
El número de unidades 16-bit que están disponibles a través de data y del método substringData descrito abajo. Esto puede tener el valor cero, es decir, los nodos CharacterData pueden estar vacíos.
Métodos
appendData
Añade la cadena al final de los datos de caracteres del nodo. En caso de éxito, data proporciona acceso a la concatenación de data y el DOMString especificado.
Parámetros
arg of type DOMString
El DOMString a añadir.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

Sin Valor Devuelto
deleteData
Borra un rango de unidades 16-bit del nodo. En caso de éxito, data y length reflejan el cambio.
Parámetros
offset of type unsigned long
La posición (offset) a partir de la cual empezar a borrar.
count of type unsigned long
El número de unidades de 16-bit a borrar. Si la suma de offset y count excede a length entonces todas las unidades de 16-bit desde offset hasta el final de los datos son borradas.

Excepciones

DOMException

INDEX_SIZE_ERR: provocada si el offset especificado es negativo o mayor que el número de unidades de 16-bit de data, o si el count especificado es negativo.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

Ningún Valor Devuelto
insertData
Inserta una cadena en la posición (offset) de unidades de 16-bit especificado.
Parámetros
offset of type unsigned long
Posición (offset) del carácter desde donde insertar.
arg of type DOMString
El DOMString a insertar.

Excepciones

DOMException

INDEX_SIZE_ERR: provocada si el offset especificado es negativo o mayor que el número de unidades de 16-bit de data.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

Ningún Valor Devuelto
replaceData
Reemplaza los caracteres de unidades de 16-bit especificados empezando en la posición (offset) especificada con la cadena especificada.
Parámetros
offset of type unsigned long
La posición (offset) a partir de la cual empezar a reemplazar.
count of type unsigned long
El número de unidades de 16-bit a reemplazar. Si la suma de offset y count excede a length, entonces se reemplazan todas las unidades de 16-bit hasta el final de los datos; (es decir, el efecto es el mismo que el de una llamada al método remove la misma subcadena, seguida de una invocación al método append).
arg of type DOMString
La DOMString con la debe ser reemplazada la subcadena.

Excepciones

DOMException

INDEX_SIZE_ERR: provocada si el offset especificado es negativo o mayor que el número de unidades de 16-bit de data, o si el count especificado es negativo.

NO_MODIFICATION_ALLOWED_ERR: Provocado si este nodo es de solo lectura.

Ningún Valor Devuelto
substringData
Extrae una subcadena de datos del nodo.
Parámetros
offset of type unsigned long
Posición (offset) del inicio de la subcadena a extraer.
count of type unsigned long
El número de unidades de 16-bit a extraer.
Valor Devuelto

DOMString

La subcadena especificada. Si la suma de offset y count excede a length, entonces se devuelven todas las unidades de 16-bit hasta el final de los datos devueltos.

Excepciones

DOMException

INDEX_SIZE_ERR: provocada si el offset especificado es negativo o mayor que el número de unidades de 16-bit de data, o si el count especificado es negativo.

DOMSTRING_SIZE_ERR: provocada si la subcadena de texto especificada no cabe en un DOMString.

Interfaz Attr

La interfaz Attr representa un atributo de un objeto Element. Normalmente los valores permitidos para el atributo está definidos en el esquema asociado al documento.

Los objetos Attr heredan la interfaz Node, pero como en realidad no son nodos hijos del elemento al que describen, DOM no los considera parte del árbol del documento. Así, los atributos de Node parentNode, previousSibling, y nextSibling tienen un valor null para los objetos Attr. DOM considera que los atributos son propiedades de elementos, es decir, que no tienen una identidad separada de los elementos a los que están asociados; gracias a esto debería ser más sencillo implementar carácterísticas tales como atributos por defecto asociados a elementos de un tipo dado. Además, los nodos Attr no pueden ser hijos inmediatos de un DocumentFragment. Sin embargo, pueden asociarse a nodos Element contenidos dentro de un DocumentFragment. En resumen, los usuarios y los implementadores del DOM deben darse cuenta de que los nodos Attr tienen algunas cosas en común con otros objetos que heredan la interfaz Node, pero que son al mismo tiempo bastante diferentes a ellos

El valor efectivo del atributo se determina de la siguiente manera: si se le ha asignado a ese atributo explícitamente un valor, ese valor es el valor efectivo del atributo; en caso contrario, si hay una declaración para ese atributo, y dicha declaración incluye un valor por defecto, entonces el valor por defecto es el valor efectivo del atributo; en otro caso, no existe el atributo para este elemento en el modelo de estructura mientras no se haya añadido explícitamente. Observe que el atributo Node.nodeValue del ejemplar Attr también puede utilizarse para obtener la versión en forma de cadena del valor o valores del atributo.

Si explícitamente no se asignó un valor al atributo en el documento pero tiene un valor por defecto proporcionado por el esquema asociado con el documento, un nodo atributo podría ser creado con el conjunto especificado a false . Quitar nodos de atributo para los que un valor por defecto es definido en el esquema genera un nuevo nodo atributo con el valor por defecto y el conjunto especificado a false. Si la validación ocurriera invocando Document.normalizeDocument(), los nodos de atributos equivalentes especificados a false son vueltos al procesar de acuerdo a los valores de atributos por defecto proporcionados por el esquema. Si no hay valor por defecto asociado con este atributo en el esquema, el nodo de atributo es descartado.

En XML, donde el valor de un atributo puede contener referencias a entidades, los nodos hijos del nodo Attr pueden ser o bien nodos Text o EntityReference (cuando estos están en uso; ver la descripción de EntityReference).

El Núcleo de DOM representa todos los valores de atributos como cadenas simples, incluso si el DTD o el esquema asociado con el documento declaran algún tipo específico como Símbolo (tokenized).

La forma de normalizar el valor del atributo es realizada por la implementación DOM dependiendo del conocimiento de la implementación acerca del esquema en uso. Normalmente, los atributos value y nodeValue de un nodo Attr inicialmente devuelven el valor normalizado dado por el analizador. También es en el caso de que Document.normalizeDocument() es llamado después (asumiendo que las opciones correctas han sido establecidas). Pero este no puede ser el caso después de la mutación, independientemente de si la mutación es realizada estableciendo directamente el valor de cadena o cambiando los nodos hijos de Attr. En particular, esto es verdadero cuando las referencias de caracteres están implicadas, considerando que esos no son representados en el DOM y ni en el impacto de la normalización del valor del atributo. De otra parte, si la implementación conoce el esquema en uso cuando el valor del atributo es cambiado, y este es diferente de un tipo de CDATA, este puede normalizarse otra vez en ese momento. Esto es verdadero sobre todo en implementaciones DOM especializadas, como implementaciones DOM SVG, que almacena los valores de atributos de forma interna diferente de una cadena.

La siguiente tabla muestra algunos ejemplos de la relación entre el valor del atributo en el documento original (atributo analizado), el valor expuesto por DOM, y la serialización del valor:

EjemplosValor de Atributo Analizado Inicial Attr.value Valor de atributo Serializado
Referencia de Carácter
"x&#178;=5"
"x²=5"
"x&#178;=5"
Entidad de Carácter embebido
"y&lt;6"
"y<6"
"y&lt;6"
Nueva línea Literal entre
"x=5&#10;y=6"
"x=5
y=6"
"x=5&#10;y=6"
Nueva línea normalizada entre
"x=5
y=6"
"x=5 y=6"
"x=5 y=6"
Entidad e con nueva línea literal
<!ENTITY e
'...&#10;...'>
[...]>
"x=5&e;y=6"
Depende de la Implementación y de las Opciones de Carga Depende de la Implementación y de las Opciones de Carga/Guardado

Definición IDL
interfaz Attr : Node {
  readonly attribute DOMString       name;
  readonly attribute boolean         specified;
           attribute DOMString       value;
                                        // raises(DOMException) on setting

  // Introducido en DOM Nivel 2:
  readonly attribute Element         ownerElement;
  // Introducido en DOM Nivel 3:
  readonly attribute TypeInfo        schemaTypeInfo;
  // Introducido en DOM Nivel 3:
  readonly attribute boolean         isId;
};

Atributos
isId of type boolean, readonly, introducido en DOM Nivel 3
Devuelve si ese atributo se reconoce que es del tipo ID (es decir, que contiene un identificador para este propio elemento) o no. Cuando este y su valor son únicos, el Elemento propietario (ownerElement) de este atributo puede ser recuperado utilizando el método Document.getElementById. La implementación podría utilizar varios caminos para determinar si a un nodo atributo se le conoce que contenga un identificador:
  • Si la validación ocurre utilizando un esquema XML [Prte 1 del Esquema XML] mientras se está cargando el documento o mientras se está invocando Document.normalizeDocument(), los valores del post-schema-validation infoset contributions (PSVI contributions) (Aportador de información establecida de validación de esquema de envío) son utilizados para determinar si este atributo es un atributo ID de esquema resuelto usando el esquema resuelto de ID definido en [XPointer].
  • Si la validación ocurre utilizando un DTD mientras se está cargando el documento o mientras se está invocando Document.normalizeDocument(), el valor del conjunto de información (infoset) [Definición del Tipo] se utiliza para determinar si este atributo es un atributo ID resuelto DTD usando el DTD resuelto de ID definido en [XPointer].
  • del uso de los métodos Element.setIdAttribute(), Element.setIdAttributeNS(), o Element.setIdAttributeNode(), es decir, es un atributo ID resuelto de usuario;

    Nota: El marco de trabajo de XPointer (ver sección 3.2 en [XPointer]) considera al DOM atributo ID resuelto de usuario como parte de la definición de XPointer ID resuelto externamente.

  • Los mecanismos utilizados no recogidos en esta especificación, son entonces un atributo ID resuelto externamente. Esto incluye la utilización de esquemas de lenguajes diferentes de esquemas XML y DTD.

Si la validación ocurre mientras se invoca Document.normalizeDocument(), todos los atributos ID determinados por el usuario son reformulados y toda la información de los nodos atributos ID es reevaluada de acuerdo al esquema utilizado. Como consecuencia, si el atributo Attr.schemaTypeInfo contiene un tipo ID, isId siempre devolverá verdadero (true).
name of type DOMString, readonly
Devuelve el nombre de este atributo. Si Node.localName es distinto de null, este atributo es un nombre cualificado.
ownerElement of type Element, readonly, introducido en DOM Level 2
El nodo Element al que este atributo va unido o null si este atributo no está en uso.
schemaTypeInfo of type TypeInfo, readonly, introducido en DOM Nivel 3
El tipo de información asociada con este atributo. Mientras el tipo de información contenida en este atributo es la garantía para ser correcto después de la carga del documento o invocación de Document.normalizeDocument(), schemaTypeInfo puede no ser fiable si el nodo fue movido.
specified of type boolean, readonly
True si a este atributo se le asigno explícitamente un valor en el documento, false en caso contrario. Si la aplicación cambia el valor de este nodo atributo (incluso si acaba teniendo el mismo valor que el valor por defecto) entonces este es establecido a true. La implementación pueden manejar los atributos con valores por defecto de otros esquemas de modo similar pero las aplicaciones deben utilizar Document.normalizeDocument() para garantizar que esta información es actualizada.
value of type DOMString
Cuando se lee, el valor del atributo es devuelto como una cadena. Las referencias a entidades generales y de caracteres se reemplazan por sus valores. Ver también el método getAttribute en la interfaz Element.
Cuando se establece, esto crea un nodo Text con los contenidos no analizados de la cadena, es decir, cualquier carácter que un procesador XML pueda reconocer como etiqueta (markup) es tratada como texto literal. Ver también el método Element.setAttribute().
Algunas implementaciones especializadas, tales como algunas implementaciones [SVG 1.1], pueden hacer automáticamente normalizaciones, incluso después de la mutación; en tal caso, el valor recuperado puede diferir del valor establecido.
Excepciones al establecer

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada cuando el nodo es de solo lectura.

Interfaz Element

La interfaz Element representa un elemento en un documento HTML o XML. Los elementos pueden tener atributos asociados a ellos; como la interfaz Element se hereda de Node, puede utilizarse el atributo de la interfaz genérica Node attributes para obtener el conjunto de todos los atributos de un elemento. Existen métodos en la interfaz Element para obtener o bien un objeto Attr por su nombre o bien un valor de atributo por su nombre. En XML, en el cual un valor de atributo puede contener referencias a entidades, debería obtenerse un objeto Attr para examinar el posiblemente complejo sub-árbol que representa el valor del atributo. Por otra parte, en HTML, en el cual todos los atributos tienen valores de cadenas simples, pueden emplearse con seguridad métodos más convenientes para acceder directamente al valor de un atributo.

Nota: En DOM Nivel 2, el método normalize es heredado de la interfaz Node donde este fue movido.


Definición IDL
interfaz Element : Node {
  readonly attribute DOMString       tagName;
  DOMString          getAttribute(in DOMString name);
  void               setAttribute(in DOMString name, 
                                  in DOMString value)
                                        raises(DOMException);
  void               removeAttribute(in DOMString name)
                                        raises(DOMException);
  Attr               getAttributeNode(in DOMString name);
  Attr               setAttributeNode(in Attr newAttr)
                                        raises(DOMException);
  Attr               removeAttributeNode(in Attr oldAttr)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString name);
  // Introducido en DOM Nivel 2:
  DOMString          getAttributeNS(in DOMString namespaceURI, 
                                    in DOMString localName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  void               setAttributeNS(in DOMString namespaceURI, 
                                    in DOMString qualifiedName, 
                                    in DOMString value)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  void               removeAttributeNS(in DOMString namespaceURI, 
                                       in DOMString localName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  Attr               getAttributeNodeNS(in DOMString namespaceURI, 
                                        in DOMString localName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  Attr               setAttributeNodeNS(in Attr newAttr)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI, 
                                            in DOMString localName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 2:
  boolean            hasAttribute(in DOMString name);
  // Introducido en DOM Nivel 2:
  boolean            hasAttributeNS(in DOMString namespaceURI, 
                                    in DOMString localName)
                                        raises(DOMException);
  // Introducido en DOM Nivel 3:
  readonly attribute TypeInfo        schemaTypeInfo;
  // Introducido en DOM Nivel 3:
  void               setIdAttribute(in DOMString name, 
                                    in boolean isId)
                                        raises(DOMException);
  // Introducido en DOM Nivel 3:
  void               setIdAttributeNS(in DOMString namespaceURI, 
                                      in DOMString localName, 
                                      in boolean isId)
                                        raises(DOMException);
  // Introducido en DOM Nivel 3:
  void               setIdAttributeNode(in Attr idAttr, 
                                        in boolean isId)
                                        raises(DOMException);
};

Atributos
schemaTypeInfo of type TypeInfo, readonly, introducido en DOM Nivel 3
El tipo de información asociada con este elemento.
tagName of type DOMString, readonly
El nombre del elemento. Si Node.localName es diferente a null, este atributo es un nombre cualificado. Por ejemplo, en:
          <elementoEjemplo id="demo"> 
          ... 
          </elementoEjemplo> ,
        
tagName tiene el valor "elementoEjemplo". Obsérvese que en XML se conserva la distinción entre mayúsculas y minúsculas, como en todas las operaciones del DOM. El DOM HTML devuelve el tagName de un elemento HTML en la forma canónica en mayúsculas, independientemente de la forma en que se presentaba en el documento fuente HTML.
Métodos
getAttribute
Obtiene el valor de un atributo por su nombre.
Parámetros
name of type DOMString
El nombre del atributo a obtener.
Valor Devuelto

DOMString

El valor Attr como una cadena, o la cadena vacía si ese atributo no tiene un valor especificado o por defecto.

Sin Excepciones
getAttributeNS introducido en DOM Level 2
Obtiene un valor del atributo por el nombre local y URI de espacio de nombre.
Por [Espacios de Nombres XML], las aplicaciones deben utilizar para los métodos el valor null como el parámetro de namespaceURI si estos no desean tener espacio de nombre.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del atributo a obtener.
localName of type DOMString
El nombre local del atributo a obtener.
Valor Devuelto

DOMString

El valor de Attr como una cadena, o la cadena vacía si ese atributo no tiene un valor especificado o por defecto.

Excepciones

DOMException

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto por el documento no soporta Espacios de Nombres XML (como [HTML 4.01]).

getAttributeNode
Obtiene un nodo atributo por el nombre.
Para obtener un nodo atributo por el nombre cualificado y el URI de espacio de nombre, utilice el método getAttributeNodeNS.
Parámetros
name of type DOMString
El nombre (nodeName) del atributo a obtener.
Valor Devuelto

Attr

El nodo Attr con el nombre especificado (nodeName) o null si no existe tal atributo.

Sin Excepciones
getAttributeNodeNS introducido en DOM Level 2
Obtiene un nodo Attr por nombre local y URI de espacio de nombre.
Por [Espacios de Nombres XML], las aplicaciones deben utilizar el valor null como parámetro de namespaceURI para los métodos si estos no desean tener espacio de nombre.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del atributo a obtener.
localName of type DOMString
El nombre local del atributo a obtener.
Valor Devuelto

Attr

El nodo Attr con los atributos nombre local y URI de espacio de nombre especificados o null si no existe tal atributo.

Excepciones

DOMException

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el documento no soporta los Espacios de Nombres XML (tal como [HTML 4.01]).

getElementsByTagName
Devuelve una lista NodeList de todos los Elementos descendentes con un nombre de etiqueta dado, en el orden del documento.
Parámetros
name of type DOMString
El nombre de la etiqueta a emparejar. El valor especial "*" se empareja con todas las etiquetas.
Valor Devuelto

NodeList

Una lista de los nodos Element emparejados.

Sin Excepciones
getElementsByTagNameNS introducido en DOM Level 2
Devuelve una lista NodeList de todos los Elementos descendentes con un nombre local y URI de espacio de nombre dado en el orden del documento.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre de los elementos a emparejar. El valor especial "*" empareja a todos los espacios de nombre.
localName of type DOMString
El nombre local de los elementos a emparejar. El valor especial "*" empareja a todos los nombres locales.
Valor Devuelto

NodeList

Un nuevo objeto NodeList que contiene todos los Elementos emparejados.

Excepciones

DOMException

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el Documento no soporta Espacios de Nombres XML (tal como [HTML 4.01]).

hasAttribute introducido en DOM Level 2
Devuelve true cuando un atributo con un nombre dado está especificado en este elemento o tiene un valor por defecto, false en caso contrario.
Parámetros
name of type DOMString
El nombre del atributo a buscar.
Valor Devuelto

boolean

true si un atributo con el nombre dado está especificado en este elemento o tiene un valor por defecto, false en caso contrario.

Sin Excepciones
hasAttributeNS introducido en DOM Level 2
Devuelve true cuando un atributo con un nombre local y URI de espacio de nombre dado está especificado en este elemento o tiene un valor por defecto, false en caso contrario.
Por [Espacios de Nombre XML], las aplicaciones deben utilizar el valor null como parámetro namespaceURI para los métodos si estos no quieren tener un espacio de nombre.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del atributo a buscar.
localName of type DOMString
El nombre local del atributo a buscar.
Valor Devuelto

boolean

true si un atributo con el nombre local y URI de espacio de nombre dado está especificado en este elemento o tiene un valor por defecto y false en caso contrario.

Excepciones

DOMException

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el Documento no soporta los Espacios de Nombres XML (tal como [HTML 4.01]).

removeAttribute
Quita un atributo por el nombre. Si un valor por defecto para el atributo quitado es definido en el DTD, un nuevo atributo aparece inmediatamente con el valor por defecto así como con el URI de espacio de nombre, nombre local correspondiente, y el prefijo cuando sea aplicable. La implementación puede manejar los valores por defecto desde otro esquema similar pero las aplicaciones deberían utilizar Document.normalizeDocument() para garantizar que esta información sea actualizada.
Si no se encuentra un atributo con este nombre, este método no tiene efecto.
Para quitar un atributo por el nombre local y el URI de espacio de nombre, utilice el método removeAttributeNS.
Parámetros
name of type DOMString
El nombre del atributo a quitar.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

No Devuelve Ningún Valor
removeAttributeNS introducido en DOM Level 2
Quita un atributo por el nombre local y el URI de espacio de nombre. Si un valor por defecto para el atributo quitado es definido en el DTD, un nuevo atributo aparece inmediatamente con el valor por defecto así como con el URI de espacio de nombre, nombre local correspondiente, y el prefijo cuando sea aplicable. La implementación puede manejar los valores por defecto desde otro esquema similar pero las aplicaciones deberían utilizar Document.normalizeDocument() para garantizar que esta información se actualiza.
Si no se encuentra un atributo con este nombre local y URI de espacio de nombre, este método no tiene efecto.
Por [Espacios de Nombres XML], las aplicaciones pueden utilizar el valor null como el parámetro namespaceURI para los métodos si estos no desean tener espacios de nombre.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del atributo a quitar.
localName of type DOMString
El nombre local el atributo a quitar.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el Documento no soporta los Espacios de Nombres XML (tal como [HTML 4.01]).

No Devuelve Ningún Valor
removeAttributeNode
Quita el nodo atributo especificado. Si un valor por defecto para el nodo Attr quitado es definido en el DTD, un nuevo nodo aparece inmediatamente con el valor por defecto así como con el URI de espacio de nombre, nombre local correspondientes, y el prefijo cuando sea aplicable. Las implementaciones pueden manejar los valores por defecto desde otros esquemas similares pero las aplicaciones deberían utilizar Document.normalizeDocument() para garantizar que esta información se actualiza.
Parámetros
oldAttr of type Attr
El nodo Attr a quitar de la lista de atributos.
Valor Devuelto

Attr

El nodo Attr que fue quitado.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NOT_FOUND_ERR: provocada si oldAttr no es un atributo del elemento.

setAttribute
Añade un nuevo atributo. Si un atributo con este nombre está presente en el elemento, su valor es cambiado por el valor del parámetro. Este valor es una simple cadena; no es analizada en el momento de establecerla. De modo que cualquier código o markup (como por ejemplo sintaxis que debe ser reconocida como una referencia a una entidad) es tratada como texto literal, y la implementación debe transformarlo en secuencias de escape de forma apropiada al producir su salida. Para asignar a un atributo un valor que contenga referencias a entidades, el usuario puede crear un nodo Attr y además nodos Text y EntityReference, construir el sub-árbol apropiado, y usar setAttributeNode para asignarlo como valor del atributo.
Para establecer un atributo con un nombre cualificado y un URI de espacio de nombre, utilice el método setAttributeNS.
Parámetros
name of type DOMString
El nombre del atributo a crear o modificar.
value of type DOMString
Valor a establecer en forma de cadena.

Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el nombre especificado no es un nombre XML de acuerdo con la versión XML en uso especificada en el atributo Document.xmlVersion.

NO_MODIFICATION_ALLOWED_ERR: provocada si el nodo es de solo lectura.

No Devuelve Ningún Valor
setAttributeNS introducido en DOM Level 2
Añade un nuevo atributo. Si un atributo con el mismo nombre local y URI de espacio de nombre está presente en el elemento, su prefijo es cambiado al prefijo del qualifiedName (nombre cualificado), y su valor es cambiado por el valor del parámetro. Este valor es una simple cadena; no es analizada en el momento de establecerla. De modo que cualquier código o markup (como por ejemplo sintaxis que debe ser reconocida como una referencia a una entidad) es tratada como texto literal, y la implementación debe transformarlo en secuencias de escape de forma apropiada al producir su salida. Para asignar a un atributo un valor que contenga referencias a entidades, el usuario puede crear un nodo Attr y además nodos Text y EntityReference, construir el sub-árbol apropiado, y utilizar setAttributeNodeNS o setAttributeNode para asignarlo como valor del atributo.
Por [Espacios de Nombres XML], las aplicaciones pueden utilizar el valor null como parámetro del namespaceURI para los métodos si estos no desean tener espacio de nombre.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del atributo a crear o modificar.
qualifiedName of type DOMString
El nombre cualificado del atributo a crear o modificar.
value of type DOMString
El valor a establecer en forma de cadena.

Excepciones

DOMException

INVALID_CHARACTER_ERR: provocada si el nombre cualificado especificado no es un nombre XML de acuerdo a la versión XML en uso especificado en el atributo Document.xmlVersion.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NAMESPACE_ERR: provocada si el nombre cualificado está mal formado por los Espacios de Nombres en la especificación XML, si el Nombre cualificado tiene un prefijo y el URI de espacio de nombre es null, si el Nombre cualificado tiene un prefijo que es "xml" y el URI de espacio de nombre es diferente del "http://www.w3.org/XML/1998/namespace", si el Nombre cualificado o su prefijo es "xmlns" y el URI de espacio de nombre es diferente de "http://www.w3.org/2000/xmlns/", o si el URI de espacio de nombre es "http://www.w3.org/2000/xmlns/" y ni el Nombre cualificado ni su prefijo son "xmlns".

NOT_SUPPORTED_ERR: Puede ser provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el Documento no soporta los Espacios de Nombres XML(tal como [HTML 4.01]).

No Devuelve Ningún Valor
setAttributeNode
Añade un nuevo nodo atributo. Si un atributo con ese nombre (nodeName) ya está presente en ese elemento, este es reemplazado por el nuevo. Reemplazar un nodo atributo por si mismo no tiene efecto.
Para añadir un nuevo nodo atributo con un nombre cualificado y URI de espacio de nombre, utilice el método setAttributeNodeNS.
Parámetros
newAttr of type Attr
El nodo Attr a añadir a la lista de atributos.
Valor Devuelto

Attr

Si el atributo newAttr reemplaza un atributo existente, el nodo Attr reemplazado es devuelto, en caso contrario de devuelve null.

Excepciones

DOMException

WRONG_DOCUMENT_ERR: provocada si newAttr fue creado de un documento diferente del que creó el elemento.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

INUSE_ATTRIBUTE_ERR: provocada si newAttr es ya un atributo de otro objeto Element. El usuario de DOM debe clonar explícitamente los nodos Attr para reutilizarlos en otros elementos.

setAttributeNodeNS introducido en DOM Level 2
Añade un nuevo atributo. Si ya está presente un atributo con ese nombre local y URI de espacio de nombre en el elemento, este es reemplazado por el nuevo. Reemplazar un nodo atributo por si mismo no tiene efecto.
Por [Espacios de Nombre XML], las aplicaciones necesitan utilizar el valor null como parámetro del URI de espacio de nombre para los métodos si estos no desean tener espacio de nombre.
Parámetros
newAttr of type Attr
El nodo Attr a añadir a la lista de atributos.
Valor Devuelto

Attr

Si el atributo newAttr reemplaza un atributo existente con el mismo nombre local y URI de espacio de nombre, el nodo Attr reemplazado es devuelto, en caso contrario se devuelve null.

Excepciones

DOMException

WRONG_DOCUMENT_ERR: provocada si newAttr fue creado de un documento diferente del que fue creado el elemento.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

INUSE_ATTRIBUTE_ERR: provocada si newAttr es ya un atributo de otro objeto Element. El usuario de DOM necesita clonar explícitamente los nodos Attr para reutilizarlos en otros elementos.

NOT_SUPPORTED_ERR: Puede se provocada si la implementación no soporta la funcionalidad "XML" y el lenguaje expuesto en el Documento no soporta Espacios de Nombre XML (tal como [HTML 4.01]).

setIdAttribute introducido en DOM Nivel 3
Si el parámetro isId es true, este método declara que el atributo especificado es un Atributo ID decidido por el usuario. Este afecta al valor de Attr.isId y al comportamiento de Document.getElementById, pero no cambia ningún esquema que puede estar en uso, en particular este no afecta a Attr.schemaTypeInfo del nodo especificado Attr. Usa el valor false para el parámetro isId para no declarar un atributo que será un atributo ID decidido por el usuario.
Para especificar un atributo por el nombre local y el URI de espacio de nombre, utilice el método setIdAttributeNS.
Parámetros
name of type DOMString
El nombre del atributo.
isId of type boolean
Si el atributo es de tipo ID.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NOT_FOUND_ERR: provocada si el nodo especificado no es un atributo de este elemento.

No Devuelve Ningún Valor
setIdAttributeNS introducido en DOM Nivel 3
Se el parámetro isId es true, este método declara el atributo especificado para ser un atributo ID decidido por el usuario. Este afecta al valor de Attr.isId y al comportamiento de Document.getElementById, pero no cambia ningún esquema que pueda ser usado, en particular este no afecta al Attr.schemaTypeInfo del nodo Attr especificado. Usa el valor false para el parámetro isId para declarar un atributo que no es un atributo ID decidido por el usuario.
Parámetros
namespaceURI of type DOMString
El URI de espacio de nombre del atributo.
localName of type DOMString
El nombre local del atributo.
isId of type boolean
Si el atributo es del tipo ID.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NOT_FOUND_ERR: provocada si el nodo especificado no es un atributo de este elemento.

No Devuelve Ningún Valor
setIdAttributeNode introducido en DOM Nivel 3
Si el parámetro isId es true, este método declara que el atributo especificado es un atributo ID designado por el usuario. Este afecta al valor de Attr.isId y al comportamiento de Document.getElementById, pero no cambia ningún esquema que pueda ser usado, en particular esto no afecta al Attr.schemaTypeInfo del nodo Attr especificado. Usa el valor false para el parámetro isId para declarar un atributo que no es un atributo ID designado por el usuario.
Parámetros
idAttr of type Attr
El nodo atributo.
isId of type boolean
Si el atributo es del tipo ID.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

NOT_FOUND_ERR: provocada si el nodo especificado no es un atributo de este elemento.

No Devuelve Ningún Valor
Interfaz Text

La interfaz Text es heredada de CharacterData y representa el contenido textual (los llamados datos de caracteres en XML) de un Element o Attr. Si no hay código dentro de los contenidos de un elemento, el texto está contenido en un solo objeto que implementa la interfaz Text que es el único hijo del elemento. Si hay código, este es analizado dentro de la información de los elementos (elementos, comentarios, etc.) y nodos Text que forma la lista de hijos del elemento.

Cuando se dispone un documento por primera vez a través del DOM, hay un solo nodo Text para cada bloque de texto. Los usuarios pueden crear nodos Text adyacentes que representen los contenidos de un elemento dado sin ningún código intermedio, pero debería recordar que no hay manera de representar las separaciones entre estos nodos en XML o HTML, de modo que (en general) no persistirán entre sesiones de edición del DOM. El método Node.normalize() combina estos objetos Text adyacentes en un solo nodo para cada bloque de texto.

No se realiza ninguna comprobación léxica sobre el contenido de un nodo Text y, dependiendo de la posición del documento, algunos caracteres deben ser escapados durante la serialización utilizando referencias de caracteres; por ejemplo los caracteres "<&" si el contenido textual es parte de un elemento o de un atributo, la secuencia de caracteres "]]>" cuando es parte de un elemento, las comillas dobles " o el apostrofe ' cuando es parte de un atributo.


Definición IDL
interfaz Text : CharacterData {
  Text               splitText(in unsigned long offset)
                                        raises(DOMException);
  // Introducido en DOM Nivel 3:
  readonly attribute boolean         isElementContentWhitespace;
  // Introducido en DOM Nivel 3:
  readonly attribute DOMString       wholeText;
  // Introducido en DOM Nivel 3:
  Text               replaceWholeText(in DOMString content)
                                        raises(DOMException);
};

Atributos
isElementContentWhitespace of type boolean, readonly, introducido en DOM Nivel 3
Devuelto si este nodo texto contiene espacios en blanco en el contenido del elementos, a menudo llamado "espacios en blanco ignorables". El nodo texto es determinado para contener espacios en blanco en el contenido del elemento durante la carga del documento o si la validación ocurre mientras se utiliza Document.normalizeDocument().
wholeText of type DOMString, readonly, introducido en DOM Nivel 3
Devuelve todo el texto de los nodos Text lógicamente nodos de texto adyacentes a este nodo, concatenados en el orden del documento.
Por ejemplo, en el ejemplo de abajo wholeText en el nodo Text que contiene "bar" devuelve "barfoo", mientras que en el nodo Text que contiene "foo" devuelve "barfoo".
barTextNode.wholeText el valor es "barfoo"

Figura: barTextNode.wholeText el valor es "barfoo" [SVG 1.0 versión]

Métodos
replaceWholeText introducido en DOM Nivel 3
Reemplaza el texto del nodo actual y todos los nodos texto lógicamente adyacentes con el texto especificado. Todos los nodos texto lógicamente adyacentes son quitados incluido el nodo actual a menos que este fuera el recipiente del texto a reemplazar.
Este método devuelve el nodo que recibe el texto a reemplazar. El nodo devuelto es:
  • null, cuando el texto a reemplazar es una cadena vacía
  • El nodo actual, excepto cuando el nodo actual es de solo lectura;
  • Un nuevo nodo Text del mismo tipo (Text o CDATASection) al del nodo actual insertado en la posición del reemplazo.

Por ejemplo, en el ejemplo de arriba llamado replaceWholeText en el nodo Text que contiene "bar" con "yo" en el argumento resulta lo siguiente:
barTextNode.replaceWholeText("yo") modifies the textual content of barTextNode with "yo"

Figura: barTextNode.replaceWholeText("yo") modifica el contenido textual de barTextNode con "yo" [SVG 1.0 versión]


Cuando los nodos que se quitan de un EntityReference son descendentes de solo lectura, el EntityReference debe ser quitado en lugar de los nodos de solo lectura. Si algún EntityReference que será quitado tiene descendentes que no sean nodos EntityReference, Text, o CDATASection, el método replaceWholeText debe fallar antes de la realización de cualquier modificación del documento, mostrando un DOMException con el código NO_MODIFICATION_ALLOWED_ERR.
Por ejemplo, en el ejemplo de abajo llamado replaceWholeText en el nodo Text que contiene "bar" falla, porque el nodo EntityReference "ent" contiene un nodo Element el cual no puede ser quitado.
barTextNode.replaceWholeText("yo") muestra un NO_MODIFICATION_ALLOWED_ERR DOMException

Figura: barTextNode.replaceWholeText("yo") muestra un NO_MODIFICATION_ALLOWED_ERR DOMException [SVG 1.0 versión]

Parámetros
content of type DOMString
El contenido del nodo Text reemplazado.
Valor Devuelto

Text

El nodo Text creado con el contenido especificado.

Excepciones

DOMException

NO_MODIFICATION_ALLOWED_ERR: provocada si uno de los nodos Text que serán reemplazados es de solo lectura.

splitText
Divide este nodo en dos nodos por el offset especificado, manteniendo a ambos en el árbol como hermanos. Después de la división este nodo contendrá todos los datos/contenido hasta el punto offset. Un nuevo nodo del mismo tipo, que contiene todos los datos/contenido desde y después del punto offset, es devuelto. Si el nodo original tenía nodos padre, el nuevo nodo es insertado como el hermano siguiente del nodo original. Cuando el offset es igual a la longitud de este nodo, el nuevo nodo no tiene datos.
Parámetros
offset of type unsigned long
El offset de la unidad de 16-bit en el cual se producirá la división, comenzando en 0.
Valor Devuelto

Text

El nuevo nodo, del mismo tipo que este nodo.

Excepciones

DOMException

INDEX_SIZE_ERR: provocada si el offset especificado es negativo o mayor que el número de unidades de 16-bit de data.

NO_MODIFICATION_ALLOWED_ERR: provocada si este nodo es de solo lectura.

Interfaz Comment

Esta interfaz es heredada de CharacterData y representa el contenido de un comentario, es decir, todos los caracteres entre el '<!--' inicial y el '-->' final. Obsérvese que esta es la definición de un comentario en XML, y, en la práctica, en HTML, aunque algunas herramientas HTML pueden implementar la estructura completa de comentarios SGML.

No se realiza ningún chequeo en el contenido de un comentario y es por lo tanto posible tener la secuencia de caracteres "--" (doble-guión) en el contenido, el cual es ilegal en el comentario por la sección 2.5 de [XML 1.0]. La presencia de esta secuencia de caracteres debe generar un error grave durante la serialización.


Definición IDL
interfaz Comment : CharacterData {
};

Interfaz TypeInfo (introducido en DOM Nivel 3)

La interfaz TypeInfo representa el tipo referenciado de nodos Element o Attr, especificado en los esquemas asociados con el documento. El tipo es un par de propiedades URI de espacio de nombre y nombre, y depende del esquema del documento.

Si el esquema del documento es un XML DTD [XML 1.0], los valores están compuesto por los siguientes:

  • Si este tipo es referenciado de un nodo Attr, typeNamespace es "http://www.w3.org/TR/REC-xml" y el typeName representa la propiedad [tipo de atributo] en el [Establecer Información XML]. Si no hay declaración para el atributo, typeNamespace y typeName son null.
  • Si este tipo es referenciado de un nodo Element, typeNamespace y typeName son null.

Si el esquema del documento es un Esquema XML [Parte 1 de Esquemas XML], los valores son computados así usando el post-schema-validation infoset contributions (también llamado aportación PSVI) (Aportador de información establecida de validación de esquema de envío):

  • Si la propiedad [validity] existe Y es "invalid" (no válida) o "notKnown" (desconocida): las propiedades {espacio de nombre de destino} y {nombre} del tipo declarado si están disponible, en caso contrario es null.

    Nota: En el momento de la escritura, la especificación del Esquema XML no requiere la exposición del tipo declarado. Así, las implementaciones DOM podrían decidir no proporcionar el tipo de información si la validez no es válida.

  • Si la propiedad [validity] (validez) existe y es "válida":
    1. Si la [definición del tipo de miembro] existe:
      1. Si {nombre} no está ausente, entonces expone las propiedades {nombre} (name) y {espacio de nombre de destino} (target namespace) de la propiedad [definición del tipo de miembro];
      2. En caso contrario, expone el espacio de nombre y el nombre local del nombre de tipo anónimo correspondiente.
    2. Si la propiedad [Definición de Tipo] existe:
      1. Si {nombre} no está ausente, entonces expone las propiedades {name} (nombre) y {target namespace} (espacio de nombre de destino) de la propiedad [Definición de Tipo];
      2. En caso contrario, expone el espacio de nombre y nombre local del nombre de tipo anónimo correspondiente.
    3. Si la [definición del tipo de miembro anónimo] existe:
      1. Si este es falso, entonces expone las propiedades [nombre de definición del tipo de miembro] y [espacio de nombre de definición del tipo de miembro];
      2. En caso contrario, expone el espacio de nombre y el nombre local del nombre de tipo anónimo correspondiente.
    4. Si la [definición de tipo anónima] existe:
      1. Si este es falso, entonces expone las propiedades [definición de tipo de nombre] y [definición de tipo de espacio de nombre];
      2. En caso contrario, expone el espacio de nombre y nombre local del nombre de tipo anónimo.

Nota: Otros lenguajes de esquema están fuera del alcance de W3C y por lo tanto deberían definir como representar su sistema de tipos utilizando TypeInfo.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz TypeInfo {
  readonly attribute DOMString       typeName;
  readonly attribute DOMString       typeNamespace;

  // DerivationMethods
  const unsigned long       DERIVATION_RESTRICTION         = 0x00000001;
  const unsigned long       DERIVATION_EXTENSION           = 0x00000002;
  const unsigned long       DERIVATION_UNION               = 0x00000004;
  const unsigned long       DERIVATION_LIST                = 0x00000008;

  boolean            isDerivedFrom(in DOMString typeNamespaceArg, 
                                   in DOMString typeNameArg, 
                                   in unsigned long derivationMethod);
};

Grupo de definiciones de DerivationMethods

Estos son los valores disponibles para el parámetro derivationMethod usados por el método TypeInfo.isDerivedFrom(). Este es un conjunto de posibles tipos de derivación, y los valores representan las posiciones en bit. Si un bit en el parámetro derivationMethod se establece a 1, el tipo correspondiente de derivación será tenida en cuenta evaluando la derivación entre la referencia del tipo de definición y el otro tipo de definición. Cuando se utiliza el método isDerivedFrom, combinando todos ellos en el parámetro derivationMethod es equivalente a invocar el método para cada uno de ellos separadamente y combinando los resultados con la función OR booleana. Esta especificación solo define el tipo de derivación para Esquemas XML.

Además de los tipos de derivación de la lista de abajo, por favor observe que:

  • cualquier tipo se deriva de xsd:anyType.
  • cualquier tipo simple se deriva de xsd:anySimpleType por restricción.
  • cualquier tipo complejo no se deriva de xsd:anySimpleType por restricción.
Definido de Constantes
DERIVATION_EXTENSION
Si el esquema del documento es un Esquema XML [Parte 1 del Esquema XML], esta constante representa la derivación por extensión.
La definición del tipo de referencia es derivada por la extensión desde la otra definición de tipo si otra definición de tipo puede ser alcanzada recurrentemente después de la propiedad {definición de tipo base) de la definición de tipo de referencia, y al menos uno de los métodos de derivación implicados es una extensión.
DERIVATION_LIST
Si el esquema del documento es un Esquema XML [Parte 1 de Esquema XML], esta constante representa la lista.
La definición del tipo de referencia es sacada por la lista de otra definición de tipo si allí existen las dos definiciones de tipo T1 y T2 así como la definición del tipo de referencia es sacada de T1 por DERIVATION_RESTRICTION o DERIVATION_EXTENSION, T2 es sacada de la otra definición de tipo por DERIVATION_RESTRICTION, T1 tiene {variedad} la lista, y T2 es la (definición de tipo de elemento). observar que T1 podría ser igual a la definición de tipo de referencia, y T2 podría ser igual a otra definición de tipo.
DERIVATION_RESTRICTION
Si el esquema del documento es un Esquema XML [Parte 1 de Esquema XML], esta constante representa la derivación por restricción si está involucrado el tipo complejo, o una restricción si está involucrado un tipo simple.
La definición del tipo de referencia es sacada según la restricción de otra definición de tipo si la otra definición de tipo es la misma que la definición de tipo de referencia, o si la otra definición de tipo puede ser alcanzada recursivamente/recurrentemente después de (definición de tipo base) la propiedad de definición de tipo de referencia y todos los métodos de derivación implicados son restricción.
DERIVATION_UNION
Si el esquema del documento es un Esquema XML [Parte 1 de Esquema XML], esta constante representa la unión si están implicados tipos simples.
La definición del tipo de referencia es sacada por la unión de otra definición de tipo si allí existen las dos definiciones de tipo T1 y T2 como la definición del tipo referencia T1 es sacada por DERIVATION_RESTRICTION o DERIVATION_EXTENSION, T2 es sacada de otra definición de tipo por DERIVATION_RESTRICTION, T1 tiene {la variedad} la unión, y una de las definiciones del tipo miembro es T2. Observe que T1 podría ser igual que la definición del tipo referencia, y T2 podía ser igual que otra definición de tipo.
Atributos
typeName of type DOMString, readonly
El nombre de un tipo declarado para el elemento o atributo asociado, o null si es desconocido.
typeNamespace of type DOMString, readonly
El espacio de nombre (namespace) del tipo declarado para el elemento o atributo asociado o null si el elemento no tiene declaración o si no hay disponible información alguna del espacio de nombre.
Métodos
isDerivedFrom
Este método devuelve si hay una derivación entre la definición del tipo de referencia, esto es el TypeInfo en el método que se está llamando, y la otra definición de tipo, esto es el que se pasa como parámetro.
Parámetros
typeNamespaceArg of type DOMString
el espacio de nombre de la otra definición de tipo.
typeNameArg of type DOMString
el nombre de la otra definición de tipo.
derivationMethod of type unsigned long
el tipo de derivación y condiciones aplicadas entre los dos tipos, como se describe en la lista de constantes proporcionadas en esta interfaz.
Valor Devuelto

boolean

Si el esquema del documento es un DTD o no es un esquema asociado con el documento, este método siempre devolverá false.
Si el esquema del documento es un Esquema XML, el método devolverá true si la definición del tipo de referencia es sacada de la otra definición de tipo de acuerdo a los parámetros de derivación. Si el valor del parámetro es 0 (el bit no se establece a 1 para el parámetro derivationMethod), el método devolverá true si la otra definición del tipo puede ser alcanzada recursivamente por alguna combinación de (definición del tipo base), (definición del tipo objeto), o (definición del tipo miembro) de la definición del tipo de referencia.

Sin Excepciones
Interfaz UserDataHandler (introducido en DOM Nivel 3)

Cuando asociamos una clave a un objeto en un nodo utilizando Node.setUserData() la aplicación puede proporcionar un manejador que obtenga dicho objeto cuando el objeto asociado al nodo va a ser clonado, importado o renombrado. Esto puede ser usado por la aplicación para implementar distintos comportamientos respecto a los datos asociados a los nodos del DOM. Esta interfaz define esos manejadores.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz UserDataHandler {

  // OperationType
  const unsigned short      NODE_CLONED                    = 1;
  const unsigned short      NODE_IMPORTED                  = 2;
  const unsigned short      NODE_DELETED                   = 3;
  const unsigned short      NODE_RENAMED                   = 4;
  const unsigned short      NODE_ADOPTED                   = 5;

  void               handle(in unsigned short operation, 
                            in DOMString key, 
                            in DOMUserData data, 
                            in Node src, 
                            in Node dst);
};

Grupo de Definiciones de OperationType

Un número entero indicando el tipo de operación que se está realizando sobre un nodo.

Definición de Constantes
NODE_ADOPTED
El nodo es adoptado, usando Document.adoptNode().
NODE_CLONED
El nodo es clonado, usando Node.cloneNode().
NODE_DELETED
El nodo es eliminado.

Nota: Esto puede no ser soportado o puede no ser seguro en ciertos entornos, tales como Java, donde la implementación no tiene un control real cuando los objetos son eliminados realmente.

NODE_IMPORTED
El nodo es importado, usando Document.importNode().
NODE_RENAMED
El nodo es renombrado, utilizando Document.renameNode().
Métodos
handle
Este método es llamado cuando el nodo para el cual este manejador es registrado es importado o clonado.
Las aplicaciones DOM pueden no mostrar excepciones en un UserDataHandler. El efecto de lanzar excepciones del manejador depende de la implementación DOM.
Parámetros
operation of type unsigned short
Especifica el tipo de operación que se realiza sobre un nodo.
key of type DOMString
Especifica la clave por la que este manejador será llamado.
data of type DOMUserData
Especifica los datos por el que este manejador será llamado.
src of type Node
Especifica el nodo que está siendo clonado, adoptado, importado o renombrado. Esto es null cuando el nodo está siendo eliminado.
dst of type Node
Especifica el nodo recién creado si lo hay, o null.

No Devuelve Valor
Sin Excepciones
Interfaz DOMError (introducido en DOM Nivel 3)

DOMError es un interfaz que describe un error.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz DOMError {

  // ErrorSeverity
  const unsigned short      SEVERITY_WARNING               = 1;
  const unsigned short      SEVERITY_ERROR                 = 2;
  const unsigned short      SEVERITY_FATAL_ERROR           = 3;

  readonly attribute unsigned short  severity;
  readonly attribute DOMString       message;
  readonly attribute DOMString       type;
  readonly attribute DOMObject       relatedException;
  readonly attribute DOMObject       relatedData;
  readonly attribute DOMLocator      location;
};

Grupo de Definiciones de ErrorSeverity

Un número entero que indica la gravedad del error.

Definición de Constantes
SEVERITY_ERROR
La gravedad del error descrito por el DOMError es un error. Un SEVERITY_ERROR puede no causar la parada del proceso si se puede recuperar del error, a menos que DOMErrorHandler.handleError() devuelva false.
SEVERITY_FATAL_ERROR
La gravedad del error descrito por el DOMError es un error grave. Un SEVERITY_FATAL_ERROR causaría la detención normal del procesamiento. El valor devuelto de DOMErrorHandler.handleError() es ignorado a menos que la implementación decida continuar, en tal caso el comportamiento es indefinido.
SEVERITY_WARNING
La gravedad del error descrito por el DOMError es una advertencia. Un SEVERITY_WARNING no causará la parada del procesamiento, a menos que DOMErrorHandler.handleError() devuelva false.
Atributos
location of type DOMLocator, readonly
La localización del error.
message of type DOMString, readonly
La implementación especifica la descripción del error ocurrido.
relatedData of type DOMObject, readonly
La relación de DOMError.type depende de si hay algunos datos.
relatedException of type DOMObject, readonly
La relación de plataforma depende si hay alguna excepción.
severity of type unsigned short, readonly
La gravedad del error, cualquiera SEVERITY_WARNING, SEVERITY_ERROR, o SEVERITY_FATAL_ERROR.
type of type DOMString, readonly
Un DOMString indicando la relación de datos que se espera en relatedData. Los usuarios deberían referirse a la especificación del error en orden a encontrar su tipo DOMString y definiciones relatedData si las hay.

Nota: Por ejemplo, Document.normalizeDocument() genera alertas cuando el parámetro "split-cdata-sections" está en uso. Por lo tanto, el método genera un SEVERITY_WARNING con type "cdata-sections-splitted" y el primer nodo CDATASection en el orden del documento resultante de la división es devuelto por el atributo relatedData.

Interfaz DOMErrorHandler (introducido en DOM Nivel 3)

DOMErrorHandler es una interfaz de rellamada que la implementación DOM puede llamar cuando se reportan errores que ocurren mientras se procesan datos XML, o cuando se realiza algún otro procesamiento (por ejemplo, validación de un documento). Un objeto DOMErrorHandler pude ser adjuntado a un Document usando el "error-handler" (manejador de error) sobre la interfaz DOMConfiguration. Si necesita ser reportado más de un error durante una operación, la secuencia y números de los errores pasados al manejador de errores depende de la implementación.

Las aplicaciones que están usando la implementación DOM se espera que implementen esta interfaz.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz DOMErrorHandler {
  boolean            handleError(in DOMError error);
};

Métodos
handleError
Este método es llamado sobre el manejador de errores cuando ocurre un error.
Si ocurre una excepción en este método, esto se considera igual que devolver true.
Parámetros
error of type DOMError
El objeto error que describe el error. Este objeto pude ser reutilizado por la implementación DOM a través de múltiples llamadas al método handleError.
Valor Devuelto

boolean

Si el método handleError devuelve false, la implementación DOM debería detener el procesamiento actual cuando sea posible. Si el método devuelve true, el procesamiento pude continuar según DOMError.severity.

Sin Excepciones
Interfaz DOMLocator (introducido en DOM Nivel 3)

La interfaz DOMLocator describe una localización (Por ejemplo donde ha ocurrido un error).


Definición IDL
// Introducido en DOM Nivel 3:
interfaz DOMLocator {
  readonly attribute long            lineNumber;
  readonly attribute long            columnNumber;
  readonly attribute long            byteOffset;
  readonly attribute long            utf16Offset;
  readonly attribute Node            relatedNode;
  readonly attribute DOMString       uri;
};

Atributos
byteOffset of type long, readonly
El byte offset en la fuente de entrada que indica el localizador o -1 si no hay disponible byte a compensar.
columnNumber of type long, readonly
El número de columna que indica el localizador, o -1 si no hay disponible número de columna.
lineNumber of type long, readonly
El número de línea que indica el localizador, o -1 si no hay disponible número de línea.
relatedNode of type Node, readonly
El nodo que indica este localizador, o null si no hay nodo disponible.
uri of type DOMString, readonly
El URI que indica este localizador, o null si no hay URI disponible.
utf16Offset of type long, readonly
El UTF-16, como se define en [Unicode] y la resolución 1 de [ISO/IEC 10646], equivalente dentro de la fuente de entrada que indica este localizador o -1 si no hay disponible una equivalente UTF-16.
Interfaz DOMConfiguration (introducido en DOM Nivel 3)

La interfaz DOMConfiguration representa la configuración de un documento y mantiene una tabla de parámetros reconocidos. Usando la configuración, es posible cambiar el comportamiento de Document.normalizeDocument(), así como sustituir nodos CDATASection con nodos Text o especificando el tipo de esquema que debe ser utilizado cuando es requerida la validación del Document. Los objetos DOMConfiguration son utilizados también en [DOM Nivel 3 Cargar y Guardar] en las interfaces DOMParser y DOMSerializer.

Los nombres de parámetros usados por el objeto DOMConfiguration son definidos en las partes de la especificación DOM Nivel 3. Los nombres son insensibles a las mayúsculas y las minúsculas (case-insensitive). Para evitar posibles conflictos, por acuerdo, los nombres referidos a parámetros definidos fuera de la especificación DOM deberían ser únicos. Como los parámetros son expuestos como propiedades en el Enlace de Lenguaje ECMAScript, se recomienda que los nombres sigan la sección "5.16 Identificadores" de [Unicode] incluyendo el carácter '-' (Guión-Menos) pero no es obligatorio para la implementación DOM. A las implementaciones del Núcleo de DOM Nivel 3 se les requiere que reconozcan todos los parámetros definidos en esta especificación. Algunos valores de parámetros pueden ser también requeridos para que sean soportados por la implementación. Referirse a la definición de un parámetro para saber si un valor debe ser soportado o no.

Nota: Los parámetros son iguales a las funcionalidades y propiedades usadas en SAX2 [SAX].

La lista de parámetros definidos en DOM:

"canonical-form"
true
[opcional]
Canoniza el documento de acuerdo a las reglas especificadas en [Canonical XML], así como quita el nodo DocumentType (si hay alguno) del árbol, o quita declaraciones de espacios de nombre superfluas de cada elemento. Observe que esto está limitado a lo que puede ser representado en el DOM; en particular, no hay una forma para especificar el orden de atributos en DOM. Además,
Estableciendo estos parámetros a true también establecerá el estado de los parámetros indicados abajo. Los cambios posteriores del estado de uno de esos parámetros volverán la "forma canónica" de nuevo a false.
Parámetros establecidos a false: "entidades", "caracteres normalizados", "secciones cdata".
Parámetros establecidos a true: "espacios de nombre", "declaraciones de espacio de nombre", "bien formados", "elementos que contienen espacios en blanco".
Otros parámetros no cambian a menos que se especifique explícitamente en la descripción del parámetro.
false
[requerido] (predeterminado)
No hace canonizable el documento.
"cdata-sections"
true
[requerido] (predeterminado)
Mantiene los nodos CDATASection en el documento.
false
[requerido]
Transforma los nodos CDATASection del documento en nodos Text. El nuevo nodo Text es combinado con cualquier nodo Text adyacente.
"check-character-normalization"
true
[opcional]
Verifica si los caracteres en el documento están completamente normalizados, como define el apéndice B de [XML 1.1]. Cuando se encuentra una secuencia de caracteres que falla la verificación de normalización, se muestra un error con el DOMError.type igual a "check-character-normalization-failure" (la verificación de normalización de caracteres ha fallado).
false
[requerido] (predeterminado)
No se verifica si los caracteres son normalizados.
"comments"
true
[requerido] (predeterminado)
Mantiene los nodos Comment en el documento.
false
[establecido]
Descarta los nodos Comment en el documento.
"datatype-normalization"
true
[opcional]
Expone el esquema de valores normalizados en el árbol, tal como Esquema XML de valores normalizados en el caso de Esquema XML. Ya que este parámetro requiere tener información del esquema, el parámetro "validate" también será establecido a true. Teniendo este parámetro activado cuando "validate" es false no tiene efecto y no pasaría el esquema normalizado.

Nota: Ya que el documento contiene los resultados del procesamiento de XML 1.0, este parámetro no aplica a la normalización del valor del atributo como define la sección 3.3.3 de [XML 1.0] y se piensa que solo es para otros lenguajes de esquema Definición del Tipo de Documento (DTD).

false
[requerido] (predeterminado)
No realiza la normalización en el árbol.
"element-content-whitespace"
true
[requerido] (predeterminado)
Mantiene todos los espacios en blanco en el documento.
false
[opcional]
Descarta todos los nodos Text que contienen espacios en blanco en el contenido del elemento, como describe [espacios en blanco en el contenido del elemento]. La implementación está esperando a utilizar el atributo Text.isElementContentWhitespace para determinar si un nodo Text debería ser descartado o no.
"entities"
true
[requerido] (predeterminado)
Mantiene los nodos EntityReference en el documento.
false
[requerido]
Quita todos los nodos EntityReference del documento, poniendo la expansión de la entidad directamente en su lugar. Los nodos Text son normalizados, como define Node.normalize. Solamente las referencias de entidades no expandidas son conservadas en el documento.

Nota: Este parámetro no afecta a nodos Entity.

"error-handler"
[requerido]
Contiene un objeto DOMErrorHandler. Si se encuentra un error en el documento, la implementación re-llamaría al DOMErrorHandler registrado usando este parámetro. La implementación puede proporcionar un objeto DOMErrorHandler por defecto.
Cuando es llamado, DOMError.relatedData contendrá el nodo más cercado donde haya ocurrido el error. Si la implementación es incapaz de determinar el nodo donde ocurrió el error, DOMError.relatedData contendrá el nodo Document. Las mutaciones del documento que resultarán desde un manejador de errores dependerán del comportamiento en la implementación.
"infoset"
true
[requerido]
Mantiene en el documento la información definida en el Conjunto de Información XML[Conjunto de Información XML].
Esto obliga a los siguientes parámetros a false: "validated-if-schema", "entities", "datatype-normalization", "cdata-seccions".
Esto obliga a los siguientes parámetros a true: "namespace-dclarations", "well-formed", "element-content-whitespace", "comments", "namespace".
otros parámetros no son cambiados a no ser que sea especificado explícitamente en la descripción de los parámetros con getParameter devolviendo true solamente si los parámetros individuales especificados arriba son establecidos apropiadamente.
false
Establece infoset a false no teniendo efecto.
"namespaces"
true
[requerido] (predeterminado)
Representa el tratamiento de los espacios de nombre como define la Normalización de Espacio de Nombre.
false
[opcional]
No representa el tratamiento de los espacios de nombre.
"namespace-declarations"
Este parámetro no tiene efecto si el parámetro "espacio de nombres" se fija a false.
true
[requerido] (predeterminado)
Incluye la declaración de atributos de espacio de nombre, especificado o predeterminado del esquema, en el documento. Vea también las secciones "Declarando Espacios de Nombres" en [Espacios de Nombres XML] y [Espacios de Nombres XML 1.1].
false
[requerido]
Descarta todas las declaraciones de atributos de espacios de nombre. Los prefijos de espacios de nombre (Node.prefix) son conservados incluso si este parámetro es establecido a false.
"normalize-characters"
true
[opcional]
Normaliza completamente los caracteres del documento como define el apéndice B de [XML 1.1].
false
[requerido] (predeterminado)
No realiza la normalización de caracteres.
"schema-location"
[opcional]
Representa un objeto DOMString que contiene una lista de URIs, separadas por espacios en blanco (los caracteres que corresponden a la S de producción no terminada definido en la sección 2.3 [XML 1.0]), eso representa otra vez el esquema con la validación que debería ocurrir, por ejemplo el esquema actual. Los tipos de esquemas referenciados en esta lista deben combinar el tipo especificado con el tipo del esquema, si no el comportamiento de la implementación es indefinido.
El esquema especificado usando esta propiedad tiene prioridad frente a la información del esquema especificado en el propio documento. Para esquemas consciente de espacios de nombre, si un esquema especificado usando esta propiedad y un esquema especificado en el caso del documento (es decir, usando el atributo schemaLocation) en un documento de esquema (es decir usando el mecanismo import esquema) comparten el mismo targetNamespace, el esquema especificado por el usuario utilizando esta propiedad es el que será usado. Si dos esquemas especificados utilizando esta propiedad comparten el mismo targetNamespace o no tienen espacio de nombre, su comportamiento depende de la implementación.
Si no se ha proporcionado una localización, este parámetro es null.

Nota: El parámetro "schema-location" (localización de esquema) es ignorado a no ser que el valor del parámetro "schema-type" (tipo de esquema) sea establecido. Se recomienda encarecidamente que Document.documentURI sea fijada para que una implementación pueda resolver satisfactoriamente cualquier entidad externa referenciada.

"schema-type"
[opcional]
Representa un objeto DOMString que contiene un URI absoluto y representa el tipo de lenguaje de esquema usado para validar un documento. Observe que no se realiza una verificación léxica sobre el URI absoluto.
Si este parámetro no es indicado, el valor por defecto puede ser proporcionado por la implementación, basado sobre el lenguaje del esquema soportado y sobre el lenguaje del esquema utilizado en el momento de carga. Si no se proporciona un valor, este parámetro es null.

Nota: Para Esquemas XML [Parte 1 de Esquemas XML], las aplicaciones deben usar el valor "http://www.w3.org/2001/XMLSchema". Para DTD XML [XML 1.0], las aplicaciones deben utilizar el valor "http://www.w3.org/TR/REC-xml". Otros lenguajes de Esquema están fuera del alcance de W3C y por lo tanto debería recomendar un URI absoluto para usar este método.

"split-cdata-sections"
true
[requerido] (predeterminado)
La división de la sección CDATA que contiene el marcador de sección CDATA ']]>'. Cuando una sección CDATA es dividida se muestra un aviso con un DOMError.type igual a "cdata-sections-splitted" (sección cdata dividida) y un DOMError.relatedData igual al primer nodo CDATASection en el orden del documento resultante de la división.
false
[requerido]
Señala un error si CDATASection contiene un carácter no representable.
"validate"
true
[opcional]
Requiere la validación contra un esquema (es decir, un esquema XML, DTD, cualquier otro tipo o representación de esquema) del documento cuando está siendo normalizado como define [XML 1.0]. Si se encuentran errores de validación, o no se encuentra un esquema, se notifica al manejador de errores. Los valores normalizados del esquema no serán expuestos conforme al esquema usado a no ser que el parámetro "datatype-normalization" sea true.
Este parámetro recalculará:

Nota: "validate-if-schema" y "validate" son mutuamente excluyentes, estableciendo uno de ellos a true se establecerá el otro a false. Las aplicaciones deberían considerar también establecer el parámetro "well-formed" a true, como predeterminado para esa opción, cuando el documento se valida.

false
[requerido] (predeterminado)
No lleva a cabo el procesamiento del esquema, incluyendo el procesamiento del subconjunto interno. La información de los valores por defecto del atributo se conserva. Observe que la validación podría todavía ocurrir si "validate-if-schema" es true.
"validate-if-schema"
true
[opcional]
Permite la validación solo si una declaración para el elemento del documento puede ser encontrada en un esquema (independientemente de donde se encuentre, es decir Esquema XML, DTD, o cualquier otro tipo o representación de esquema). Si se permite la validación, este parámetro tiene el mismo comportamiento que el parámetro "validate" fijado a true.

Nota: "validate-if-schema" y "validate" son mutuamente excluyentes, estableciendo uno de ellos a true se establecerá el otro a false.

false
[requerido] (predeterminado)
No se debería realizar ningún procesamiento del esquema si el documento tiene un esquema, incluyendo sub-conjuntos de procesamiento internos. La información de los valores del atributo por defecto son conservados. Observe que la validación puede aun ocurrir si "validate" es true.
"well-formed"
true
[requerido] (predeterminado)
Verifica si todos los nodos son XML bien formados de acuerdo a la versión XML en uso en Document.xmlVersion:
false
[opcional]
No comprueba si el XML está bien formado.

La resolución de los identificadores de sistema asociados con entidades se hace usando Document.documentURI. Sin embargo, cuando la funcionalidad "LS" (Load and Save) definida en [DOM Nivel 3 Cargar y Guardar] es soportada por la implementación DOM, el parámetro "resource-resolver" puede ser también utilizado en objetos DOMConfiguration unidos a los nodos Document. Si este parámetro es definido, Document.normalizeDocument() invocará el recurso para resolver en lugar de utilizar Document.documentURI.


Definición IDL
// Introducido en DOM Nivel 3:
interfaz DOMConfiguration {
  void               setParameter(in DOMString name, 
                                  in DOMUserData value)
                                        raises(DOMException);
  DOMUserData        getParameter(in DOMString name)
                                        raises(DOMException);
  boolean            canSetParameter(in DOMString name, 
                                     in DOMUserData value);
  readonly attribute DOMStringList   parameterNames;
};

Atributos
parameterNames of type DOMStringList, readonly
La lista de los parámetros soportados por este objeto DOMConfiguration y al menos un valor que puede ser establecido por la aplicación. Observe que esta lista pude contener también nombres de parámetros definidos fuera de esta especificación.
Métodos
canSetParameter
Comprueba si la fijación de un parámetro con un valor específico es soportado.
Parámetros
name of type DOMString
El nombre del parámetro a comprobar.
value of type DOMUserData
Un objeto. Si es null, el valor devuelto es true.
Valor Devuelto

boolean

true si el parámetro pudiera ser establecido satisfactoriamente con el valor especificado, o false si el parámetro no es reconocido o el valor solicitado no es soportado. Esto no cambia el valor actual del parámetro.

Sin Excepciones
getParameter
Devuelve el valor de un parámetro si es conocido.
Parámetros
name of type DOMString
El nombre del parámetro.
Valor Devuelto

DOMUserData

El objeto actual asociado con el parámetro especificado o null si el objeto no tiene asociado ninguno o el parámetro no es soportado.

Excepciones

DOMException

NOT_FOUND_ERR: provocado cuando el nombre del parámetro no es reconocido.

setParameter
Establece el valor del parámetro.
Parámetros
name of type DOMString
El nombre del parámetro a fijar.
value of type DOMUserData
El nuevo valor o null si el usuario desea quitar el parámetro. Mientras que el valor del tipo de parámetro es definido como DOMUserData, el tipo de objeto debe tomar el tipo definido por la definición del parámetro. Por ejemplo, si el parámetro es "error-handler", el valor debe ser del tipo DOMErrorHandler.
Excepciones

DOMException

NOT_FOUND_ERR: provocado cuando el nombre del parámetro no es reconocido.

NOT_SUPPORTED_ERR: provocado cuando el nombre del parámetro es reconocido pero el valor requerido no puede ser establecido.

TYPE_MISMATCH_ERR: provocado si el tipo de valor para este nombre del parámetro es incompatible con el tipo de valor esperado.

Ningún Valor Devuelto

1.5 Interfaces Extendidas: Módulo XML

Las interfaces aquí definidas forman parte del Núcleo de la especificación DOM, pero los objetos que expongan estas interfaces no se encontrarán nunca en implementaciones DOM que sólo traten con HTML.

Las interfaces de esta sección no son obligatorias. Una aplicación de DOM puede usar el método DOMImplementation.hasFeature(funcionalidad, versión) con los valores de parámetros "XML" y "3.0" (respectivamente) para determinar si realmente este módulo es soportado o no por la implementación. En orden a soportar completamente este módulo, una implementación debe soportar también la funcionalidad del "Núcleo" definida en Interfaces Fundamentales: Módulo Núcleo y la funcionalidad "XMLVersion" con la versión "1.0" definida en Document.xmlVersion. Por favor para información adicional vea Conformidad en esta especificación. El módulo XML de DOM Nivel 3 es compatible con los módulos XML de DOM Nivel 2 [Núcleo de DOM Nivel 2] y XML de DOM Nivel 1 [DOM Nivel 1], esto es una implementación XML de DOM Nivel 3 que devuelve true para "XML" con la versión número "3.0" debe también devolver true para esta funcionalidad cuando el número de versión es "2.0", "1.0", "" o, null.

Interfaz CDATASection

Las secciones CDATA se usan para transformar en secuencias de escape bloques de texto que contienen caracteres que de otro modo serían considerados como código. El único delimitador reconocido en una sección CDATA es la cadena "]]>" que finaliza la sección CDATA. Las secciones CDATA no pueden anidarse. El propósito principal es la inclusión de material tal como fragmentos XML sin necesidad de escapar todos los delimitadores.

El atributo CharacterData.data contiene el texto que está contenido en la sección CDATA. Observe que este puede contener caracteres que necesiten ser escapados fuera de la sección CDATA y que, dependiendo de la codificación de caracteres ("charset") elegida para la serialización, puede ser imposible escribir en la salida ciertos caracteres como parte de la sección CDATA.

La interfaz CDATASection se hereda de la interfaz CharacterData a través de la interfaz Text. Los nodos CDATASection adyacentes no son combinados cuando se usa el método de normalización del la interfaz Node.

No se realiza ninguna comprobación léxica sobre el contenido de la sección CDATA y esto hace posible tener la secuencia de caracteres "]]>" en el contenido, lo que es ilegal en una sección CDATA según la sección 2.7 de [XML 1.0]. La presencia de esta secuencia de caracteres debe generar un error grave durante la serialización o la sección de cdata debe ser dividida antes de la serialización (vea también el parámetro "split-cdata-sections" en la interfaz DOMConfiguration).

Nota: Como ningún código es reconocido dentro de un CDATASection, las referencias de caracteres numéricos no pueden ser utilizados como un mecanismo de escape en la serialización. Por lo tanto, la acción necesita ser tomada cuando se serializa un CDATASection con una codificación de caracteres donde algunos de los caracteres contenidos no pueden ser representados. El fallo no produce un XML bien formado.
Una solución potencial en el proceso de serialización es determinar la sección CDATA antes del carácter, el carácter de salida usa una referencia de carácter o referencia de entidad, y abre una nueva sección CDATA para cualquier carácter remoto en el nodo texto. Observe, sin embargo, que algunas librerías de conversión de código en el momento de escribir no devuelven un error o excepción cuando un carácter se pierde en la codificación, haciendo que la tarea de asegurar estos datos no sea corrompida en la serialización haciéndolo más difícil.


Definición IDL
interfaz CDATASection : Text {
};

Interfaz DocumentType

Cada Document (documento) tiene un atributo doctype cuyo valor es o bien null o bien un objeto DocumentType. La interfaz DocumentType en el Núcleo de DOM proporciona una interfaz a la lista de entidades definidas para el documento, y poco más debido al efecto de espacios de nombre y de los distintos esfuerzos de esquemas XML en la representación del DTD no se entienden claramente a fecha de redacción de este documento.

El Nivel 3 del DOM no soporta la edición de los nodos DocumentType. Los nodos DocumentType son de solo lectura.


Definición IDL
interfaz DocumentType : Node {
  readonly attribute DOMString       name;
  readonly attribute NamedNodeMap    entities;
  readonly attribute NamedNodeMap    notations;
  // Introducido en DOM Nivel 2:
  readonly attribute DOMString       publicId;
  // Introducido en DOM Nivel 2:
  readonly attribute DOMString       systemId;
  // Introducido en DOM Nivel 2:
  readonly attribute DOMString       internalSubset;
};

Atributos
entities of type NamedNodeMap, readonly
Un NamedNodeMap contiene las entidades generales, tanto externas como internas, declaradas en el DTD. Los parámetros de las entidades no son contenidos. Las duplicaciones son descartadas. Por ejemplo en:
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY bar "bar2">
  <!ENTITY % baz "baz">
]>
<ex/>
la interfaz proporciona acceso a foo y a la primera declaración de bar pero no a la segunda declaración de bar o baz. Todos los nodos de este mapa implementan además la interfaz Entity.
El Nivel 2 del DOM no soporta la edición de entidades, y por tanto las entities no pueden modificarse de ningún modo.
internalSubset of type DOMString, readonly, introducido en DOM Level 2
El subconjunto interno como una cadena, o null si no hay ninguno. Estos no contienen el delimitador corchetes ([ ]).

Nota: El contenido actual devuelto depende de cuanta información está disponible para la implementación. Esto pude variar dependiendo de varios parámetros, incluyendo el procesador XML que construye el documento.

name of type DOMString, readonly
El nombre del DTD; es decir, el nombre que sigue inmediatamente a la palabra clave DOCTYPE.
notations of type NamedNodeMap, readonly
Un NamedNodeMap que contiene las notaciones declaradas en el DTD. Los duplicados se descartan. Todos los nodos en el mapa implementan además la interfaz Notation.
El Nivel 2 de DOM no soporta la edición de notaciones, y por tanto las notations no pueden ser modificadas de ninguna forma.
publicId of type DOMString, readonly, introducido en DOM Level 2
El identificador publico del subconjunto externo.
systemId of type DOMString, readonly, introducido en DOM Level 2
El identificador del sistema del subconjunto externo. Este puede ser un URI absoluto o no.
Interfaz Notation

Esta interfaz representa una notación declara en el DTD. Una notación cualquiera declarada, por el nombre, el formato de una entidad no analizada (ver la sección 4.7 de la especificación XML 1.0 [XML 1.0]), o se usa para la declaración formal de destinos de instrucciones de procesamiento (ver la sección 2.6 de la especificación XML 1.0 [XML 1.0]). El atributo nodeName heredado de Node se hace igual al nombre declarado de la notación.

El Núcleo DOM no soporta la edición de nodos Notation; son por lo tanto de solo lectura.

Un nodo Notation no tiene ningún padre.


Definición IDL
interfaz Notation : Node {
  readonly attribute DOMString       publicId;
  readonly attribute DOMString       systemId;
};

Atributos
publicId of type DOMString, readonly
El identificador público de esta notación. Si el identificador no ha sido especificado, esto es null.
systemId of type DOMString, readonly
El identificador de sistema de esta notación. Si el identificador de sistema no ha sido especificado, eso es null. Esto puede o no ser un URI absoluto.
Interfaz Entity

Esta interfaz representa una entidad conocida, analizada o no, en un documento XML. Obsérvese que esto modeliza la entidad en si misma no la declaración de la entidad.

El atributo nodeName que está heredado de Node contiene el nombre de la entidad.

Un procesador XML puede optar por expandir completamente las entidades antes de pasar el modelo estructurado al DOM; en este caso no habrá ningún nodo EntityReference en el árbol del documento.

XML no obliga a que un procesador XML no validado lea y procese las declaraciones de entidades hechas en el subconjunto externo o declaradas en entidades paramétricas externas. Esto significa que algunas clases de aplicaciones no necesitan expandir las entidades analizadas declaradas en el subconjunto externo, y que el valor por el que se reemplaza la entidad puede no estar disponible. Cuando el texto de reemplazo está disponible, la lista de nodos hijos del nodo Entity correspondiente representa la estructura del valor de reemplazo. En caso contrario, la lista de hijos está vacía.

El Nivel 3 de DOM no soporta la edición de los nodos Entity; si un usuario quiere realizar cambios en el contenido de un Entity, cada nodo EntityReference relacionado ha de ser reemplazado en el modelo de estructura por un clon de los contenidos en Entity, y entonces los cambios deseados deben realizarse en cada uno de esos clones. Todos los nodos Entity y sus descendentes son de solo lectura.

Un nodo Entity no tiene ningún padre.

Nota: Si al entidad contiene prefijo de espacio de nombre ilimitado, el URI de espacio de nombre del nodo correspondiente en el subárbol del nodo Entity es null. Esto mismo es cierto para nodos EntityReference que se refieran a esta entidad, cuando estas son creadas utilizando el método createEntityReference de la interfaz Document.


Definición IDL
interfaz Entity : Node {
  readonly attribute DOMString       publicId;
  readonly attribute DOMString       systemId;
  readonly attribute DOMString       notationName;
  // Introducido en DOM Nivel 3:
  readonly attribute DOMString       inputEncoding;
  // Introducido en DOM Nivel 3:
  readonly attribute DOMString       xmlEncoding;
  // Introducido en DOM Nivel 3:
  readonly attribute DOMString       xmlVersion;
};

Atributos
inputEncoding of type DOMString, readonly, introducido en DOM Nivel 3
Un atributo que especifica la codificación usada para esta entidad en el momento del análisis, cuando esto es una entidad externa analizada. Esto es null si esta es una entidad del subconjunto externo o si es desconocida.
notationName of type DOMString, readonly
Para entidades no analizadas, el nombre de la notación para la entidad. Para entidades analizadas, esto es null.
publicId of type DOMString, readonly
El identificador público asociado con la entidad si es especificado, y null en caso contrario.
systemId of type DOMString, readonly
El identificador de sistema asociado con la entidad si está especificado, y null en caso contrario. Esto puede ser un URI absoluto o no.
xmlEncoding of type DOMString, readonly, introducido en DOM Nivel 3
Una especificación de atributo, como parte de la declaración del texto, de la codificación de esta entidad, cuando esta es una entidad externa analizada. Esto es null en caso contrario.
xmlVersion of type DOMString, readonly, introducido en DOM Nivel 3
Una especificación de atributo, como parte de la declaración de texto, del número de versión de esta entidad, cuando esta es una entidad externa analizada. Esto es null en caso contrario.
Interfaz EntityReference

Los nodos EntityReference pueden ser utilizados para representar una referencia de una entidad en el árbol de nodos. Obsérvese que las referencias de caracteres y las referencias a entidades predefinidas son consideradas expandidas por el procesador HTML o XML de modo que los caracteres son representados por sus equivalentes Unicode más que por una referencia de entidades. Además, el procesador XML puede expandir referencias a entidades mientras construye el Document, en lugar de proporcionar nodos EntityReference. Si lo que hace es proporcionar tales nodos, entonces para un nodo EntityReference que represente una referencia a una entidad conocida existe un Entity, y el sub-árbol del nodo EntityReference es una copia del sub-árbol del nodo Entity . Sin embargo, lo anterior no puede ser verdadero cuando una entidad no es obligada a contener un prefijo de espacio de nombre. En tal caso, debido al prefijo de espacio de nombre la resolución depende de donde es la referencia de la entidad, los descendentes del nodo EntityReference pueden ser obligados a un URIs de espacio de nombre diferente. Cuando un nodo EntityReference representa una referencia a una entidad desconocida, el nodo no tiene hijos y su valor de reemplazo, cuando utiliza por ejemplo Attr.value, está vacío.

Como con los nodos Entity, los nodos EntityReference y todos sus descendentes son de solo lectura.

Nota: Los nodos EntityReference pueden causar problemas en la normalización del contenido de elementos y en el valor de atributos cuando, como en XML 1.0 y el esquema de XML, la normalización se realiza después de la referencia de la entidad son expandidos.


Definición IDL
interfaz EntityReference : Node {
};

Interfaz ProcessingInstruction

La interfaz ProcessingInstruction representa una "instrucción de procesamiento", utilizada en XML como medio de mantener información específica del procesador en el texto del documento.

No se realiza una verificación del contenido de la instrucción de procesamiento y por lo tanto es posible tener secuencia de caracteres "?>" en el documento, los cuales son ilegales en la instrucción de procesamiento por la sección 2.6 de [XML 1.0]. La presencia de esta secuencia de caracteres debe generar un error grave durante la serialización.


Definición IDL
interfaz ProcessingInstruction : Node {
  readonly attribute DOMString       target;
           attribute DOMString       data;
                                        // raises(DOMException) on setting

};

Atributos
data of type DOMString
El contenido de esta instrucción de procesamiento. Este va desde el primer carácter después del destino que no es espacio en blanco hasta el carácter que precede inmediatamente a ?>.
Excepciones al establecer

DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada cuando el nodo es de solo lectura.

target of type DOMString, readonly
El destino de esta instrucción de procesamiento. XML define a este como la primera palabra ("token") que sigue al código que inicia la instrucción de procesamiento.