Running the Project

To save yourself a lot of clicking and typing, you can turn to the files on the accompanying CD. Copy the event project on your hard disk and copy the following files in the appropriate directories. All these directories are under the XMetaL main directory:

• event.css goes under Display .

• event.mcr goes under Macros .

• event.dtd , event.ctm , and ~event.tbr go under Rules .

• For Event Description Form.xml , you must first create a new Pineapplesoft directory under Template . Then, copy the file in the new directory.

Creating the Model

The first step is to model the information we want to capture. We must decide which information is relevant and how to encode it in XML (which elements). We are not concerned with the presentation but with the structure of the document.

A form to record local events is not very complicated. Essentially, it must capture the name , location, and date of the event, as well as contact information. Finally, it should provide a text area to describe the specifics of the event. You might want to propose basic formatting options (bold and italic) for the description.

Figure 3.3 shows the structure for the form. Translated into DTD format, it looks similar to Listing 3.2.

Figure 3.3. The event form starts with closed questions and ends with a free-text description.

Listing 3.2 event.dtd

 <!ELEMENT Event       (Name,Location,Date,Contact,Description)> <!ELEMENT Name        (#PCDATA)> <!ELEMENT Location    (#PCDATA)> <!ELEMENT Date        (Start,End)> <!ELEMENT Contact     (Name,Phone,Email?)> <!ELEMENT Description (Para+)> <!ELEMENT Start       (#PCDATA)> <!ELEMENT End         (#PCDATA)> <!ELEMENT Phone       (#PCDATA)> <!ELEMENT Email       (#PCDATA)> <!ELEMENT Para        (#PCDATA  Bold  Italic)*> <!ELEMENT Bold        (#PCDATA  Italic)*> <!ELEMENT Italic      (#PCDATA  Bold)*> 

XML Models

In XML, markup is used to encode the structure of a document. Most XML tools manipulate the structure, making it important to have proper tools to model the structure of documents.

Therefore, XML has a modeling language, the Document Type Definition (DTD) . A DTD defines which elements appear in the document and what their relationships are (which element appears where). It also defines which elements can repeat and which are optional. Finally, the DTD also declares attributes and entities.

Listing 3.2 is a DTD. It lists all the elements and their content. For example,

 <!ELEMENT Event (Name,Location,Date,Contact,Description)> 

means that the Event element must contain a Name , Location , Date , Contact , and Description element.

XML documents fall into one of the following two categories:

• Well-formed documents follow the XML syntax. So far, our documents have been well formed .

• Valid documents follow the XML syntax and respect a model. This chapter uses valid documents.

Valid documents are helpful because XML tools will enforce their model. For example, XMetaL reports an error if you create a document in which an Event has no Location . In practice, your application benefits from a free validation routine.

For completeness, note that W3C is working on a replacement for DTD. The new modeling language, which should be called XML Schema, will be more powerful and will support object-oriented concepts.

For a comprehensive introduction to DTD and XML models, I recommend you read my other book, XML by Example, published by Que.

Loading the Model in XMetaL

Copy event.dtd (refer to Listing 3.2) under the Rules directory underneath the XMetaL main directory (on my system that is the C:\ Program Files\ SoftQuad\ XMetaL 1\ Rules directory). XMetaL can load DTDs from any directory, but placing them in the Rules directory ensures they are always available.

In the menu, choose File, New to open the New dialog box. Under the General tab, select Blank XML Document and then select the event.dtd file you have just created. XMetaL opens a dialog box to inquire about the space options; click the Apply Layout button.

Note

The Preserve Space Options dialog box determines how XMetaL indents the XML code. For most documents, you should choose Apply Layout, which produces more readable XML code.

However, if you write documents in which spaces are meaningful, you should opt to Preserve Space. You can always change the setting later.

You now should see a blank editor window but be unable to type anything. To create the root XML element, choose Insert, Element in the menu and double-click Event.

The editor window fills with various entry fields for name, location, and more. Click { Name} and type Book Fair . Click { Location} and type Exhibition Center, Namur , as illustrated in Figure 3.4.

Figure 3.4. After inserting the root element, enter some data.

Note

As you can see, XMetaL makes good use of the DTD. It extracts the list of elements and their relationships so that, when you insert an Event element, it knows which elements must appear underneath ”Name , Location , and so on. Therefore, it creates input fields for these elements.

In the menu, choose View, Plain Text to display the XML code you have just created. The screen should look similar to Figure 3.5.

Figure 3.5. XMetaL shows the XML code.

What happened ? To find out, close the document but don't save it. Look in the XMetaL directory and you will see several new files:

• event.rlx ”Appears under the Rules directory and is a so-called rules file. Essentially, it's a compiled version of the DTD.

• event.ctm ”Appears under the Rules directory and is the customization file. You will learn how to edit it soon.

• ~event.tbr ”Appears in the same directory and represents the toolbars .

• event.css ”Appears in the Display directory and is a cascading style sheet for this document.

These files are created with default options. They give us a starting point, but we probably want to customize them to better fit our event form.

Creating a Template

Our second step will be to create a template or an empty form that the clerk can use to get started. Create a new empty event document as previously discussed: Choose File, New, select event.dtd , choose Insert, Element, and double-click Event.

Choose View, Plain Text to edit the XML code. First, though, make sure the DOCTYPE statement uses a relative path . Edit it until it looks exactly as follows (it might be correct already):

 <!DOCTYPE Event SYSTEM "event.dtd"> 

As you can see, in this empty document, the text is replaced by processing instructions such as the following:

 <?xm-replace_text { Name} ?> 

These processing instructions are specific to XMetaL. The editor renders them as an input area, similar to the Click Me fields in a word processor. When the user enters text, the text replaces the processing instruction.

To make the template more friendly, adopt more descriptive processing instructions, such as:

 <?xm-replace_text { Click here to enter the event's name} ?> 

You should edit the document until it looks like Listing 3.3.

Listing 3.3 Event Description Form.xml

 <?xml version="1.0"?> <!DOCTYPE Event SYSTEM "event.dtd"> <Event>   <Name><?xm-replace_text { Click here to enter the event's name} ?></Name>   <Location><?xm-replace_text { Click here to enter the event's location} ?></Location>   <Date>     <Start><?xm-replace_text { Click here to enter the event's start date} ?></Start>     <End><?xm-replace_text { And its end date} ?></End>   </Date>   <Contact>     <Name><?xm-replace_text { Click here to enter the contact person's name} ?></Name>     <Phone><?xm-replace_text { Click here to enter the contact person's phone number} ?></  Phone>   </Contact>   <Description>     <Para><?xm-replace_text { Click here to enter the event's description} ?></Para>   </Description> </Event> 

Create a new directory, called Pineapplesoft , under the Template directory below the XMetaL main directory. Save the template (Listing 3.3) under the Pineapplesoft directory and name it Event Description Form.xml .

We now have created a new template. If you close the file and choose File, New, you will see that the New dialog has a Pineapplesoft tab. The Pineapplesoft tab contains one entry: Event Description Form (see Figure 3.6).

If you double-click Event Description Form, it creates an empty document based on your template.

Figure 3.6. Calling up the form is easy with custom templates.

Styling the Form

So far, thanks to the template, we have provided the clerk with an empty form he can fill in. Also, thanks to the DTD, XMetaL makes sure the clerk provides all the required information.

However, the form is dull. At the minimum, fields should be labeled. To change the presentation of the document, you will edit the cascading style sheet.

Cascading Style Sheet

XML markup is descriptive. Markup identifies the role of each element and its position in the structure, not how it should look. XML tools (particularly editors and browsers) need additional information to describe how to format the document for viewing.

The presentation rules are kept separated from the document itself in style sheets , which describe how to render the elements onscreen.

Cascading Style Sheet, or CSS, was originally created for HTML, but it was quickly extended for XML. A CSS is a list of rules, with each rule listing formatting properties associated with one or more elements.

For example, in XML, the Bold element does not automatically mean that the text must be bolded. However, you can define a CSS rule that says so:

 Bold {         font-weight: bold;         display: inline;       } 

CSS defines an extensive list of formatting properties. For the complete description, see http://www.w3.org/Style/CSS.

XMetaL includes a CSS editor that is convenient for getting you started. However, as you become more familiar with CSS, you will find it is faster to edit the style code directly.

First, you should format the Name element. Indent the field from the left margin and include a label.

Next, click somewhere in the Name field and choose Tools, Editor Display Style, Current Element. Make sure you are editing the Name element and then select the Box tab. Next, modify the margin-left property to 1em and click the Apply button. Notice how the two Name elements are now indented from the left margin.

Tip

The em unit is relative to the height of the font. Using relative units makes it easier to grow or shrink the whole document.

The Name rule you have just created applies to the element itself, so how can you insert a label before the element? The trick is to use CSS pseudo-elements. Pseudo- elements are not XML elements, but the style sheet treats them as such. You can think of them as virtual elements created by the style sheet.

In this case, you create a pseudo-element called Name:before . Name:before enables you to insert values before the Name element.

Still from the CSS editor, click the More button. Then, click New to open the Edit Selectors in Rule dialog box. Select Name , click Add, and click Edit to open the Edit Simple Selector dialog box. In the Pseudo/class element list (bottom-right of the box), select Before. Finally, click OK twice to return to the CSS editor.

You now have created an entry called Name:before (see Figure 3.7). Enter the following properties:

• A content property (in the Other tab) with the value Name: .

• A font- size property (in the Font tab) with the value smaller .

• A color property (in the Text tab) with the value gray .

Click OK to close the dialog box. The content property is the label. Because it is attached to the Name:before rule, it appears before the element itself. Notice that, per your selection, the label is in a smaller, gray font.

Continue adding rules for the other elements until your style sheet looks similar to Listing 3.4. Notice that the form title appears in an Event:before rule.

You probably will find it easier to edit the CSS style sheet in a text editor. To do so, from the CSS editor, click Edit Style Text.

Figure 3.7. Editing the Name:before rule.

Note

$DOCUMENT , $COMMENT , and $PROCINS are not elements. They are XMetaL-specific pseudo-elements that point to the entire document, comments, and processing instructions, respectively.

Listing 3.4 event.css

 /* Use Times New Roman for default font */ $DOCUMENT {   font-family: "Times New Roman";   font-size: 12pt;   margin-top: 5px;   margin-left: 5px; } $COMMENT {   display: block;   color: purple;   white-space: pre; } $PROCINS {   color: black;   background-color: #c0c0c0; } Contact, Date, Description, Email, Event, Location, Name, Para, Phone  {   display: block; } Start, End {   display: inline; } Event:before {   content: "Event Description Form";   display: block;   font-size: large;   font-weight: bold; } Name:before, Location:before, Date:before, Phone:before, Email:before, End:before {   font-size: smaller;   color: gray; } Name:before {   content: "Name: "; } Location:before {   content: "Location: "; } Date:before {   content: "Date: "; } Phone:before {   content: "Phone: "; } Email:before {   content: "Email: "; } End:before {   content: " to "; } Description:before, Contact:before {   display: block;   font-weight: bold; } Description:before {   content: "Description"; } Contact:before {   content: "Contact"; } Bold {   font-weight: bold;   display: inline; } Italic {   font-style: italic;   display: inline; } Name, Location, Date, Phone, Email, Para {   margin-left: 1em; } Contact, Description {   margin-top: 0.5em; } Event>Name {   margin-top: 0.5em; } 

The form in the editor should now look like Figure 3.8. This is a good layout for a form: The fields are clearly labeled and the form is divided into sections separated by titles.

Remember that the labels and section titles are not part of the XML document; they appear only in the style sheet as pseudo-elements. Review the XML code in plain text view (choose View, Plain Text) to convince yourself.

Figure 3.8. A good-looking form in XMetaL.