Setting Element Properties in a Customization
Understanding the Customization File
In this lesson, you'll learn how to set properties for each XML element used in your project. These properties will affect how each element looks and behaves in the documents used by every XML content developer working with your customization.
Customization properties are stored in the Customization file, which has the file suffix ".ctm". The elements listed in the CTM file mirror those in the DTD file used by your project. In the CTM file, however, each element is associated with a set of configurable element properties.
First, we'll take a look at a sample customization, and at the CTM file that the customization depends on. Then we'll go back and forth between them, taking a close look at how each element property affects the XML document that uses it.
This lesson will take about one hour to complete.
The Meeting Minutes Customization
For this lesson, we'll work with a more complex example of an XMetaL customization, provided with your installation. This project is called "MeetingMinutes".
Meeting Minutes is a simple XMetaL Author application for recording attendance and taking notes at meetings.
Open XMetaL Author, and choose File>New. Click the Meeting tab, then double-click the Meeting icon. This opens a new Meeting Minutes document.
Play with the document for a moment. Try clicking on all the fields, and entering information into some of them. You'll see how even such a simple XML application can allow an organization to easily capture, store, and retrieve valuable information about all its meetings.
Opening and Viewing a Customization File
Now let's look at the customization properties that bring a Meeting Minutes document to life.
Find the directory in which XMetal is installed, go to XMetaL 4.5>Developer>Samples>MeetingMinutes, and open the file called MeetingMinutes.sln. You'll see that there are about 100 objects of several different file types that form this project.
In the Solution Explorer, double-click the object called "Meeting.ctm". The Meeting.ctm file opens in the main view.
XML elements used in the MeetingMinutes project are listed in the table, one per row. Across the top of the open CTM file window, you'll see a series of column headings, listing the names of the properties associated with each element, one per column.
Setting the Parent Property
Each row in the CTM file lists the properties associated with an element defined in the project DTD. Select one of the elements, and you'll see a list of all the property settings in the Properties window on the bottom right of your screen.
Select one of the properties, and the field beside it becomes a drop-down list, allowing you to choose a configuration value for that property.
If you double-click on a property, you'll toggle the configuration to the next possible value.
Let's take a look first of all at the Parent property. Each XML element must have a single parent element. In our example, there are no parent elements listed, meaning that every element has as its parent the root element, which in the Meeting Minutes customization is <Meeting>.
You can only make an element the child of another element if the DTD or Schema hierarchy permits it. If you choose to make any element a child of any other element, enter the name of its parent element into its parent property in the Properties window.
Setting an In-Parent Property
In the Meeting.ctm main view, right-click on the element name "ItemizedList". You'll see a shortcut menu that allows you to clear all properties for this element.
The shortcut menu also allows you to do something called "Insert 'In-Parent' Entry". This requires a bit of explanation.
Inserting an In-Parent entry means to add a new instance of the selected element whose properties only come into effect when that element is a child of another defined element (i.e. when it's IN a certain parent).
Take a look at this example:
<Book> <Title>My XML Book</Title> <Chapter> <Title>Chapter 1: Welcome to XML</Title> <Para>Lorum ipsum est...</Para> </Chapter> <Bibliography> <Title>Bibliographical References</Title> <Entry>MyBiblioEntry</Entry> <Entry>MyBiblioEntry</Entry> </Chapter> </Book>
Notice that the <Title> element appears within the parents <Book>, <Chapter>, and <Bibliography>. If I'd like <Title> to have different properties within <Bibliography> than it does elsewhere, I can create an In-Parent element based on <Title>, whose properties only apply when <Title> has the specific parent <Bibliography>.
Again, right-click the element ItemizedList, and select "Insert 'In-Parent' Entry". The Add Element window appears, allowing you to choose an In-Parent element for ItemizedList.
Once you click OK, a new instance of ItemizedList is created, with a different parent than the original. You can then set special properties for that instance as required.
Setting the Change List
The Change List property allows you to give an end user the ability to change one element to another. This ability must be carefully controlled in order not to disrupt the integrity of the document structure. However, in most documents, there's room for limited flexibility to help authors do things like change a bulleted list to a numbered list.
Return to XMetaL Developer, and in the Meeting.ctm main view, select the Underscore element. You'll see the properties of that element listed in the Properties window.
Scroll down until you see the Changelist property. Select Changelist, and click the ellipsis button (...) next to the property value field. You'll see a Change List window like the one shown below.
Elements listed in both the From: and the To: columns are elements which the Underscore element can legitimately be changed into, according to DTD or Schema rules. An element listed in the To: column will appear in the Style Element drop-down list in XMetaL Author. An element listed in the From: column is one that is eligible to be moved to the To: column.
Once an element name appears in the Style Element drop-down list, an author can change the current element to that new element by just choosing its name. In the example of the Underscore element, our authors will only be able to change it to Strong or Emphasis (i.e. bold or italic).
Understanding the "Display As" Properties
The "Display As" property allows you to use an element to call an embedded form or an ActiveX control within an XML document. This can save your authors a lot of typing and formatting and guarantee you valid content in every document.
Let's look at a document created with the Meeting Minutes customization, to see how this works. From within XMetaL Author, close any open files, then choose File>Open. Find the directory in which XMetal is installed, go to XMetaL 4.5 >Developer >Samples >MeetingMinutes >SampleDocs, and open the file called T-App Design.xml.
You'll see a file like the one below.
Take a moment to familiarize yourself with this file and the elements within it. Choose View>Plain Text or View>Tags On, and see how the XML tags relate to what an XMetaL author sees on the screen.
"Displaying As" an XFT form
Now let's return to the Meeting.ctm file, and see how the Display As property helps us to achieve what we see in the T-App Design.xml file.
In the main view of the Meeting.ctm file, select AgendaItem. Note that the Display As column for AgendaItem shows "XFT", short for an XMetaL Form Tool object.
In the Properties window, click "Advanced Display Type", then in the property value field, click the elipsis button (...). The Display As window appears.
The XFT Form field on the Display As window shows the filename of the XFT form used by the AgendaItem element.
If you click the Setup button, you'll start the XFT Form Wizard. This wizard lets you quickly decide:
  1. Which XFT file to use,
  2. Whether to embed the form or display it in a separate window,
  3. Whether the form should replace element content, or come before or after it, and
  4. Whether the form display should be conditional or based on a script.
Viewing an element "Displayed As" an XFT form
Now let's see how the Display As property works in action. Return to the T-App Design.xml document, and click the Minutes subheading just following the Agenda items. Your cursor will appear to the right of the subheading.
In the Resource Manager pane next to the document view, click "Insert Agenda Item". (If you don't see the Resource Manager pane, click View>Resource Manager.) An "AgendaItem" element will appear in your document.
Change views to Plain Text and Tags On to get a clearer understanding of how the Display As property operates. You'll find it invaluable in your work!
"Displaying As" an ActiveX Control
You can also use the Display As property to display elements as ActiveX controls.
In the main view of the Meeting.ctm file, select Participant. Note that the Display As column for AgendaItem shows "XFT", short for an XMetaL Form Tool object.
In the Properties window, click "Advanced Display Type", then in the property value field, click the elipsis button (...). The Display As window appears.
Change the Insert option button choice from XFT Form to In-place Control.
In the ProgID/ClsID field, enter the identifer for the control you'd like to use. If you don't know the name of this identifier, click the Browse button. You'll be able to choose from a list of common controls, identified by their common English names.
If the control you'd like to use is not in this list, search for its ID in the control documentation, or if you are an advanced user, in the registry itself. Enter that ID into the ProgID/ClsID field.
Type a script prefix into the Script Prefix field. You'll use this prefix when writing macros that enable the control to communicate with XMetaL.
Check the Use Bitmap Printing checkbox if your authors are likely to print their documents and would like to see a printout similar to what they see onscreen.
For the purposes of this tutorial, click Cancel so your changes are not saved.
Setting the "Followed By" Property
If you press the Enter key while in XMetaL Author, by default a new element of the same type will be created.
However, if the DTD does not permit two elements of the same type to follow one another, or if you just want one element type to always be followed by a specific different element type, you can set this using the "Followed By" property.
In the Meeting.ctm file, click ItemizedList. Scroll down the Properties window to the Followed By property. Note that the element ItemizedList is always to be followed by the element Para. This means that every time you hit the Enter key twice at the end of an itemized list, you'll switch over to a Para element.
Specifying "On Insert" content
The "On Insert" property allows you to specify what the content of an element will be at the time the element is first created. This property is most useful for inserting "replacement text".
Replacement text is text that's meant to serve as a prompt or a reminder to the user of what sort of content should be entered in this element. Replacement text acts like a screen field containing text that's meant to be overtyped.
In the Meeting.ctm document, select the element Para. In the Properties window, scroll down to the MiniTemplate property. Position your cursor over the property value field, and you'll see the code that displays replacement text "on insert" of the Para element.
Replacement text is contained within xm-replace_text processing instructions. For example:
<Para><?xm-replace_text {Paragraph} ?></Para>
Now switch back to the T-App Design.xml document, and click at the end of the bullet point in the Minutes that reads "Dropped terminal input requirement". Then hit the Enter key.
You'll see a new paragraph element, displaying the dummy text "Paragraph". Click anywhere in this text and start typing, and the word "Paragraph" will be replaced by your input.
Specifying an "On Insert" Script
Just as you can specify replacement text for an element, so can you specify a script to be loaded and run whenever a particular element from the current DTD is inserted.
JavaScript, VBScript, or any script that conforms to the Microsoft Scripting Engine interface will work from this property.
Consider this example:
<Warning><Para> <?xm-replace_text {Warning}?> </Para></Warning>
The same results can be obtained with this VBScript code:
Selection.InsertElement "Warning" Selection.InsertElement "Para" Selection.InsertReplaceableText "{Warning}"
Setting the "Text Layout" Property
XMetaL uses spaces, indentation, and line breaks to format "raw" XML text files so they are readable in XMetaL Author's Plain Text view. This formatting is called "text layout", and is controlled by the Text Layout property.
You may find this formatting helps with reading the printout of a source file, but you can turn it on or off as you choose, globally, or by element.
Look for a moment at the Meeting.ctm file list of customization elements. At the top of the list, you'll see the #GLOBAL element, whose properties affect all other elements.
We'll talk more about the #GLOBAL element at the end of this lesson. For now we need to know only how this element affects text layout globally.
Look in the Properties window. At the top of the list of #GLOBAL properties is Disable Text Layout, with a potential value of either Yes or No.
If you set this property to Yes, all text layout will be disabled for all elements in this customization.
If you set it to No, all elements will use text layout to format text for the Plain Text view in XMetaL Author. You can then go through and disable the feature for any individual elements as you see fit.
Setting the "Treat As" Property
The "Treat As" property lets you set some of the behaviours of individual elements in XMetaL Author documents, by "treating" them as paragraphs, images, lists, toggles, and the like.
Select any element in the Meeting.ctm file, and in the Properties window, scroll to the Treat As property. Click the property value drop-down list, and look at the options.
General: The General setting means this element will not be treated in any special way.
Paragraph: The Paragraph setting affects the behaviour of the element in two ways:
  1. If an XMetaL Author user tries to enter text where text is not allowed, but where a new paragraph element is permitted, the program will insert a new paragraph element. Author looks in its Customizations dialog box and inserts the first element that has its "Treat As" property set to "Paragraph".
  2. If an XMetaL Author user presses the Enter key at the end of any element, and there is no "Followed By" element or required element, and the element cannot be split, XMetaL inserts a new paragraph element.
Toggle Element: Treating an element as a Toggle Element means it is affected by the Bold, Italic, and Underline toggle buttons in the Formatting toolbar. You can also map an element to a toolbar button for a macro.
In the Properties pane, click the Categorized button. Expand the Treat As property by clicking the little plus (+) sign next to its name. Change the Treat As Type to either Bold, Italic, Underline, or Macro.
If you select Macro as the Treat As Type, a new field called MacroName appears. Enter the name of the macro you want to use in that field.
Image Element: Treating an element as an Image Element allows the XMetaL Author user to insert images using Insert>Image or the Insert Image toolbar button.
In the Properties pane, Make sure you've clicked the Categorized button. If it is not already open, expand the Treat As property by clicking the little plus (+) sign next to its name. Change the Treat As Type to Image Element. You'll be able there to enter the Alternate Text, Height, Source, and Width of any image you'd like to appear in this element.
List Element: XMetaL Author supports three types of lists: bulleted, numbered, and definition lists.
Numbered and bulleted lists consist of a parent "list" element, and any number of nested "list item" elements. You can identify these elements in the ListHeader (HTML equivalent = LH) and ListItem (HTML equivalent = LI) fields.
Definition lists are two-part lists that consist of a list element and two kinds of sub-elements: term elements and definition elements. These elements are similar in structure to the HTML elements DL, a list element, DT, a term element, and DD, a definition element.
Setting the "Alias" Property
The "Alias" property allows you to give a plain language name to an element name. This can help authors better understand what elements are used for.
An Alias is especially valuable for implementations in languages other than the language of the DTD.
For example, an element which the developer has named "T" could have an alias of "Title" for an English-language implementation, and "Titre" for French.
The real-language name appears in the following places in XMetaL Author:
  1. In the Element List pane
  2. In the element list box in the Attribute Inspector.
  3. In the element tag icons in Tags On view.
  4. In the element tag tooltip text.
  5. As the current element or its ancestors in the context area at the bottom of the main editing pane between the View buttons and the horizontal scroll bar (Normal and Tags On views only).
  6. In place of the element name when the element appears in a change list, if one has been configured.
If you do not enter a real-language name for the element, the element name from the DTD is used instead.
Setting the "Description" Property
You can enter a description of an element in its "Description" property. When the element is highlighted in the Insert Element pane, this description appears beneath it.
If you don't enter a description for the element, the element name from the DTD is used instead.
Setting the #GLOBAL Element
We discussed the #GLOBAL element's Disable Text Layout property earlier in this lesson in connection with the Text Layout property.
The #GLOBAL property also allows you to set what's called the Paragraph Order.
When someone in XMetaL Author presses the Enter key, XMetaL inserts a new element, according to the rules laid out in the DTD or Schema.
A Paragraph Order is a series of elements which may potentially be valid elements to insert after the Enter key is pressed.
If you set a Paragraph Order, XMetaL will search your sequence of possible elements, and insert the first valid element in the list. If no items in the list are valid for this location, XMetal will ignore the Enter key.
The #GLOBAL element can also be used to set namespaces. Namespaces are a feature of XML that permits documents to contain elements defined in more than one DTD.
XMetaL provides minimal support for the HTML namespace, through the Namespace Editor.
To edit namespaces:
  1. If it is not already visible, open the Solution Explorer.
  2. Click the customization in the Solution Explorer.
  3. Double-click the CTM file.
  4. Right-click the #GLOBAL element and select Namespaces from the shortcut menu. This opens the Namespace Editor.
  5. Click the Prefix you want to change and enter the new value.
  6. When you are finished changing the namespace information, click OK.
Go to the next lesson: Using Scripts in XMetaL Developer...
Last modified: Thursday, May 20, 2004 2:49:41 PM