ENTITY

Article
02/21/2011

The ENTITY statement is used to define entities in the DTD, for use in both the XML document associated with the DTD and the DTD itself. An ENTITY provides an abbreviated entry to place in your XML document. The abbreviated name is what you provide for the name parameter. ENTITYs are extremely useful for repeating information or large blocks of text that could be stored in separate files. The abbreviated name is followed by a ; in the XML document (&abbName;)

An example of ENTITYs used in a DTD and a XML file is shown below.

longtext.txt

The following is the content of longtext.txt:

<definition>ATTLIST(attribute list) Declares a list of XML attributes. These attributes are qualified by name, data type, implied default values, and the name of any elements that permit their use.

</definition>

dtd_chunk.dtd

<!ELEMENT list >
<!ATTLIST list list_type (ul | ol)>

sample.dtd

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE dtd_sample[
<!ELEMENT file_info>
<!ATTLIST file_info name #REQUIRED>

<!ENTITY xml "eXtensible Markup Language">
<!ENTITY attlist_def SYSTEM "longtext.txt">
<!ENTITY % lists "(ol | ul)">
<!ENTITY % dtd_chunk SYSTEM "chunk.dtd">
<!ENTITY file_pic SYSTEM "file.jpg" NDATA jpg>
<!NOTATION jpg SYSTEM "image/jpeg">
%dtd_chunk;
<!ELEMENT icon EMPTY>
<!ATTLIST icon source ENTITY #REQUIRED>
<!ATTLIST icon list_type &lists;>
]>

When you parse the DTD document, you get the following results. Note that this replacement only occurs in memory. The parser does not actually change the file.

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE dtd_sample[
<!ELEMENT file_info>
<!ATTLIST file_info name #REQUIRED>
<!ENTITY xml "eXtensible Markup Language">
<!ENTITY attlist_def SYSTEM "longtext.txt">

<!ENTITY % dtd_chunk SYSTEM "chunk.dtd">
<!ENTITY file_pic SYSTEM "file.jpg" NDATA jpg>
<!NOTATION jpg SYSTEM "image/jpeg">
<!ELEMENT list >
<!ATTLIST list list_type (ul | ol)>
<!ELEMENT icon EMPTY>
<!ATTLIST icon source ENTITY #REQUIRED>
<!ATTLIST icon list_type (ol | ul)>
]>

sample.xml

<?xml version="1.0" standalone="no" ?>
<heading>Definition list for &xml; attributes used in DTD files.</heading>
    <file_info name="topfile">
        <icon source="file_pic"/>
        <list list_type="ul"/>
        %attlist_def
    </file_info>
<footer>Conclusion of definition list for &xml; attributes.</footer>

Results of the parsed XML document

When you parse the XML document, you get the following results:

Definition list for eXtensible Markup Language attributes used in DTD files.

top file

ATTLIST(attribute list) Declares a list of XML attributes. These attributes are qualified by name, data type, implied default values, and the name of any elements that permit their use.

Conclusion of definition list for eXtensible Markup Language attributes.

Syntax

<!ENTITY [%] name [SYSTEM|PUBLIC publicID] resource [NDATA notation] >

Parameters

name
The name of the entity. Required for all entity definitions.

publicID
The public identifier for the entity. Only required if the declaration uses the PUBLIC keyword.

resource
The value for the entity. Required for all entity definitions. In the case of internal entities, this is a text string that is parsed and expanded. In the case of external entities, it is a Uniform Resource Identifier (URI) that identifies an external entity such as a file name or file type.

notation
The name of a notation declared elsewhere in the DTD using the NOTATION statement. Only required when declaring an unparsed entity through the use of the non-XML data (NDATA) keyword.

Examples

General entity (parsed internal)

The following declares an internal general entitys that can be referenced as &oumlaut; and &xml; in XML documents that use the DTD.

<!ENTITY oumlaut "&#38;#246;">

or a simple text substitution example is

<!ENTITY xml "eXtensible Markup Language">

The XML parser expands the raw entity value (&#246;) to make it part of the internal XML document. In the final parsed document output, the "&" value is used to create the character "&" and the value appears in the XML document as "ö".

Parameter entity (parsed internal)

The following declares an internal parameter entity that can be referenced as %lists;in other places in the DTD. This allows repeated references to the XHTML list elements, <ul> and <ol>.

<!ENTITY % lists "ul | ol">

Unparsed external entity

The following declares an unparsed external entity that allows you to encode links to non-XML data (in this case, an image file in GIF format) for inclusion in your XML document.

<!ENTITY file_pic SYSTEM "file.jpg" NDATA jpg>

In this case, the use of the NDATA keyword requires that a NOTATION declaration for a notation called "jpg" must also be used in combination with this declaration. For more information, see NOTATION.

Remarks

ENTITYs can be used in a variety of ways. If you are not sure how to define an entity for use, the following questions might help you better understand the different conditions for using the entities you declare in the DTD:

Is the value of the entity simply to be used to abbreviate a larger text string that might change during the life of the document? Then use a general entity.
Will it be used as a pointer to something external to the DTD or XML document (i.e. external entities), like a file name or MIME type? Then use an unparsed external entity.
Should the URI value of the entity be parsed (i.e. expanded as part of the DTD or an XML document that uses it), or remain unparsed (i.e. the XML parser will omit its contents from the final parsed document)?
If parsed, should the expanded entity content become part of the XML document that uses the DTD (i.e. general entities) or part of the DTD itself (i.e. parameter entities)?

Share via