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:
- 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.
- A function can run
other macros, but a function must be contained inside a macro, although it is
not a macro itself.
- 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.
- If the Meeting
Minutes customization isn't still open 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> 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:
- From the
Project menu, select
Add New Item.
- Double-click
New Script File and then click
Open.
- The
Create Script dialog box opens.
- Enter these
settings:
- 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.
- 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.
- 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:
-
Intellisense does not recognize the objects, therefore does not provide the
list of objects, properties, and methods.
- The text
of the scripts is displayed without colors identifying the scripting syntax.
- 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.
- 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.
- 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:
- Click
Project>Add Existing Item.
- Find and select a
suitable script and click Open.
- The
Import as Macro dialog opens with
these fields you can use to control the behavior of the macro:
- 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.
- Hot Key - Use these setting to control
which keys in XMetaL Author will launch your macro.
- Hide - Use this setting to determine
whether or not the macro is hidden from the user.
- Description - You can enter your own
description of the macro.
- 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:
- Click
Project>Import XMetaL Macros.
- This opens the
Import Macro from File dialog.
- Browse to the
folder containing your scripts and select it. The
Select Macros to Import dialog opens.
- 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.
- 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:
- If the script you
want to modify is not visible in the Solution Explorer, click the plus sign to
expand the macros folder.
- 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:
- (Name) - The filename of the macro
- Description - The description of the macro
- FilePath - The filepath to (location of)
the script
- Hidden - Indicates whether or not the macro
is hidden from the user
- Language - The scripting language the
script is written in
- MacroName - The name given to the script at
the time of its creation
- ShortcutKey - The Hot Keys assigned in
XMetaL Author to launch the script
- UseAs - Indicates the UseAs type
Go to the next lesson: Debugging a
Customization...
Last modified: Thursday, May 20, 2004 3:37:50 PM