EntityReference (W3C DOM Core object)

Spec
Version Depr. Parent
DOM1 No Node
Browser support (more…)
IE5.5+ FF3 SA1.3+ OP9.5
Full None Full None

Example

var reference = document.createEntityReference('amp');

The example above creates an entity reference called amp which would be written in HTML as & and decodes as the entity &.

Description

The EntityReference interface inherits from Node, and represents an unexpanded entity reference (eg. amp). EntityReference nodes may appear in the DOM when an entity reference appears in the source document, or when inserting new entity references. Entity nodes themselves are readonly, so the EntityReference interface is used to create or modify them.

The DOM does not require an implementation to expand external entities, hence the replacement value of an entity reference may not be available; if it is available it will appear in the childNodes collection of the EntityReference.

Conversely, an implementation may choose to expand all entities before building the DOM tree, in which case there will be no EntityReference nodes in the document at all, only Entity nodes. In practise, this is what happens in all tested browsers.

An EntityReference node can have Element, ProcessingInstruction, Comment, Text, CDATASection and other EntityReference nodes as children.

Compatibility

Internet Explorer Firefox Safari Opera
5.5 6.0 7.0 1.5 2.0 3.0 1.3 2.0 3.0 9.0 9.5
Full Full Full None None None Full Full Full None None

In all browsers, EntityReference nodes are expanded before building or modifying the DOM tree, and therefore never appear in a document.

So this interface is only testable in browsers which fully implement the createEntityReference method — Internet Explorer in XML and Safari. Since this method should only work in XML (and should throw an exception in HTML) this is taken to mean that the interface is fully supported, in both cases. However the method itself has support caveats which are documented separately (see createEntityReference).

User-contributed notes

There are no comments yet.

Related Products