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:
  1. Scripts
  2. Customization (CTM) files
  3. 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.
  1. If the MiniJournalist customization is not still visible in the Solution Explorer from the last lesson, choose File>Open Solution.
  2. 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:
  1. From the Solution Explorer, right-click the Macros folder, and click Add>Add New Item. The Add New Item dialog opens
  2. Double-click the Macro Script icon to open the Create Script File dialog.
  3. Give it the name MyTestMacro, and keep the language as JScript. Once you are finished naming it, click Finish.
  4. 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 ";")
  5. 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:
  1. Once XMetaL Author opens, open the following file:
    ...\Program Files\Blast Radius\XMetaL 4.5\Developer\Samples\MiniJournalist\SampleDocs\SimpleGuide.xml
  2. Once the file opens, right-click the toolbar area.
  3. From the context menu that opens, select Customize. The Toolbar and Menu Customization dialog opens:
  4. Click New to open the New Toolbar dialog, and type, "MyToolbar" in the text field.
  5. Click OK and note that a new blank toolbar appears in XMetaL Author.
  6. 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.
  7. Now we are going to assign an image to the button. Click the Choose Image button to open the Choose Toolbar Button Image dialog.
  8. 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).
  9. 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.
  10. Close the Toolbar and Menu Customization dialog.
  11. 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.
  1. From XMetaL Developer, Save and Build the MiniJournalist customization.
  2. Once XMetaL Author opens, open the following file:
    ...\Program Files\Blast Radius\XMetaL 4.5\Developer\Samples\MiniJournalist\SampleDocs\SimpleGuide.xml
  3. Locate your new toolbar and click the button. Note that your macro has an error!
  4. Switch to XMetaL Developer and, if it is not already open, open the MyTestMacro.js file.
  5. Fix the error (replace the colon ":" with a semicolon ";") and save the macro file.
  6. 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.
  1. Open the Meeting Minutes customization in the Solution Explorer: Choose File>Open Solution.
  2. 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:
  1. First open XMetaL Author, and reopen the file XMetaL 4.5> Developer> Samples> MeetingMinutes >SampleDocs >T-App Design.xml.
  2. Choose View>Tags On.
  3. Scroll down to the first instance of the TopicDiscussion element, immediately following the Minutes heading.
  4. Place your cursor between the TopicDiscussion tag and the following Discussion tag.
  5. On the Element List pane, double-click TopicDiscussion.
  6. 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.
  1. Without saving your changes, close the T-App Design.xml document in XMetaL Author and return to XMetaL Developer.
  2. Select the TopicDiscussion element.
  3. In the Properties window, scroll down to the On Insert property.
  4. Click the ellipsis (...) in the MiniTemplate field.
  5. Change the text "Enter topic of discussion" to "Discussion Topic Title".
  6. Click OK.
  7. Click Build>Build Solution.
  8. When the build is finished, re-open the T-App Design.xml document.
  9. Choose View>Tags On.
  10. Scroll down to the first instance of the TopicDiscussion element, immediately following the Minutes heading.
  11. Place your cursor between the TopicDiscussion tag and the following Discussion tag.
  12. On the Element List pane, double-click TopicDiscussion.
  13. 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.
  1. In XMetaL Author, open the document:
    ...\Program Files\Blast Radius\XMetaL 4.5\Developer\Samples\MeetingMinutes\T-App Design.xml
  2. Place the cursor into the Meeting Subject ("T-App Design" at the top of the page).
  3. From the Edit menu, click Edit CSS style in XMD.
  4. You are switched automatically to XMetaL Developer and the CSS Editor is open with the MeetingSubject element selected.
  5. Change some properties of the element, such as the size and color. Change to other tabs to view and change other properties.
  6. 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