Tip: Include external information with general entities

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

General entities enable XML authors to conveniently include not only characters that would be difficult to represent directly, but also information that must be repeated. They also enable you to import information from another file, as well as from another location. This tip shows you how to include external information through the use of general entities.

Share:

Nicholas Chase (nicholas@nicholaschase.com), President, Chase and Chase, Inc.

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.



01 July 2002

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.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into XML on developerWorks


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