REC-DOM-Level-1-19981001


Nota: Este documento es parte de una traducción al castellano de la Recomendación del W3C "Document Object Model (DOM) Level 1" (más información). Puede consultar la versión original del mismo. Para cualquier comentario o corrección acerca de la traducción póngase en contacto con el traductor en jrpozo arroba conclase punto net. Gracias por su colaboración.
Véase el Aviso de copyright de la traducción.

1. Modelo de Objetos del Documento (Núcleo), Nivel 1

Editores
Mike Champion, ArborText (a partir del 20 de noviembre de 1997)
Steve Byrne, JavaSoft (hasta el 19 de noviembre de 1997)
Gavin Nicol, Inso EPS
Lauren Wood, SoftQuad, Inc.

Tabla de contenidos


1.1. Visión general de las Interfaces del Núcleo del DOM

Esta sección define un conjunto mínimo de objetos e interfaces para acceder y manipular objetos del documento. La funcionalidad especificada en esta sección (la funcionalidad del Núcleo) debería ser suficiente para permitir a los desarrolladores de programas y a los autores de scripts web acceder y manipular contenido HTML y XML analizado dentro de productos conformes. El API del Núcleo del DOM permite también poblar un objeto Document usando únicamente llamadas al API DOM; la creación del esqueleto del documento Document y su almacenamiento persistente se deja al producto que implementa el API DOM.

1.1.1. El Modelo de Estructura del 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 hijos de varios tipos, mientras que otros son nodos hoja que no pueden tener nada bajo ellos en la estructura del documento. Los tipos de nodo, y los tipos de nodo que éstos pueden tener como hijos, son los siguientes:

El DOM especifica además una interfaz NodeList para manejar listas ordenadas de Nodes, como los hijos de un Node o los elementos devueltos por el método Element.getElementsByTagName, 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. En el DOM, NodeLists y NamedNodeMaps están "vivos", es decir, los cambios en la estructura subyacente del documento se reflejan en todos los NodeLists y NamedNodeMaps 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 elemento (o los elimina, o los 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 del árbol se reflejan en todas las referencias a ese Node desde los NodeLists y los NamedNodeMaps.

1.1.2. Gestión de Memoria

La mayoría de los APIs definidos en esta especificación son interfaces más que clases. Eso significa que una implementación concreta sólo necesita exponer los métodos con los nombres definidos y la operación especificada, y 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 nuevas con 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 ("factory" methods) que creen ejemplares de objetos que implementen las diferentes interfaces. En el Nivel 1 del DOM, 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.

El Nivel 1 del API DOM no define una manera estándar de crear objetos DOMImplementation ni Document; cada implementación del DOM debe proporcionar algún modo propietario de arrancar estas interfaces DOM, y después todos los demás objetos pueden construirse con los métodos Create de Document (o con cualesquiera otros métodos que resulten convenientes).

Los APIs del Núcleo del DOM están diseñados para ser compatibles con un amplio espectro de lenguajes, incluyendo tanto los lenguajes de scripts de uso general como los lenguajes más complejos usados principalmente por programadores profesionales. Así, los 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 memoria en absoluto, a aquellas (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 estas 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 diseñados por el Grupo de Trabajo DOM para los lenguajes ECMAScript y Java requiere ningún método de gestión de memoria, pero los enlaces con el DOM que se creen para otros lenguajes (especialmente C o C++) probablemente necesitarán tal soporte. Estas extensiones serán responsabilidad de aquellos que adapten el API DOM a un lenguaje específico, no del Grupo de Trabajo 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 OMG como ECMAScript tienen limitaciones significativas a la hora de eliminar las ambigüedades en los nombres provenientes de espacios de nombres 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, nosotros usamos el nombre de método "remove" ("retirar") cuando el método cambia el modelo estructural, y el nombre del método delete ("borrar") cuando el método suprime algo dentro del modelo de estructura. La cosa que se borra no se devuelve. La cosa que se retira puede devolverse, 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/XHTML: uno que 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 necesidad de especificaciones explícitas de tipo o casts (en Java y otros lenguajes como C), o de llamadas a interfaces de petición en entornos COM. Estas operaciones son bastante costosas en Java y COM, y el DOM puede 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 el 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 necesarios en otras interfaces. (Por supuesto, cuando el análisis orientado a objetos 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 nodeName (nombre de nodo) en la interfaz Node, sigue habiendo un atributo tagName en la interfaz Element; ambos atributos deben contener el mismo valor, pero el Grupo de Trabajo considera que vale la pena soportar ambos, dadas las diferentes exigencias que debe satisfacer el API DOM.

1.1.5. El tipo DOMString

Para asegurar la interoperabilidad, el DOM especifica el tipo DOMString como sigue:

Nota: A fecha de agosto de 1998, la especificación del IDL del OMG incluía un tipo wstring. Sin embargo, esa definición no satisfacía las exigencias de interoperabilidad del API DOM, ya que para definir la anchura de un carácter se basaba en una negociación de la codificación.

1.1.6. Distinción entre mayúsculas y minúsculas en el DOM

El DOM tiene muchas interfaces que implican un emparejamiento de cadenas. Los procesadores de HTML generalmente asumen una normalización de nombres en mayúsculas (con menor frecuencia en minúsculas) para cosas tales como elementos, mientras que XML distingue explícitamente entre mayúsculas y minúsculas. Para los propósitos del DOM, el emparejamiento de cadenas se realiza puramente por comparación binaria entre las unidades de 16 bits de los DOMString. Así, el DOM supone que cualquier normalización tiene lugar en el procesador antes de que se construyan las estructuras del DOM.

Esto lleva a plantearse la cuestión de qué normalizaciones tienen lugar exactamente. El Grupo de Trabajo I18N del W3C está actualmente en vías de definir exactamente qué normalizaciones son necesarias para las aplicaciones que implementen el DOM.

1.2. Interfaces Fundamentales

Las interfaces contenidas en esta sección se consideran fundamentales, y deben ser completamente implementadas por todas las implementaciones conformes con el DOM, incluyendo todas las implementaciones del DOM HTML.

Excepción DOMException

Las operaciones del DOM sólo provocan excepciones en circunstancias "excepcionales", es decir, cuando una operación es imposible de realizar (bien por razones lógicas, porque se han perdido datos, o porque la implementación se ha vuelto inestable). En general, los métodos del DOM devuelven códigos de error específicos en situaciones ordinarias de procesamiento, tales como errores de exceso de rango al usar NodeList.

Las implementaciones pueden provocar otras excepciones en otras circunstancias. Por ejemplo, las implementaciones pueden provocar excepciones dependientes de la implementación si se pasa un argumento null.

Algunos lenguajes y sistemas de objetos no soportan el concepto de excepción. Para tales sistemas las condiciones de error pueden indicarse usando mecanismos nativos para la indicación de errores. Por ejemplo, para algunas implementaciones los métodos pueden devolver códigos de error similares a los enumerados en las descripciones de los métodos correspondientes.

Definición IDL
exception DOMException {
  unsigned short   code;
};

// ExceptionCode
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;

Grupo de definiciones ExceptionCode

Un entero que indica el tipo de error generado.

Constantes Definidas
INDEX_SIZE_ERR

Si el índice o el tamaño son negativos, o mayores que el valor permitido

DOMSTRING_SIZE_ERR

Si el tamaño del texto especificado no cabe en un DOMString

HIERARCHY_REQUEST_ERR

Si se inserta un nodo en algún sitio al que no pertenece

WRONG_DOCUMENT_ERR

Si se usa un nodo en un documento diferente del que lo creó (que no lo soporte)

INVALID_CHARACTER_ERR

Si se especifica un carácter inválido, como por ejemplo en un nombre.

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

NOT_FOUND_ERR

Si se intenta hacer referencia a un nodo en un contexto en que no existe

NOT_SUPPORTED_ERR

Si la implementación no soporta el tipo de objeto requerido

INUSE_ATTRIBUTE_ERR

Si se intenta añadir un atributo que ya está siendo usado en algún otro lugar

Interfaz DOMImplementation

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

El Nivel 1 del DOM no especifica ningún modo de crear un ejemplar de documento, y por tanto la creación de documentos es una operación específica de cada implementación. Se espera que los Niveles futuros del DOM proporcionen métodos para crear documentos directamente.

Definición IDL
interface DOMImplementation {
  boolean                   hasFeature(in DOMString feature, 
                                       in DOMString version);
};

Métodos
hasFeature
Comprueba si la implementación del DOM implementa un característica específica.
Parámetros
feature

El nombre del paquete de la característica a comprobar. En el Nivel 1, los valores legales son "HTML" y "XML" (no se distingue entre mayúsculas y minúsculas).

version

Este es el número de versión del nombre del paquete a comprobar. En el Nivel 1, versión 1.0, es la cadena "1.0". Cuando no se especifica la versión, si se soporta cualquier versión de la característica se devolverá el valor true.

Valor de Retorno
true si la característica está implementada en la versión especificada, false en caso contrario.

Este método no provoca 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 por ejemplo 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 puede 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 hijos del DocumentFragment sean movidos a la lista de hijos de este nodo.

Los hijos de un 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 varios nodos superiores). Por ejemplo, un DocumentFragment podría tener un único hijo y ese nodo hijo podría ser un nodo Text. Este modelo de estructura no representaría ni a un documento HTML ni a un documento XML bien formado.

Cuando se inserta un DocumentFragment dentro de un Document (o en cualquier otro nodo Node que pueda tener hijos), son los hijos del DocumentFragment los que se insertan en el Node, y no el DocumentFragment. 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 insertBefore() ("insertar antes") y appendChild() ("añadir hijo").

Definición IDL
interface 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
interface Document : Node {
  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);
};

Atributos
doctype
La Declaración del Tipo del Documento (ver DocumentType) asociada con este documento. Para documentos HTML así como para documentos XML sin una declaración del tipo de documento esto devuelve null. El Nivel 1 del DOM no soporta la edición de la Declaración del Tipo de Documento, y por tanto docType no puede modificarse de ningún modo.
implementation
El objeto DOMImplementation que manipula este documento. Una aplicación DOM puede usar objetos de varias implementaciones.
documentElement
Este es un atributo de conveniencia que permite acceder directamente al nodo hijo que es el elemento raíz del documento. Para documentos HTML, este es el elemento con tagName "HTML".
Métodos
createElement
Crea un elemento del tipo especificado. Obsérvese que el ejemplar devuelto implementa la interfaz Element, de modo que se pueden especificar directamente los atributos del objeto devuelto. Además, si hay atributos conocidos con valores por defecto, los nodos Attr que los representan se crean y adjuntan automáticamente al elemento.
Parámetros
tagName

El nombre del tipo de elemento a crear. Para XML, se distingue entre mayúsculas y minúsculas. Para HTML, se puede dar el tagName en mayúsculas o en minúsculas, pero la implementación DOM debe transformarlo en la forma canónica en mayúsculas.

Valor de Retorno
Un nuevo objeto Element.
Excepciones
DOMException

INVALID_CHARACTER_ERR: Provocada si el nombre especificado contiene un carácter inválido.


createDocumentFragment
Crea un objeto DocumentFragment vacío.
Valor de Retorno
Un nuevo DocumentFragment.

Este método no tiene parámetros.
Este método no provoca excepciones.
createTextNode
Crea un nodo Text al que se le da la cadena especificada.
Parámetros
data

Los datos para el nodo.

Valor de Retorno
El nuevo objeto Text.

Este método no provoca excepciones.
createComment
Crea un nodo Comment al que se la da la cadena especificada.
Parámetros
data

Los datos para el nodo.

Valor de Retorno
El nuevo objeto Comment.

Este método no provoca excepciones.
createCDATASection
Crea un nodo CDATASection cuyo valor es la cadena especificada.
Parámetros
data

Los datos para los contenidos de la sección CDATASection.

Valor de Retorno
El nuevo objeto CDATASection.
Excepciones
DOMException

NOT_SUPPORTED_ERR: Provocada si el documento es un documento HTML.


createProcessingInstruction
Crea un nodo ProcessingInstruction al que se le dan las cadenas de nombre y datos especificadas.
Parámetros
target

La parte destino de la instrucción de procesamiento.

data

Los datos para el nodo.

Valor de Retorno
El nuevo objeto ProcessingInstruction.
Excepciones
DOMException

INVALID_CHARACTER_ERR: Provocada si se especifica un carácter inválido.

NOT_SUPPORTED_ERR: Provocada si el documento es un documento HTML.


createAttribute
Crea un atributo Attr con el nombre dado. Obsérvese que el ejemplar Attr puede ser establecido a continuación en un Element usando el método setAttribute.
Parámetros
name

El nombre del atributo.

Valor de Retorno
Un nuevo objeto Attr.
Excepciones
DOMException

INVALID_CHARACTER_ERR: Provocada si el nombre especificado contiene un carácter inválido.


createEntityReference
Crea un objeto EntityReference. Además, si la entidad referenciada es conocida, la lista de hijos del nodo EntityReference se hace igual a la del nodo Entity correspondiente.
Parámetros
name

El nombre de la entidad a referenciar.

Valor de Retorno
El nuevo objeto EntityReference.
Excepciones
DOMException

INVALID_CHARACTER_ERR: Provocada si el nombre especificado contiene un carácter inválido.

NOT_SUPPORTED_ERR: Provocada si el documento es un documento HTML.


getElementsByTagName
Devuelve una lista NodeList de todos los Elements que tengan un nombre de etiqueta dado en el orden en que se encontrarían al realizar un recorrido preordenado (preorder traversal) del árbol del Document.
Parámetros
tagname

El nombre de la etiqueta a emparejar. El valor especial "*" se empareja con todas las etiquetas.

Valor de Retorno
Un nuevo objeto NodeList que contiene todos los Elements concordantes.

Este método no provoca excepciones.
Interfaz Node

La interfaz Node es el tipo de datos primario del Modelo de Objetos del Documento. Representa un nodo individual del árbol del documento. Si bien 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 estos nodos se provoca una excepción DOMException.

Los atributos nodeName, nodeValue y attributes se han incluido como un mecanismo para obtener información sobre el nodo sin tener que realizar una conversión explícita a la interfaz específica derivada. En los casos en que no haya una transformación obvia para estos atributos para un tipo de nodo nodeType específico (p.ej., nodeValue para un elemento o attributes para un comentario), se devuelve null. Obsérvese que las interfaces especializadas pueden contener mecanismos adicionales y más convenientes para obtener y establecer la información relevante.

Definición IDL
interface 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;
  readonly attribute  Document             ownerDocument;
  Node                      insertBefore(in Node newChild, 
                                         in Node refChild)
                                         raises(DOMException);
  Node                      replaceChild(in Node newChild, 
                                         in Node oldChild)
                                         raises(DOMException);
  Node                      removeChild(in Node oldChild)
                                        raises(DOMException);
  Node                      appendChild(in Node newChild)
                                        raises(DOMException);
  boolean                   hasChildNodes();
  Node                      cloneNode(in boolean deep);
};

Grupo de definiciones de NodeType

Un entero que indica qué tipo de nodo es éste.

Constantes Definidas
ELEMENT_NODE

El nodo es un Element.

ATTRIBUTE_NODE

El nodo es un Attr.

TEXT_NODE

El nodo es un nodo Text node.

CDATA_SECTION_NODE

El nodo es una sección CDATASection.

ENTITY_REFERENCE_NODE

El nodo es una EntityReference.

ENTITY_NODE

El nodo es una Entity.

PROCESSING_INSTRUCTION_NODE

El nodo es una ProcessingInstruction.

COMMENT_NODE

El nodo es un Comment.

DOCUMENT_NODE

El nodo es un Document.

DOCUMENT_TYPE_NODE

El nodo es un DocumentType.

DOCUMENT_FRAGMENT_NODE

El nodo es un DocumentFragment.

NOTATION_NODE

El nodo es un nodo Notation.

Los valores nodeName, nodeValue y attributes varían según el tipo de nodo según se especifica a continuación:
nodeNamenodeValueattributes
Elementnombre de etiqueta (tagName)nullNamedNodeMap
Attrnombre del atributovalor del atributonull
Text#textcontenido del nodo de textonull
CDATASection#cdata-sectioncontenido de la Sección CDATAnull
EntityReferencenombre de la entidad referenciadanullnull
Entitynombre de la entidadnullnull
ProcessingInstructiondestino (target)contenido completo excluyendo el destinonull
Comment#commentcontenido del comentarionull
Document#documentnullnull
DocumentTypenombre del tipo de documentonullnull
DocumentFragment#document-fragmentnullnull
Notationnombre de la notaciónnullnull

Atributos
nodeName
El nombre de este nodo, dependiendo de su tipo; ver la tabla precedente.
nodeValue
El valor de este nodo, dependiendo de su tipo; ver la tabla precedente.
Excepciones al establecer
DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada cuando es de sólo lectura.

Excepciones al leer
DOMException

DOMSTRING_SIZE_ERR: Provocada cuando devolvería más caracteres de los que cabrían en una variable DOMString de la plataforma de la implementación.

nodeType
Un código que representa el tipo del objeto subyacente, según se define arriba.
parentNode
El padre de este nodo. Todos los nodos, excepto Document, DocumentFragment y Attr, pueden tener un padre. Sin embargo, si un nodo acaba de ser creado y aún no ha sido añadido al árbol, o si ha sido retirado del árbol, esto es null.
childNodes
Una lista NodeList que contiene todos los hijos de este nodo. Si no hay hijos, esto es un NodeList que no contiene ningún nodo. El contenido del NodeList devuelto está "vivo", en el sentido de que, por ejemplo, los cambios en los hijos del objeto nodo a partir del cual se crearon se reflejan inmediatamente en los nodos devueltos por los métodos de acceso de NodeList; no es una fotografía estática del contenido del nodo. Esto se cumple para todas las listas NodeList, incluyendo las que devuelve el método getElementsByTagName.
firstChild
El primer hijo de este nodo. Si no existe tal nodo, esto devuelve null.
lastChild
El último hijo de este nodo. Si no existe tal nodo, esto devuelve null.
previousSibling
El nodo que precede inmediatamente a este nodo. Si no existe tal nodo, esto devuelve null.
nextSibling
El nodo que sigue inmediatamente a este nodo. Si no existe tal nodo, esto devuelve null.
attributes
Un NamedNodeMap que contiene los atributos de este nodo (si se trata de un Element), o null en cualquier otro caso.
ownerDocument
El objeto Document asociado a este nodo. Esto también es el objeto Document usado para crear nuevos nodos. Cuando este nodo es un Document esto es null.
Métodos
insertBefore
Inserta el nodo newChild antes del nodo hijo existente refChild. Si refChild es null, newChild se inserta al final de la lista de hijos.

Si newChild es un objeto DocumentFragment, se insertan todos sus hijos, en el mismo orden, antes de refChild. Si newChild ya está en el árbol, se retira primero.

Parámetros
newChild

El nodo a insertar.

refChild

El nodo de referencia, es decir, el nodo antes del cual debe insertarse el nuevo nodo.

Valor de Retorno
El nodo insertado.
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 ascendientes de este nodo.

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

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.

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


replaceChild
Reemplaza el nodo hijo oldChild con newChild en la lista de hijos, y devuelve el nodo oldChild. Si el newChild ya está en el árbol, se retira primero.
Parámetros
newChild

El nuevo nodo a poner en la lista de hijos.

oldChild

El nodo que se va a reemplazar en la lista.

Valor de Retorno
El nodo reemplazado.
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 introducir es uno de los ascendientes de este nodo.

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

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.

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


removeChild
Retira el nodo hijo indicado por oldChild de la lista de hijos, y lo devuelve como valor de retorno.
Parámetros
oldChild

El nodo a retirar.

Valor de Retorno
El nodo retirado.
Excepciones
DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.

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


appendChild
Añade el nodo newChild al final de la lista de hijos de este nodo. Si el newChild ya está en el árbol, se retira primero.
Parámetros
newChild

El nodo a añadir.

Si es un objeto DocumentFragment, se mueven todos los contenidos del fragmento de documento a la lista de hijos de este nodo

Valor de Retorno
El nodo añadido.
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 añadir es uno de los ascendientes de este nodo.

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

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


hasChildNodes
Este es un método de conveniencia que permite determinar fácilmente si un nodo tiene algún hijo.
Valor de Retorno
true si el nodo tiene algún hijo, false si el nodo no tiene ningún hijo.

Este método no tiene parámetros.
Este método no provoca excepciones.
cloneNode
Devuelve una réplica de este nodo, es decir, sirve como constructor genérico de copia para nodos. El nodo réplica no tiene padre (parentNode devuelve null).

Cuando se clona un Element se copian todos los atributos y sus valores, incluyendo aquéllos generados por el procesador XML para representar los atributos con valores por defecto, pero este método no copia ningún texto de su contenido a menos que se trate de clon profundo, ya que el texto está contenido en un nodo hijo de tipo Text. La clonación de cualquier otro tipo de nodo devuelve simplemente una copia de este nodo.

Parámetros
deep

Si es true, se clona recursivamente el sub-árbol bajo el nodo especificado. Si es false, se clona sólo el nodo en sí (y sus atributos si es un Element).

Valor de Retorno
El nodo réplica.

Este método no provoca excepciones.
Interfaz NodeList

La interfaz NodeList proporciona la abstracción de un conjunto ordenado de nodos, sin definir o restringir cómo se implementa este conjunto.

Se puede acceder a los objetos de un NodeList a través de un índice entero que comienza en el 0.
Definición IDL
interface NodeList {
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        length;
};

Métodos
item
Devuelve el objeto del conjunto cuyo índice es index. Si index es mayor o igual que el número de nodos de la lista, esto devuelve null.
Parámetros
index

Índice dentro del conjunto.

Valor de Retorno
El nodo en la posición index de la lista NodeList, o null si aquél no es un índice válido.

Este método no provoca excepciones.
Atributos
length
El número de nodos de la lista. El rango de índices válidos de nodos hijos va desde 0 hasta length-1, ambos inclusive.
Interfaz NamedNodeMap

Los objetos que implementan la intertaz NamedNodeMap se usan para representar conjuntos de nodos a los que se puede acceder por su nombre. Obsérvese que NamedNodeMap no se hereda de un NodeList; en efecto, los NamedNodeMaps no se mantienen en ningún orden particular. También se puede acceder a los objetos contenidos en un objeto que implemente NamedNodeMap mediante un índice ordinal, pero esto es simplemente para permitir la enumeración conveniente de los contenidos de un NamedNodeMap, y no implica que el DOM especifique un orden para estos nodos.

Definición IDL
interface 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;
};

Métodos
getNamedItem
Obtiene el nodo especificado por el nombre name.
Parámetros
name

El nombre del nodo a obtener.

Valor de Retorno
Un Node (de cualquier tipo) con el nombre especificado, o null si el nombre especificado no identificó a ningún nodo del conjunto.

Este método no provoca excepciones.
setNamedItem
Añade un nodo usando su atributo nodeName.

Como el atributo nodeName se utiliza para determinar el nombre bajo el cual debe almacenarse el nodo, no pueden almacenarse varios nodos de ciertos tipos (aquellos que tengan un valor de cadena "especial") ya que los nombres entrarían en conflicto. Se considera que esto es preferible a permitir que se pueda dar un alias a los nodos.

Parámetros
arg

Un nodo a almacenar en un mapa de nodos con nombre. El nodo será después accesible usando el valor del atributo nodeName del nodo. Si ya hay algún nodo con ese nombre en el mapa, se reemplaza por el nuevo.

Valor de Retorno
Si el nuevo Node reemplaza a algún nodo existente con el mismo nombre, se devuelve el Node existente previamente; en caso contrario se devuelve null.
Excepciones
DOMException

WRONG_DOCUMENT_ERR: Provocada si arg fue creado a partir de un documento diferente del que creó al NamedNodeMap.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este NamedNodeMap es de sólo lectura.

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


removeNamedItem
Retira un nodo especificado por su nombre. Si el nodo retirado es un Attr con un valor por defecto se reemplaza inmediatamente. Cuando este mapa NamedNodeMap contiene los atributos asociados a un elemento, tal y como se devuelve por el atributo attributes de la interfaz Node, si se sabe que el atributo retirado tiene un valor por defecto, inmediatamente aparece un atributo que contiene el valor por defecto.
Parámetros
name

El nombre del nodo a retirar.

Valor de Retorno
El nodo retirado del mapa si existe algún nodo con el nombre especificado.
Excepciones
DOMException

NOT_FOUND_ERR: Provocada si no hay ningún nodo con el nombre name en el mapa.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este NamedNodeMap es de sólo lectura.


item
Devuelve el objeto del mapa cuyo índice es index. Si index es mayor o igual que el número de nodos del mapa, esto devuelve null.
Parámetros
index

Índice dentro del mapa.

Valor de Retorno
El nodo en la posición index dentro del NamedNodeMap, o null si aquél no es un índice válido.

Este método no provoca excepciones.
Atributos
length
El número de nodos del mapa. El rango de índices válidos de nodos hijos va desde 0 hasta length-1, ambos inclusive.
Interfaz CharacterData

La interfaz CharacterData extiende a Node con un conjunto de atributos y métodos para acceder a datos de caracteres en el DOM. Por claridad se define este conjunto aquí en lugar de hacerlo en cada objeto que utilice estos atributos y métodos. No hay ningún objeto del DOM que corresponda directamente a CharacterData, aunque Text y otros heredan su interfaz de él. Todos los offsets de esta interfaz comienzan desde 0.

Definición IDL
interface 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
Los datos de caracteres del nodo que implementa esta interfaz. La implementación DOM puede no poner límites arbritrarios en la cantidad de datos que pueden almacenarse 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 estos casos, el usuario puede llamar a substringData para obtener los datos en bloques de tamaño apropiado.
Excepciones al establecer
DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada cuando el nodo es de sólo lectura.

Excepciones al leer
DOMException

DOMSTRING_SIZE_ERR: Provocada cuando se devolverían más caracteres de los que caben en una variable DOMString en la plataforma de la implementación.

length
El número de unidades de 16 bits que están disponibles a través de data y del método substringData descrito abajo. Esto puede ser el valor cero, es decir, los nodos CharacterData pueden estar vacíos.
Métodos
substringData
Extrae una subcadena de datos del nodo.
Parámetros
offset

Offset del inicio de la subcadena a extraer.

count

El número de unidades de 16 bits a extraer.

Valor de Retorno
La subcadena especificada. Si la suma de offset y count excede de la longitud length, entonces se devuelven todas las unidades de 16 bits hasta el final de los datos.
Excepciones
DOMException

INDEX_SIZE_ERR: Provocada si el offset especificado es negativo o mayor que el número de unidades de 16 bits de data, o si la cuenta count especificada es negativa.

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


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

El DOMString a añadir.

Excepciones
DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


Este método no devuelve nada.
insertData
Inserta una cadena en el offset de unidades de 16 bits especificado.
Parámetros
offset

El offset de unidades de 16 bits en el cual insertar la cadena.

arg

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 bits de data.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


Este método no devuelve nada.
deleteData
Borra una subcadena de unidades de 16 bits del nodo. En caso de éxito, data y length reflejan el cambio.
Parámetros
offset

El offset a partir del cual borrar las unidades de 16 bits.

count

El número de unidades de 16 bits a borrar. Si la suma de offset y count excede de la longitud length, entonces se borran todas las unidades de 16 bits desde offset hasta el final de los datos.

Excepciones
DOMException

INDEX_SIZE_ERR: Provocada si el offset especificado es negativo o mayor que el número de unidades de 16 bits de data, o si la cuenta count especificada es negativa.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


Este método no devuelve nada.
replaceData
Reemplaza las unidades de 16 bits desde el offset especificado con la cadena especificada.
Parámetros
offset

El offset a partir del cual comenzar el reemplazamiento.

count

El número de unidades de 16 bits a reemplazar. Si la suma de offset y count excede de la longitud length, entonces se reemplazan todas las unidades de 16 bits hasta el final de los datos (es decir, el efecto es el mismo que el de una llamada al método remove con la misma subcadena, seguida de una invocación al método append).

arg

El DOMString por el que 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 bits de data, o si la cuenta count especificada es negativa.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


Este método no devuelve nada.
Interfaz Attr

La interfaz Attr representa un atributo de un objeto Element. Normalmente los valores permitidos para el atributo están definidos en la definición del tipo de documento.

Los objetos Attr heredan la interfaz Node, pero como en realidad no son nodos hijos del elemento al que describen, el DOM no los considera parte del árbol del documento. Así, los atributos de Node parentNode, previousSibling y nextSibling tiene un valor null para los objetos Attr. El 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 caracterí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 un valor a este atributo explícitamente, ese valor es el valor efectivo del atributo; en caso contrario, si hay una declaración para este 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. Obsérvese que el atributo nodeValue del ejemplar Attr también puede utilizarse para obtener la versión en forma de cadena del valor o valores del atributo.

En XML, en el cual el valor de un atributo puede contener referencias a entidades, los nodos hijos del nodo Attr proporcionan una representación en la cual las referencias a entidades no son expandidas. Estos nodos hijos pueden ser o bien nodos Text o bien nodos EntityReference. Como el tipo de atributo puede ser desconocido, no hay valores de atributos de tipo simbólico (tokenized attributes).

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

Atributos
name
Devuelve el nombre de este atributo.
specified
Si se dio un valor a este atributo explícitamente en el documento original, esto es true; en caso contrario, es false. Obsérvese que la implementación, y no el usuario, está al cargo de este atributo. Si el usuario cambia el valor del atributo (incluso si acaba teniendo el mismo valor que el valor por defecto) entonces el indicador specified se conmuta automáticamente a true. Para especificar de nuevo que el valor tenga el valor por defecto del DTD, el usuario debe borrar el atributo. La implementación dispondrá entonces un nuevo atributo con specified establecido en false y el valor por defecto (si existe).

En resumen:

  • Si se ha asignado un valor al atributo en el documento, entonces specified es true, y el valor es el valor asignado.
  • Si no se ha asignado un valor al atributo en el documento y tiene un valor por defecto en el DTD, entonces specified es false, y el valor es el valor por defecto en el DTD.
  • Si no se ha asignado un valor al atributo en el documento y tiene un valor de #IMPLIED en el DTD, entonces el atributo no aparece en el modelo de estructura del documento.
value
Cuando se lee, se devuelve el valor del atributo como una cadena. Las referencias a entidades generales y de caracteres se reemplazan por sus valores.

Cuando se establece, esto crea un nodo Text con los contenidos no analizados de la cadena.

Excepciones al establecer
DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada cuando el nodo es de sólo lectura.

Interfaz Element

La gran mayoría de los objetos (aparte del texto) que encuentran los autores cuando recorren un documento son con mucho nodos Element. Imaginemos el siguiente documento XML:


<elementoEjemplo id="demo">
  <subelemento1/>
  <subelemento2><subsubelemento1/></subelemento2>
</elementoEjemplo>  

Si lo representamos usando el DOM, el nodo superior es un nodo Element para "elementoEjemplo", el cual contiene dos nodos Element hijos, uno para "subelemento1" y otro para "subelemento2". "subelemento1" no contiene nodos hijos.

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.

Definición IDL
interface 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);
  void                      normalize();
};

Atributos
tagName
El nombre del elemento. 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

El nombre del atributo a obtener.

Valor de Retorno
El valor Attr en forma de cadena, o la cadena vacía si el atributo no tiene un valor especificado o por defecto.

Este método no provoca excepciones.
setAttribute
Añade un nuevo atributo. Si ya hay presente en el elemento un atributo con ese nombre, su valor se cambia al del parámetro value. Este valor es una cadena simple, 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) se trata 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 debe 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.
Parámetros
name

El nombre del atributo a crear o modificar.

value

Valor a establecer, en forma de cadena.

Excepciones
DOMException

INVALID_CHARACTER_ERR: Provocada si el nombre especificado contiene un carácter inválido.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


Este método no devuelve nada.
removeAttribute
Retira un atributo especificado por su nombre. Si se sabe que el atributo retirado tiene un valor por defecto, aparece inmediatamente un atributo que contiene el valor por defecto.
Parámetros
name

El nombre del atributo a retirar.

Excepciones
DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


Este método no devuelve nada.
getAttributeNode
Obtiene un nodo Attr especificado por su nombre.
Parámetros
name

El nombre del atributo a obtener.

Valor de Retorno
El nodo Attr con el nombre de atributo especificado, o null si no existe tal atributo.

Este método no provoca excepciones.
setAttributeNode
Añade un nuevo atributo. Si ya hay presente en el elemento un atributo con ese nombre, se reemplaza con el nuevo.
Parámetros
newAttr

El nodo Attr a añadir a la lista de atributos.

Valor de Retorno
Si el atributo newAttr reemplaza a un atributo existente con el mismo nombre, se devuelve el nodo Attr previamente existente. En caso contrario, se devuelve null.
Excepciones
DOMException

WRONG_DOCUMENT_ERR: Provocada si newAttr fue creado a partir de un documento diferente del creó al elemento.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.

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


removeAttributeNode
Retira el atributo especificado.
Parámetros
oldAttr

El nodo Attr a retirar de la lista de atributos. Si el Attr retirado tiene un valor por defecto se reemplaza inmediatamente.

Valor de Retorno
El nodo Attr que ha sido retirado.
Excepciones
DOMException

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.

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


getElementsByTagName
Devuelve una lista NodeList de todos los elementos descendientes con un nombre de etiqueta dado, en el orden en que se encontrarían normalmente al realizar un recorrido en preorden del árbol del Element.
Parámetros
name

El nombre de la etiqueta a emparejar. El valor especial "*" se empareja con todas las etiquetas.

Valor de Retorno
Una lista de todos los nodos Element emparejados.

Este método no provoca excepciones.
normalize
Coloca a todos los nodos Text contenidos en todos los niveles del sub-árbol que queda por debajo de este Element en forma "normal", en la cual únicamente el código (p.ej., etiquetas, comentarios, instrucciones de procesamiento, secciones CDATA y referencias a entidades) separa a los nodos Text. Es decir, no hay nodos Text adyacentes. Esto puede utilizarse para asegurarse de que la vista DOM de un documento es la misma que si se guardara y recargara, y es útil cuando deben realizarse operaciones (tales como búsquedas XPointer) que dependen de una estructura de árbol particular del documento.
Este método no tiene parámetros.
Este método no devuelve nada.
Este método no provoca excepciones.
Interfaz Text

La interfaz Text 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 y que es el único hijo del elemento. Si hay código, se traduce en una lista de hijos del elemento.

Cuando se dispone un documento por primera vez a través del DOM, hay sólo un nodo Text por 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ían recordar que no hay manera de representar las separaciones entre estos nodos en XML o en HTML, de modo que, en general, no persistirán entre sesiones de edición del DOM. El método normalize() de Element combina estos objetos Text adyacentes en un solo nodo para cada bloque de texto; se recomienda hacer esto antes de emplear operaciones que dependan de una estructura particular del documento, como la navegación con XPointers.

Definición IDL
interface Text : CharacterData {
  Text                      splitText(in unsigned long offset)
                                      raises(DOMException);
};

Métodos
splitText
Divide este nodo Text en dos nodos Text por el offset especificado, manteniendo a ambos en el árbol como hermanos. Este nodo contendrá entonces todos los datos hasta el punto offset. Y el nuevo nodo Text, que se inserta como el siguiente hermano de este nodo, contendrá todo el contenido a partir del punto offset incluido.
Parámetros
offset

El offset de la unidad de 16 bits en el cual se producirá la división, comenzando en cero.

Valor de Retorno
El nuevo nodo Text.
Excepciones
DOMException

INDEX_SIZE_ERR: Provocada si el offset especificado es negativo o mayor que el número de unidades de 16 bits de data.

NO_MODIFICATION_ALLOWED_ERR: Provocada si este nodo es de sólo lectura.


Interfaz Comment

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.

Definición IDL
interface Comment : CharacterData {
};


1.3. Interfaces Extendidas

Las interfaces aquí definidas forman parte del Núcleo del Nivel 1 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. Como tales, las implementaciones de DOM sólo para HTML no necesitan tener objetos que implementen estas interfaces.

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 transformar todos los delimitadores en secuencias de escape.

El atributo DOMString del nodo Text contiene el texto que está contenido en la sección CDATA. Obsérvese que ésta puede contener caracteres que necesiten ser transformados en secuencias de escape fuera de secciones 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 una 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 Element.normalize().

Definición IDL
interface CDATASection : Text {
};

Interfaz DocumentType

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

El Nivel 1 del DOM no soporta la edición de los nodos DocumentType.

Definición IDL
interface DocumentType : Node {
  readonly attribute  DOMString            name;
  readonly attribute  NamedNodeMap         entities;
  readonly attribute  NamedNodeMap         notations;
};

Atributos
name
El nombre del DTD, es decir, el nombre que sigue inmediatamente a la palabra clave DOCTYPE.
entities
Un NamedNodeMap que contiene las entidades generales, tanto externas como internas, declaradas en el DTD. Los duplicados se descartan. Por ejemplo, en:
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY % baz "baz">
]>
<ex/>
la interfaz proporciona acceso a foo y a bar, pero no a baz. Todos los nodos de este mapa implementan además la interfaz Entity.

El Nivel 1 del DOM no soporta la edición de entidades, y por tanto las entities no pueden modificarse de ningún modo.

notations
Un NamedNodeMap que contiene las notaciones declaradas en el DTD. Los duplicados se descartan. Todos los nodos de este mapa implementan además la interfaz Notation.

El Nivel 1 del DOM no soporta la edición de notaciones, y por tanto las notations no pueden modificarse de ningún modo.

Interfaz Notation

Esta interfaz representa una notación declarada en el DTD. Una notación o bien declara, por el nombre, el formato de una entidad no analizada (ver la sección 4.7 de la especificación de XML 1.0), o bien 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). El atributo nodeName heredado de Node se hace igual al nombre declarado de la notación.

El Nivel 1 del DOM no soporta la edición de nodos Notation; son por lo tanto de sólo lectura.

Un nodo Notation no tiene ningún padre.

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

Atributos
publicId
El identificador público de esta notación. Si el identificador público no ha sido especificado, esto es null.
systemId
El identificador de sistema de esta notación. Si el identificador de sistema no ha sido especificado, esto es null.
Interfaz Entity

Esta interfaz representa una entidad, analizada o no analizada, en un documento XML. Obsérvese que esto modeliza la entidad en sí misma, no la declaración de la entidad. La modelización de la declaración Entity se ha dejado para un Nivel posterior de la especificación del DOM.

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 de estructura 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 validador 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 valor de reemplazamiento está disponible, la lista de nodos hijos del nodo Entity correspondiente representa la estructura del texto de reemplazamiento. En caso contrario, la lista de hijos está vacía.

La resolución de los hijos de la entidad (el valor de reemplazamiento) puede ser evaluada de manera laxa; se supone que las acciones del usuario (tales como llamar al método childNodes del nodo Entity) activan la evaluación.

El Nivel 1 del DOM no soporta la edición de nodos Entity. Si un usuario quiere hacer cambios en los contenidos de un objeto Entity, todos los nodos EntityReference relacionados se deben reemplazar en el modelo de estructura por un clon de los contenidos de la entidad, y los cambios deseados deben realizarse en cada uno de esos clones. Todos los descendientes de un nodo Entity son de sólo lectura.

Un nodo Entity no tiene ningún padre.

Definición IDL
interface Entity : Node {
  readonly attribute  DOMString            publicId;
  readonly attribute  DOMString            systemId;
  readonly attribute  DOMString            notationName;
};

Atributos
publicId
El identificador público asociado con la entidad, si está especificado. Si el identificador público no ha sido especificado, esto es null.
systemId
El identificador de sistema asociado con la entidad, si está especificado. Si el identificador de sistema no ha sido especificado, esto es null.
notationName
Para entidades no analizadas, el nombre de la notación de la entidad. Para entidades analizadas, esto es null.
Interfaz EntityReference

Los objetos EntityReference se pueden insertar en el modelo de estructura cuando hay una referencia a una entidad en el documento fuente, o cuando el usuario desea insertar una referencia a una entidad. Obsérvese que las referencias de caracteres y las referencias a entidades predefinidas se consideran expandidas por el procesador HTML o XML de modo que los caracteres son representados por su equivalente Unicode más que por una referencia de entidades. Además, el procesador XML puede expandir completamente las referencias a entidades mientras construye el modelo de estructura, en lugar de proporcionar objetos EntityReference. Si lo que hace es proporcionar estos objetos, entonces, para un nodo EntityReference dado, puede ser que no haya ningún nodo Entity que represente la entidad referenciada. Pero si existe tal Entity, entoces la lista de hijos del nodo EntityReference es la misma que la del nodo Entity. Como con el nodo Entity, todos los descendientes de EntityReference son de sólo lectura.

La resolución de los hijos de EntityReference (el valor de reemplazamiento de la entidad Entity referenciada) puede ser evaluada de manera laxa. Se supone que las acciones del usuario (como por ejemplo llamar al método childNodes del nodo EntityReference) activan la evaluación.

Definición IDL
interface 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.

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

Atributos
target
El destino de esta instrucción de procesamiento. XML define a éste como la primera palabra ("token") que sigue al código que inicia la instrucción de procesamiento.
data
El contenido de esta instrucción de procesamiento. Esto 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 sólo lectura.