Chapter 8 Working with XML Documents

Working with entities

In an XML document, an entity is a holder for some information. To use entities, you must first declare them, and then reference them. You declare entities in the DTD. The entities section of the XML document may be held separately or placed at the beginning of the document. Here is a simple DTD that specifies the two entities PQ and Logo.

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE Customers [
 <!ENTITY PQ "Province of Quebec">
 <!ENTITY Logo SYSTEM "nautilus.gif" NDATA GIF>
]>
<Customers><Customer><FName>Jess...

There are two kinds of entity declared here: PQ is a simple text replacement, and Logo is a reference to a graphic, held in a GIF file.

Entity types

The following kinds of entity can occur in XML documents:

Internal entities These entities hold replacement text that is defined in an entity declaration.
The following is an internal entity declaration:
```
<!ENTITY PQ "Province of Quebec">
```
You can reference this entity as follows in the content of an element:
```
<Region type="Province">&PQ;</Region>
```
XML supports a small set of predefined internal entities, which do not need to be defined. This set includes:
- amp The ampersand character (&)
- lt The left angle bracket character, or less-than sign (<)
- gt The right angle bracket character, or greater-than sign (>)
- apos The apostrophe character (')
- quot The quotation mark character (")
External entities that can be parsed These allow you to incorporate XML content from other files. You declare them as follows:
```
<!ENTITY chap1 SYSTEM "chapter1.xml">
<!ENTITY chap2 SYSTEM "chapter2.xml">
```
The string chapter1.xml is called the system identifier of the entity. You can reference this entity from within the content of an element as follows:
```
<BOOK>
&chap1;
&chap2;
</BOOK>
```
External entities that cannot be parsed These allow you to incorporate material that is not XML content, such as images, into an XML document.
You declare them as follows:
```
<!ENTITY Logo SYSTEM "emblem.gif" NDATA gif>
```
NDATA states that the entity is not XML data and should not be parsed.

To include an external entity of this kind in a document, you must reference it in an attribute of an element:
```
<GRAPHIC entity="Logo">
```

Working with internal entities

You can include references to internal entities in the text. For example, the following element includes a predefined internal entity:

<Names>Sammy &amp; Rosie</Names>

The Names element has three children, the first being a text node, the second being an entity reference node, and the third being another text node. The firstChild of the entity reference node is a text node, and the nodeValue of this text object is the replacement text.

The entity definitions of predefined entities are also available from the entities property of the DOMDocument object's doctype property.

Working with external entities

The following is a complete XML document that defines and references an external entity:

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE DOC [
 <!NOTATION gif SYSTEM "GIF">
 <!ENTITY Logo SYSTEM "nautilus.gif" NDATA gif>
]><DOC><GRAPHIC ENTITY="Logo"/></DOC>

The following DynaScript function takes the DOMDocument object as its argument, and displays the nautilus.gif file that holds the Logo image:

function displayGraphic( domDoc){
  dtd = domDoc.doctype;
  entlist = dtd.entities;
  
  elemlist = domDoc.getElementsByTagName( "GRAPHIC" );
  elem = elemlist.item(0);
  gif = elem.getAttribute( "ENTITY" );
  ent = entlist.item( gif );
  sysid = ent.systemId;
  document.writeln( '<img src="' + sysid + '>');
}

Notes

To access the entity declarations, you use the DOMDocumentType object, which is accessible as the doctype property of the DOMDocument object. The entities property of DOMDocumentType returns a list of entities.
The application must know which attributes are entities, as the DOM interface does not makes this information available. Here, the ENTITY attribute of the GRAPHIC element is an entity name.
The systemID property of the DOMEntity object returns the path to the file.
If you use an entity to refer to another document, you need to pay attention to the path to that document. In particular, the path may differ depending on whether the reference is resolved on the client or by Dynamo.
To resolve entities on the server you must use the full path.

Although Dynamo recognizes the home directory (~) in a path, you should not use ~ in an img tag to a browser, as the browser does not recognize the home directory.

Conversely, although browsers recognize standard URLs of the form http://address, you should not use these if you expect Dynamo itself to obtain information from the address, as Dynamo is not a Web client.