The JavaTM Web Services Tutorial
Home
TOC 		PREV TOP NEXT

Defining Parameter Entities and Conditional Sections

Just as a general entity lets you reuse XML data in multiple places, a parameter entity lets you reuse parts of a DTD in multiple places. In this section of the tutorial, you'll see how to define and use parameter entities. You'll also see how to use parameter entities with conditional sections in a DTD.

Creating and Referencing a Parameter Entity

Recall that the existing version of the slide presentation could not be validated because the document used <em> tags, and those are not part of the DTD. In general, we'd like to use a whole variety of HTML-style tags in the text of a slide, not just one or two, so it makes more sense to use an existing DTD for XHTML than it does to define all the tags we might ever need. A parameter entity is intended for exactly that kind of purpose.

Note: The DTD specifications shown here are contained in slideshow2.dtd. The XML file that references it is slideSample08.xml. (The browsable versions are slideshow2-dtd.html and slideSample08-xml.html.)

Open your DTD file for the slide presentation and add the text highlighted below to define a parameter entity that references an external DTD file: 

<!ELEMENT slide (image?, title?, item*)>	
<!ATTLIST slide 	
         ...	
>
 
<!ENTITY % xhtml SYSTEM "xhtml.dtd">	
%xhtml;
 
<!ELEMENT title ...

Here, you used an <!ENTITY> tag to define a parameter entity, just as for a general entity, but using a somewhat different syntax. You included a percent sign (%) before the entity name when you defined the entity, and you used the percent sign instead of an ampersand when you referenced it.

Also, note that there are always two steps for using a parameter entity. The first is to define the entity name. The second is to reference the entity name, which actually does the work of including the external definitions in the current DTD. Since the URI for an external entity could contain slashes (/) or other characters that are not valid in an XML name, the definition step allows a valid XML name to be associated with an actual document. (This same technique is used in the definition of namespaces, and anywhere else that XML constructs need to reference external documents.)

Notes:

The whole point of using an XHTML-based DTD was to gain access to an entity it defines that covers HTML-style tags like <em> and <b>. Looking through xhtml.dtd reveals the following entity, which does exactly what we want: 

  <!ENTITY % inline "#PCDATA|em|b|a|img|br">

This entity is a simpler version of those defined in the Modularized XHTML draft. It defines the HTML-style tags we are most likely to want to use -- emphasis, bold, and break, plus a couple of others for images and anchors that we may or may not use in a slide presentation. To use the inline entity, make the changes highlighted below in your DTD file: 

<!ELEMENT title (#PCDATA %inline;)*>	
<!ELEMENT item (#PCDATA %inline; | item)* >

These changes replaced the simple #PCDATA item with the inline entity. It is important to notice that #PCDATA is first in the inline entity, and that inline is first wherever we use it. That is required by XML's definition of a mixed-content model. To be in accord with that model, you also had to add an asterisk at the end of the title definition. (In the next two sections, you'll see that our definition of the title element actually conflicts with a version defined in xhtml.dtd, and see different ways to resolve the problem.)

Note: The Modularized XHTML DTD defines both inline and Inline entities, and does so somewhat differently. Rather than specifying #PCDATA|em|b|a|img|Br, their definitions are more like (#PCDATA|em|b|a|img|Br)*. Using one of those definitions, therefore, looks more like this: <!ELEMENT title %Inline; >

Conditional Sections

Before we proceed with the next programming exercise, it is worth mentioning the use of parameter entities to control conditional sections. Although you cannot conditionalize the content of an XML document, you can define conditional sections in a DTD that become part of the DTD only if you specify include. If you specify ignore, on the other hand, then the conditional section is not included.

Suppose, for example, that you wanted to use slightly different versions of a DTD, depending on whether you were treating the document as an XML document or as a SGML document. You could do that with DTD definitions like the following: 

someExternal.dtd: 	
   <![ INCLUDE [	
      ... XML-only definitions	
   ]]>	
   <![ IGNORE [	
      ... SGML-only definitions	
   ]]>	
   ... common definitions

The conditional sections are introduced by "<![", followed by the INCLUDE or IGNORE keyword and another "[". After that comes the contents of the conditional section, followed by the terminator: "]]>". In this case, the XML definitions are included, and the SGML definitions are excluded. That's fine for XML documents, but you can't use the DTD for SGML documents. You could change the keywords, of course, but that only reverses the problem.

The solution is to use references to parameter entities in place of the INCLUDE and IGNORE keywords: 

someExternal.dtd: 	
   <![ %XML; [	
      ... XML-only definitions	
   ]]>	
   <![ %SGML; [	
      ... SGML-only definitions	
   ]]>	
   ... common definitions

Then each document that uses the DTD can set up the appropriate entity definitions: 

<!DOCTYPE foo SYSTEM "someExternal.dtd" [	
   <!ENTITY % XML  "INCLUDE" >	
   <!ENTITY % SGML "IGNORE" >	
]>	
<foo>	
   ...	
</foo>

This procedure puts each document in control of the DTD. It also replaces the INCLUDE and IGNORE keywords with variable names that more accurately reflect the purpose of the conditional section, producing a more readable, self-documenting version of the DTD.

Home
TOC 		PREV TOP NEXT