Lesson 5	Parameter entities
Objective	Create entities to use within a DTD

Create entities to use within a DTD

You can create entities to use within the DTD itself. These are parameter entities. To denote that an entity is to be used as a parameter entity, you must include the % character in the manner indicated.
To create entities in a Document Type Definition (DTD) for use within XML documents, you use the declaration to define reusable content, such as text, markup, or external data. Entities act as placeholders that can be referenced in the XML document or DTD, promoting modularity and consistency. Below are the steps and examples for creating different types of entities in a DTD:

Internal Entity:
- Syntax: <!ENTITY entityName "replacementText">
- Purpose: Defines a string of text that can be reused in the XML document.
- Example:
```
          <!ENTITY company "Acme Corp">
        
```
- In the XML, use &company; to insert "Acme Corp".
- Steps:
  - Choose a unique entity name (e.g., company).
  - Specify the replacement text in quotes.
  - Place the declaration in the DTD (internal or external DTD subset).
  - Reference the entity in the XML document with &entityName;.
External Entity:
- Syntax: <!ENTITY entityName SYSTEM "URI"> or <!ENTITY entityName PUBLIC "publicID" "URI">
- Purpose: Imports content from an external file, such as another XML or text file.
- Example:
```
          <!ENTITY chapter SYSTEM "chapter1.xml">
        
```
- In the XML, &chapter; inserts the content of chapter1.xml.
- Steps:
  - Identify the external resource (e.g., a file URL or path).
  - Use SYSTEM for a private resource or PUBLIC with a public identifier for shared resources.
  - Ensure the file is accessible and contains valid content for the XML parser.
  - Reference the entity in the XML with &entityName;.
Parameter Entity:
- Syntax: <!ENTITY % entityName "replacementText">
- Purpose: Defines reusable content for use within the DTD itself, such as element or attribute definitions.
- Example:
```
          <!ENTITY % commonAttrs "id ID #IMPLIED">
          <!ELEMENT book (%commonAttrs;)>
        
```
- The %commonAttrs; reference inserts id ID #IMPLIED into the book elementâs attribute list.
- Steps:
  - Use the % symbol before the entity name to indicate a parameter entity.
  - Define the replacement text (e.g., attribute lists or element patterns).
  - Place the declaration in the DTD.
  - Reference it within the DTD using %entityName;.

Best Practices:

Ensure entity names are unique and follow XML naming rules (e.g., no spaces, start with a letter).
Avoid circular references, as they cause parsing errors (e.g., an entity referencing itself).
Validate external entity content to ensure itâs well-formed and compatible with the XML structure.
Test entity references in the XML document to confirm correct replacement during parsing.

Example DTD with Multiple Entities:

      <!ENTITY company "Acme Corp">
      <!ENTITY chapter SYSTEM "chapter1.xml">
      <!ENTITY % commonAttrs "id ID #IMPLIED">
      <!ELEMENT document (title, content)>
      <!ELEMENT title (#PCDATA)>
      <!ELEMENT content (#PCDATA | chapter)*>
      <!ATTLIST document %commonAttrs;>

In the XML:

<document id="doc1">
  <title>About &company;</title>
  <content>&chapter;</content>
</document>

By defining entities in the DTD, you can streamline XML document creation, ensure consistency, and make maintenance easier. Internal entities are great for small, repeated text; external entities suit large or dynamic content; and parameter entities enhance DTD modularity. Always validate the DTD and XML to ensure proper parsing and functionality.

Declaring a Parameter Entity

The syntax for declaring a parameter entity is as follows:

<!ENTITY %parameterEntityName parameterEntityDefinition >

Using parameter entities
Suppose that you need to create an attribute-list declaration to be used for several different elements. Rather than define each element with the full listing of attributes, you can create an attribute-list entity and then reference it for each of the several elements. In the following example, three elements have the same three attributes: ID, MAKE and MODEL. These three attributes are defined once in a parameter entity (commonAtts),and then used in the attribute-list declaration for each of the elements.

<!ENTITY % commonAtts
"ID ID #REQUIRED 
MAKE CDATA #IMPLIED
MODEL CDATA #IMPLIED"> 
<!ELEMENT CAR (#PCDATA)>
<!ATTLIST CAR %commonAtts>
<!ELEMENT COMPUTER (#PCDATA)>
<!ATTLIST COMPUTER %commonAtts>
<!ELEMENT MODEL (#PCDATA)>
<!ATTLIST MODEL %commonAtts>

In these declarations, each element of CAR, COMPUTER and MODEL shares the same common set of attributes defined by the parameter entity commonAtts. As you may have noticed, the order in which you declare elements and attributes does not matter, so long as you accurately declare all that you will use before the XML document loads. Within an element declaration, the order of child elements matters, but the actual order of element declarations or attribute declarations does not matter.
In the next lesson, you will learn how to use namespaces to establish clear naming conventions.

Notation Declarations in XML

A notation declaration references a non-XML resource and specifies instructions for that resource in a non-XML context.
For example, if you want to include a special media type, you would add a notation declaration that specifies the media type and perhaps an application on the system that could be used to render that media. The following code shows a fictitious notation declaration for the GIF image file type. In this example, the fictitious file name gifview.exe represents a file that enables the viewing of GIF images.

<!NOTATION GIF SYSTEM "gifview.exe">

The following entity declaration references non-XML content:

<!ENTITY BulletGif SYSTEM "bullet1.gif" NDATA GIF>

In this example, an entity referenced as BulletGif has been declared to reference the file "bullet1.gif" on the current system as non-character data (NDATA) and of the GIF type.
If a notation for GIF appears in the file, the application can choose whether or not to use the notation reference for rendering that file.

Parameter Entities - Exercise

Click the Exercise link below to practice including entities and parameters in the DTD.
Parameter Entities - Exercise