Using Scripts in XMetaL Developer
Understanding the XMetaL Developer Scripting Environment
The scripting interface provides access to XMetaL Author or XMetaL for ActiveX via an object model based largely on the Document Object Model (DOM) and the Microsoft Word VBA model.
Let's establish some definitions up front for important XMetaL terms you'll come across often:
  1. An XMetaL macro is a set of instructions consisting of zero or more condition statements, zero or more API commands, and/or zero or more functions.
  2. A function can run other macros, but a function must be contained inside a macro, although it is not a macro itself.
  3. A macro can be imported into your XMetaL project through MCR files or added in as script files. A function is a part of the MCR file, but it cannot be imported (although you can cut and paste the code).
Scripts built using XMetaL Developer are deployed with your customization; however, prior to deployment you may want to test scripts. The development environment has an easy-to-use interface to run scripts that are being developed without your having to deploy.
XMetaL uses the Visual Studio .NET scripting interface. This lesson assumes you are familiar with Visual Studio .NET scripting functionality and with best practices for scripting in the VS environment.
In this lesson we'll focus on showing you how to use new or existing scripts while building customizations within the XMetaL Developer environment. For specific information about coding issues or writing scripts from scratch, please refer to the XMetaL Programmer's Guide or to the Visual Studio .NET online documentation.
This lesson will take about 15 minutes to complete.
Adding a New Script to a Customization
For each script you want to create in your XML project, you must add a script object to your customization.
Let's return to the Meeting Minutes project to show you how to add a new script.
  1. If the Meeting Minutes customization isn't still open 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> MeetingMinutes, and open the file called MeetingMinutes.sln.
You'll see that there are several script file types that form this project, but no MCR files. That's because the macro files are compiled during the build process and appear only in the output directory.
Follow the steps below and walk through adding a new function or script to your customization:
  1. From the Project menu, select Add New Item.
  2. Double-click New Script File and then click Open.
  3. The Create Script dialog box opens.
  4. Enter these settings:
    1. Macro Name - You can select from the list of built-in macro events fired by XMetaL Author or XMetaL for ActiveX, or you can type a name for a new macro file.
    2. Select scripting language for new macro - By default, JScript and VBScript are provided. Perl scripts and Python script can also be selected from this list, provided the scripting languages are installed and registered on your system. A single macro file can contain any of these types of scripts, or any combination of them.
    3. Note: Although you can add a Perl script or Python script to your XMetaL project (provided the scripting language is installed), there are some considerations:
      1. Intellisense does not recognize the objects, therefore does not provide the list of objects, properties, and methods.
      2. The text of the scripts is displayed without colors identifying the scripting syntax.
      3. Breakpoints set in these scripting languages do not halt execution of the scripts.
      You can install Perl and Python scripting hosts separately, but they are not supplied with XMetaL.
    4. Insert this as a separate script file (not part of the MCR) - If you want this script to be a separate file in your project, check this option and provide a name in the Script File Name field. The new file appears in the solution explorer as a standalone file that is part of your project, but is not added to the Macros folder. It is not treated as an XMetaL Author macro.
  5. Click Finish.
    The script editor automatically opens. Some script is automatically added to the macro to enable VS.NET IntelliSense functionality. Do not delete or modify this automatically-generated script; simply begin your own script below the existing code.
Adding an Existing Script to a Macro File
XMetaL Developer allows you to import existing individual scripts or an existing macro file into a customization.
A macro file is an XML file that identifies individual scripts with <MACRO></MACRO> element tags. Thus a macro file looks something like this:
<MACRO> ... //script1 ... </MACRO> <MACRO> ... //script2 ... </MACRO>
You can import a single script into your customization, or you can import an entire macro file containing one or more scripts. These scripts will appear as individual objects in your project, and are not compiled into an MCR file until the project is built.
It is not recommended to import a macro file as a stand-alone file from another project, since you won't be able to debug it before deployment.
Now let's import a single script into a macro file:
  1. Click Project>Add Existing Item.
  2. Find and select a suitable script and click Open.
  3. The Import as Macro dialog opens with these fields you can use to control the behavior of the macro:
    1. Macro name - The name of the macro. You can specify your own name, or accept the default name (based on the filename). You can also select a macro from the drop-down list, in which case the script will become part of the selected macro.
    2. Hot Key - Use these setting to control which keys in XMetaL Author will launch your macro.
    3. Hide - Use this setting to determine whether or not the macro is hidden from the user.
    4. Description - You can enter your own description of the macro.
  4. Click OK.
It's as simple as that.
Adding scripts from an existing macro file, let's say from another project, is almost as easy:
  1. Click Project>Import XMetaL Macros.
  2. This opens the Import Macro from File dialog.
  3. Browse to the folder containing your scripts and select it. The Select Macros to Import dialog opens.
  4. Select the macros in the Macros Available in the Source MCR pane, and click Add. Alternatively, if you want to add all of the macros in the file, click Add All.
  5. Click OK.
Editing a script
When creating XMetaL scripts, it is expected that you will have to frequently modify your code. You can edit your scripts when you are not debugging a project; however, you cannot always edit your scripts during a debugging session.
To edit the script after execution is complete, use the VS.NET built-in script editor.
To modify an object in a customization:
  1. If the script you want to modify is not visible in the Solution Explorer, click the plus sign to expand the macros folder.
  2. Double-click the script you want to modify and the scripting editor opens with the script displayed.
Changing Script Properties
Script objects have configurable properties that you can set while creating your customization. To set any script properties, select the script in the Solution Explorer, and make changes in the Properties window.
Scripts contain the following properties:
  1. (Name) - The filename of the macro
  2. Description - The description of the macro
  3. FilePath - The filepath to (location of) the script
  4. Hidden - Indicates whether or not the macro is hidden from the user
  5. Language - The scripting language the script is written in
  6. MacroName - The name given to the script at the time of its creation
  7. ShortcutKey - The Hot Keys assigned in XMetaL Author to launch the script
  8. UseAs - Indicates the UseAs type
Go to the next lesson: Debugging a Customization...
Last modified: Thursday, May 20, 2004 3:37:50 PM