Note: This tip assumes that you have a basic understanding of Document Type Definitions (DTDs) and an XML parser to examine a processed XML file. Validation is not necessary; Internet Explorer 5.0 or above will suffice.
In this tip, I take a sample letter from a mail-merge system and add a standard disclaimer to the bottom of it. Ultimately, I want the disclaimer to be controlled from a central location, such as a server, so it can be controlled externally from the document itself.
The basic document contains the letter itself:
Listing 1. The document
<?xml version="1.0"?>
<letter>
<salutation>
Dear <customerName>Valued Customer</customerName>,
</salutation>
<body>
<paragraph>
Thank you for your recent letter/phone call/email
telling us of your problem/concern/question. We
want you to know that we take all issues seriously
and are working to quickly resolve yours.
</paragraph>
<paragraph>
We pride ourselves on our personalized service
and will be in contact with you shortly.
</paragraph>
</body>
<closing>Sincerely,</closing>
<signature>Customer Service Employee 334992</signature>
</letter> |
General entities are much like variables in an application. You can set a value for them, refer to them where they're needed, and their value will be inserted at that location. This process is known as expanding the entity. Entities must be declared as part of a Document Type Definition (DTD). For centrally controlled information, they would typically be part of the external DTD subset, but for convenience, this example shows the declaration of the entity as part of the internal subset.
Listing 2. Declaring an entity
<?xml version="1.0"?>
<!DOCTYPE letter [
<!ENTITY disclaimer "DISCLAIMER GOES HERE">
]>
<letter>
<salutation>
Dear <customerName>Valued Customer</customerName>,
</salutation>
... |
The listing shows a general entity with the name disclaimer and a value of DISCLAIMER GOES HERE. Next, you call it from within the document.
A general entity is inserted into the body of an XML document by preceding it with an ampersand (&) and following it with a semi-colon (;), as in:
Listing 3. Referencing the general entity
<?xml version="1.0"?>
<!DOCTYPE letter [
<!ENTITY disclaimer "DISCLAIMER GOES HERE">
]>
<letter>
<salutation>
Dear <customerName>Valued Customer</customerName>,
</salutation>
<body>
...
</body>
<closing>Sincerely,</closing>
<signature>Customer Service Employee 334992</signature>
&disclaimer;
</letter>
|
When an XML 1.0 compliant processor reads the document itself, the entity is expanded, and its contents replace the reference, so the entire document appears as:
Listing 4. The document, with expanded entity
<letter>
<salutation>
Dear
<customerName>Valued Customer</customerName>
,
</salutation>
<body>
<paragraph>Thank you for your recent letter/phone call/email telling
us of your problem/concern/question. We want you to know that we take
all issues seriously and are working to quickly resolve yours.</paragraph>
<paragraph>We pride ourselves on our personalized service and will
be in contact with you shortly.</paragraph>
</body>
<closing>Sincerely,</closing>
<signature>Customer Service Employee 334992</signature>
DISCLAIMER GOES HERE
</letter>
|
There is no rule, however, dictating that the expanded value must be defined directly within the DTD.
The disclaimer entity so far has been an internal entity; the document can stand on its own and has no dependencies on other documents. Now, I'll show you how to make an external entity.
External entities, like DTDs themselves, can reference SYSTEM or PUBLIC identifiers. This tip only deals with SYSTEM, but the principle is the same. Below is a reference to a file in the same directory as the current document.
Listing 5. Referencing a local file
<?xml version="1.0"?>
<!DOCTYPE letter [
<!ENTITY disclaimer SYSTEM "./disclaimer.xml">
]>
<letter>
<salutation>
Dear <customerName>Valued Customer</customerName>,
</salutation>
...
|
The entity reference is untouched, but now when it's expanded, it uses the contents of the file, so the document becomes:
Listing 6. The expanded local file
<letter>
<salutation>
Dear
<customerName>Valued Customer</customerName>
,
</salutation>
<body>
<paragraph>Thank you for your recent letter/phone call/email telling
us of your problem/concern/question. We want you to know that we take
all issues seriously and are working to quickly resolve yours.</paragraph>
<paragraph>We pride ourselves on our personalized service and will
be in contact with you shortly.</paragraph>
</body>
<closing>Sincerely,</closing>
<signature>Customer Service Employee 334992</signature>
<disclaimer>This is a test. It is only a test. If this were a
real customer emergency, it would, of course, be handled with the
utmost sincerity. Thank you for your attention.</disclaimer>
</letter>
|
No rule dictates that the system identifier must refer to a local resource. A SYSTEM identifier can point to remote files just as easily:
Listing 7. Referencing remote information
<?xml version="1.0"?>
<!DOCTYPE letter [
<!ENTITY disclaimer SYSTEM "http://www.vanguardreport.com/disclaimer.xml">
]>
<letter>
<salutation>
Dear <customerName>Valued Customer</customerName>,
</salutation>
...
|
When the file is processed, the remote file's information expands into the document.
This tip demonstrates the ability to include external information in XML documents through general entities. Any information can be included this way, with one caveat: The document must be well-formed, even after the entity is expanded.
Otherwise, this method is well-suited for information such as disclosures, copyright statements, or other statements that must be repeated frequently throughout a range of documents, or for information that must be controlled from a central source such as a server, but still accessed as part of XML documents.
- Check out the XML 1.0 recommendation.
- Get more information on Document Type Definitions (DTDs) in the Validating XML tutorial (developerWorks, September 2001).
- Have entity questions? Get answers at "Entities: What are they good for?"
- For more information on entities, read "External entities and alternatives."
- Find more XML resources on the developerWorks XML zone. For a complete list of XML tips to date, check out the tips summary page.
-
IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
- Find out how you can become an IBM Certified Developer in XML and related technologies.
- Want us to send you useful XML tips like this every week? Sign up for the developerWorks
XML Tips newsletter.
Nicholas Chase has been involved in Web site development for companies such as Lucent Technologies, Sun Microsystems, Oracle, and the Tampa Bay Buccaneers. Nick has been a high school physics teacher, a low-level radioactive waste facility manager, an online science fiction magazine editor, a multimedia engineer, and an Oracle instructor. More recently, he was the Chief Technology Officer of Site Dynamics Interactive Communications in Clearwater, Florida, USA, and is the author of three books on Web development, including Java and XML From Scratch (Que) and the upcoming Primer Plus XML Programming (Sams). He loves to hear from readers and can be reached at nicholas@nicholaschase.com.
Table of contents
Tags
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags