Customizing the Behavior

If we review your progress so far, it looks good. Our clerk can create an empty form, the fields are clearly labeled, and the editor still generates a valid XML document.

So far, we concentrated on the structure of the document and its presentation. In this section and the next , we customize XMetaL behavior to better fit your needs. We will

• Use the customization editor (in this section).

• Write JScript macros (in the next section) to create a specialized toolbar.

Tip

To save you some typing, remember you can copy event.ctm from the accompanying CD.

Element Names

Most of the element names in the DTD, such as Name , Location , and Date , are easy to understand. Other names are not so clear, however ”for example, Start , End , and Para . You should start by defining better alternatives for these names.

In the menu, choose Tools, Customization to open the customization editor. Under the General tab, enter a name for the following elements (you can leave the others empty), as follows :

• For Bold , enter Bold text .

• For Email , enter Email address .

• For End , enter End date .

• For Italic , enter Italic text .

• For Para , enter Paragraph .

• For Phone , enter Phone number .

• For Start , enter Start date .

Figure 3.9 shows the customization editor.

While we are at it, let's update the change list for the Para element. Select the Change List tab and, for Para , check both Bold and Italic . This option controls which elements appear in the list of styles in the toolbar.

Click OK to close the customization editor. Notice that the element names in the list of styles in the toolbar now reflect the changes we made. XMetaL also uses the names in the status bar.

Figure 3.9. The customization editor controls the editor's behavior.

Creating Mini-Templates

The form editor is really taking shape now. It enables easy editing of most values, with the notable exception of the email address. In fact, because the email address is an optional element, it does not appear in the template. Therefore, to insert it, the user must position it past the Phone element and choose Insert, Element. You can do much better.

Reopen the customization editor and tab to Treat As. Set the Email element as a paragraph. This controls what the editor does when the user presses Enter. When the user presses Enter, XMetaL always tries to insert the next paragraph element. By declaring Email as a paragraph, we make it easier to insert email addresses in the document, as you will see in a moment.

Tip

You don't need to explicitly declare the other elements as paragraphs because your DTD is very strict. The DTD lays down strict rules on where each element should appear, and XMetaL uses these rules to insert most elements.

A further problem with email is that some people ”particularly, AOL users ”forget to include their domain name. Ideally, you want to remind the clerk that an email address should have the form [e-mail].

The best solution is to prompt the user through a dialog box that presents the format for the email address. Return to the General tab and paste the following code in the On Insert field:

 var email = Application.Prompt("Enter the contact person's email address",  "[e-mail]",null,null,"Event Description Form")   if(email != null && email != "")   {      Selection.InsertElement("Email")      Selection.TypeText(email)   } 

Next, select JScript as the scripting language (see Figure 3.10). Now, whenever an Email element is inserted, XMetaL will run this script, which opens a dialog box.

Figure 3.10. Edit the element template.

To complete this round of customization, take a look at the On Insert field for the other elements. They always contain the XML code for the element, such as <Location></Location> .

By changing this code, we can control the XML code generated when creating the element. We can use it to modify the code and include the processing instructions. Edit the following elements (for these elements, leave the type as Content ):

• For Contact , use

   <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> 

• For Date , use

   <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> 

• For Description , use

   <Description><Para><?xm-replace_text {Click here to enter the event's description} ?></  Para></Description> 

• For End , use

   <End><?xm-replace_text {And its end date} ?></End> 

• For Location , use

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

• For Phone , use

   <Phone><?xm-replace_text {Click here to enter the contact person's phone number} ?></  Phone> 

• For Start , use

   <Start><?xm-replace_text {Click here to enter the event's start date} ?></Start> 

However, you must differentiate the event's name from the contact person's name. Right-click the Name element and select Add "In Parents" Item. Do this twice to create Name in Contact and Name in Event entries and give them different templates, respectively:

 <Name><?xm-replace_text {Click here to enter the contact person's name} ?></Name> 

and

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

Click OK to close the customization editor. Then, position the cursor on the Phone element and press Enter. A dialog box prompts for the email address (see Figure 3.11). The following occurs internally:

• XMetaL inserts the next paragraph element, which will be Email because it is marked as a paragraph.

• XMetaL executes the script from the Email mini-template. The script opens a dialog box and inserts the element.

Peeking at event.ctm

If you are curious , you can open event.ctm in XMetaL because it is an XML document. Listing 3.5 shows event.ctm if you applied all the customization described in this section.

Figure 3.11. Prompting for email information.

Caution

You should not modify event.ctm directly. It is both easier and safer to edit it through the customization editor.

Listing 3.5 event.ctm

 <?xml version="1.0"?> <!DOCTYPE DTDExtensions SYSTEM "ctm.dtd"> <DTDExtensions>   <ElementPropertiesList>     <ElementProperties>       <Name>Contact</Name>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>         <NewLineBeforeEndTag/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Date</Name>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <NewLineBeforeEndTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Description</Name>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <NewLineBeforeEndTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Email</Name>       <ShortDescription>Email address</ShortDescription>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>End</Name>       <ShortDescription>End date</ShortDescription>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Event</Name>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <NewLineBeforeEndTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Location</Name>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Name</Name>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Para</Name>       <ShortDescription>Paragraph</ShortDescription>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Phone</Name>       <ShortDescription>Phone number</ShortDescription>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Start</Name>       <ShortDescription>Start date</ShortDescription>       <PrettyPrintOptions>         <NewLineBeforeStartTag/>         <IndentContent/>       </PrettyPrintOptions>     </ElementProperties>     <ElementProperties>       <Name>Bold</Name>       <ShortDescription>Bold text</ShortDescription>     </ElementProperties>     <ElementProperties>       <Name>Italic</Name>       <ShortDescription>Italic text</ShortDescription>     </ElementProperties>   </ElementPropertiesList>   <Paragraphs>     <Paragraph>       <Name>Email</Name>     </Paragraph>   </Paragraphs>   <ChangeLists>     <ChangeList>       <Selectors>         <Selector>           <Name>#DEFAULT</Name>           <Parent>Para</Parent>         </Selector>       </Selectors>       <ChangeListElements>         <ChangeListElement>Bold</ChangeListElement>         <ChangeListElement>Italic</ChangeListElement>       </ChangeListElements>     </ChangeList>   </ChangeLists>   <Templates>     <Template>       <Name>Name</Name>       <Parent>Contact</Parent>       <MiniTemplate><![CDATA[<Name><?xm-replace_text { Click here to enter the contact  person's name} ?></Name>]]> </MiniTemplate>     </Template>     <Template>       <Name>Name</Name>       <Parent>Event</Parent>       <MiniTemplate><![CDATA[<Name><?xm-replace_text { Click here to enter the event's  name} ?></Name>]]> </MiniTemplate>     </Template>     <Template>       <Name>Description</Name>       <MiniTemplate><![CDATA[<Description><Para><?xm-replace text { Click here to enter  the event's description} ?></Para> </Description>]]></MiniTemplate>     </Template>     <Template>       <Name>Contact</Name>       <MiniTemplate><![CDATA[<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>]]></MiniTemplate>     </Template>     <Template>       <Name>Date</Name>       <MiniTemplate><![CDATA[<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>]]></MiniTemplate>     </Template>     <Template>       <Name>Location</Name>       <MiniTemplate><![CDATA[<Location><?xm-replace_text { Click here to enter the  event's location} ?></Location>]]> </MiniTemplate>     </Template>     <Template>       <Name>Phone</Name>       <MiniTemplate><![CDATA[<Phone><?xm-replace_text { Click here to enter the contact  person's phone number} ?></Phone>]]> </MiniTemplate>     </Template>     <Template>       <Name>Start</Name>       <MiniTemplate><![CDATA[<Start><?xm-replace_text { Click here to enter the event's  start date} ?></Start>]]> </MiniTemplate>     </Template>     <Template>       <Name>End</Name>       <MiniTemplate><![CDATA[<End><?xm-replace_text { And its end date} ?></End> ]]></  MiniTemplate>     </Template>   </Templates>   <OnInsertElementList>     <OnInsertElement>       <Name>Email</Name>       <Lang>JScript</Lang>       <InsertElemScript><![CDATA[var email = Application.Prompt("Enter the contact  person's email address", "[e-mail]",null,null,"Event Description Form") if(email != null && email != "") {    Selection.InsertElement("Email")    Selection.TypeText(email) } ]]></InsertElemScript>     </OnInsertElement>   </OnInsertElementList> </DTDExtensions>