Contents


Tip

Include external information with general entities

Add difficult-to-represent characters, information to be repeated, and imported information

Comments

Content series:

This content is part # of # in the series: Tip

Stay tuned for additional content in this series.

This content is part of the series:Tip

Stay tuned for additional content in this series.

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.

The document

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>

Adding a general entity

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.

Including a general entity

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.

External entities

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>

Including remote information

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.

Summary

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.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML
ArticleID=12132
ArticleTitle=Tip: Include external information with general entities
publish-date=07012002