Debugging
an XMetaL Customization
Understanding
the XMetaL Debugging Process
In the last
two lessons, we learned how to build an XMetaL customization and set script and
customization properties. Now let's learn a couple of tips for debugging and
testing.
This lesson
assumes you are familiar with the Visual Studio .NET debugging functions and
with best practices for scripting in the VS .NET environment. If not, please
refer to the VS .NET online documentation before continuing.
Using XMetaL
Developer, you can debug and test the following objects:
- Scripts
- Customization
(CTM) files
- Cascading Style
Sheets (CSS)
,
By allowing you to run scripts and customizations without deploying them, the
XMetaL Integrated Development Environment makes integrated testing and
debugging of your entire implementation easy. XMetaL 4.5 incorporates several
enhancements to XMetaL's debugging features, including multiple break points
and improved variable tracing.
This lesson
will take about 25 minutes to complete.
Testing
and Debugging a Script
Let's return
to the MiniJournalist project.
- If the
MiniJournalist customization is not still visible in the Solution Explorer from
the last lesson, choose File>Open
Solution.
- Find the directory
in which XMetal is installed, go to XMetaL
4.5> Developer> Samples> MiniJournalist, and open the file
called MiniJournalist.sln.
Now let's
create a new script, assign it to a button, and test it in XMetaL Author. We'll
start by creating a syntax error, so that you can see what errors in your
script will look like, on the off-chance that there should ever be any.
First, create
the script:
- From the Solution
Explorer, right-click the Macros
folder, and click Add>Add New
Item. The Add New Item dialog opens
- Double-click the
Macro Script icon to open the
Create Script File dialog.
- Give it the name
MyTestMacro, and keep the language as
JScript. Once you are finished naming
it, click Finish.
- When the script
editor opens, add the following erroneous line of code:
Application.Alert
("This is my macro"):
(Note the
intentionally-wrong colon ":" at the end of the line, instead of the semicolon
";")
- Now build your
customization by pressing F5.
OK, now take a
deep breath and get ready to create a custom toolbar with a custom button,
running your custom script:
- Once XMetaL Author
opens, open the following file:
...\Program
Files\Blast Radius\XMetaL
4.5\Developer\Samples\MiniJournalist\SampleDocs\SimpleGuide.xml
- Once the file
opens, right-click the toolbar area.
- From the context
menu that opens, select Customize.
The Toolbar and Menu Customization
dialog opens:
- Click
New to open the
New Toolbar dialog, and type,
"MyToolbar" in the text field.
- Click
OK and note that a new blank toolbar
appears in XMetaL Author.
- In the
Toolbar and Menu Customization
dialog, click the Buttons tab. Then,
in the list on the left, click the MiniJournalist Macros entry. The dialog
changes to list all available macros for the customization. The macro you
created should appear in the list under Macros (on the right side of the dialog),
and if it is not already selected, select it now.
- Now we are going
to assign an image to the button. Click the Choose Image button to open the
Choose Toolbar Button Image dialog.
-
First, select
a category from the list on the left (we chose
Miscellaneous).
Next, select
an image from the selected category (we chose the red coffee cup).
- You are returned
to the Toolbar and Menu Customization
dialog. Now drag the image you just selected from the dialog to the empty
toolbar that was created earlier, and drop it onto the toolbar. Now you have a
custom toolbar with your own selected image, and that will run your own custom
macro.
- Close the
Toolbar and Menu Customization
dialog.
- Close XMetaL
Author before you run your macro! This is because the
customization you just made to the toolbar will not be saved until you exit
XMetaL Author.
Now let's test
the macro. We already know that there is an error in the code, so this will be
a good way to learn how to change and re-execute that code.
- From XMetaL
Developer, Save and
Build the
MiniJournalist customization.
- Once XMetaL Author
opens, open the following file:
...\Program
Files\Blast Radius\XMetaL
4.5\Developer\Samples\MiniJournalist\SampleDocs\SimpleGuide.xml
- Locate your new
toolbar and click the button. Note that your macro has an error!
- Switch to XMetaL
Developer and, if it is not already open, open the
MyTestMacro.js file.
- Fix the error
(replace the colon ":" with a semicolon ";") and save the macro file.
- Switch back to
XMetaL Author and try clicking the button again. The message you entered in the
Application.Alert method should now display without error.
Testing and Debugging Customization Properties
By moving back
and forth between XMetal Developer and XMetal Author, you can immediately check
the results of your customization property configurations.
Let's use the
Meeting Minutes customization to illustrate this.
- Open the Meeting
Minutes customization in the Solution Explorer: Choose
File>Open Solution.
- Find the directory
in which XMetal is installed, go to XMetaL
4.5> Developer> Samples> MeetingMinutes, and open the file
called MeetingMinutes.sln.
Open the
MeetingMinutes customization file, named "Meeting.ctm". You'll see all the
MeetingMinutes customization properties in the XMetaL Developer main
window.
Let's take a
closer look at one of the elements in the CTM file, "TopicDiscussion". Select
this element, and note that the On Insert
column shows that there is "XML Content" displayed on the insertion of
this element.
Now look in
the Properties window. Scroll down to
the "On Insert" property, and click on the elipsis (...) next to the MiniTemplate field. You'll
see the following code:
<TopicDiscussion><Discussion><?xm-replace_text
{Enter topic of
discussion}?></Discussion></TopicDiscussion>
If you recall
from the lesson on customization properties, this string will display a line of
replacement text on insertion of the TopicDiscussion element.
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.
The On Insert
replacement text property is a customization that's easy for us to test:
- First open XMetaL
Author, and reopen the file XMetaL 4.5>
Developer> Samples> MeetingMinutes >SampleDocs >T-App
Design.xml.
- Choose
View>Tags On.
- Scroll down to the
first instance of the TopicDiscussion
element, immediately following the Minutes heading.
- Place your cursor
between the TopicDiscussion tag and
the following Discussion tag.
- On the Element
List pane, double-click TopicDiscussion.
- Author will insert
the TopicDiscussion element, displaying the replacement text "Enter topic of
discussion."
Let's change
this replacement text to show how easy it is to change a customization property
and test the results.
- Without saving
your changes, close the T-App Design.xml document in XMetaL Author and return
to XMetaL Developer.
- Select the
TopicDiscussion element.
- In the
Properties window, scroll down to the
On Insert property.
- Click the ellipsis
(...) in the MiniTemplate field.
- Change the text
"Enter topic of discussion" to "Discussion Topic Title".
- Click
OK.
- Click
Build>Build Solution.
- When the build is
finished, re-open the T-App Design.xml document.
- Choose
View>Tags On.
- Scroll down to the
first instance of the TopicDiscussion
element, immediately following the Minutes heading.
- Place your cursor
between the TopicDiscussion tag and
the following Discussion tag.
- On the Element
List pane, double-click TopicDiscussion.
- Author will insert
the TopicDiscussion element, displaying the replacement text "Discussion Topic
Title."
Experiment
with changing other element properties and testing the results. It's easier
than you think!
When you're
finished, close the T-App Design.xml document. Since you've been experimenting,
don't bother to save your changes.
Testing Cascading Style Sheets
You can test
Cascading Style Sheets (CSS) in the same way we tested our customization (CTM)
file properties.
In XMetaL
Developer, go to the Solution Explorer and double-click the "Meeting.css" file.
You'll see a window similar to the one below:
XMetaL
Developer gives you a simple form for changing CSS properties.
Build and run
the MeetingMinutes customization.
- In XMetaL Author,
open the document:
...\Program
Files\Blast Radius\XMetaL 4.5\Developer\Samples\MeetingMinutes\T-App
Design.xml
- Place the cursor
into the Meeting Subject ("T-App Design" at the top of the page).
- From the
Edit menu, click
Edit CSS style in XMD.
- You are switched
automatically to XMetaL Developer and the CSS Editor is open with the
MeetingSubject element selected.
- Change some
properties of the element, such as the size and color. Change to other tabs to
view and change other properties.
- Save the CSS file
and return to XMetaL Author. Note how your changes are automatically reflected
in the document.
Go to the next lesson: Working with
DTDs...
Last modified: Friday, May 21, 2004 11:20:39 AM