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:
- Which XFT file to
use,
- Whether to embed
the form or display it in a separate window,
- Whether the form
should replace element content, or come before or after it, and
- 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:
- 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".
- 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:
- In the Element
List pane
- In the element
list box in the Attribute Inspector.
- In the element tag
icons in Tags On view.
- In the element tag
tooltip text.
- 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).
- 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:
- If it is not
already visible, open the Solution Explorer.
- Click the
customization in the Solution Explorer.
- Double-click the
CTM file.
- Right-click the
#GLOBAL element and select Namespaces from the shortcut menu. This opens the
Namespace Editor.
- Click the Prefix
you want to change and enter the new value.
- 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