Advanced
Lesson 6: Implementing a Custom Container Application for XMetaL for ActiveX
using VB.NET
Getting
started
In this
lesson, you'll learn how to create a simple container application for XMetaL
for ActiveX using VB.NET. This simple application will load a document, load a
customization, and validate a document with a click of the mouse.
Don't worry
about creating a document and a customization. The focus of this lesson is
writing the code for the container application. You will use the Mini
Journalist sample provided with XMetaL Developer. Click
Start>Programs>XMetaL
4.5>Developer>Samples>Mini Journalist Customization to view the
customization.
This lesson
assumes you are familiar with the Visual Studio .NET development environment
(IDE) and the Visual Basic language. If not, please refer to the VS .NET online
documentation before continuing.
If you want to
complete the optional XMetaL - Central exercises, you should be familiar with
the XMetaL - Central console and creating packages. Refer to the tutorials
included with XMetaL - Central before trying these exercises. You must also be
a registered XMetaL - Central user with the role of developer.
This lesson
will take about 40 minutes to complete.
Creating
a Visual Basic project
In this
exercise, you will create a Windows application, which will be used as the
container application for XMetaL for ActiveX. It's not required to use a
Windows application; you can use any Visual Basic project template that
provides a user interface as the container application for XMetaL for ActiveX,
such as an ASP .NET Web Application.
To create a
new Windows application:
- In Visual Studio
.NET, click File>New>Project
- Select
Visual Basic Projects as the project
type.
- Select
Windows Application as the template.
- Type a descriptive
name for the application, such as
MyXMContainerApp.
- Change the
location to save the application, if necessary.
- Click
OK.
The new
project appears in the Visual Studio environment. Your project should have a
Windows form created by default. If a form is not created, add one to your
project now.
Change the
form properties to give the form a descriptive name, like
MyXMContainerForm,
and descriptive text, like
XMetaL
for ActiveX container application, before continuing.
View the
properties of the Visual Basic project, and make sure the form is the Startup
object for the Windows application.
Adding
XMetaL for ActiveX to a form
You can drag
and drop the XMetaL for ActiveX control onto a Windows form, just like any
Windows form object. But before you can drag and drop, you must add the XMetaL
for ActiveX control to the Visual Studio Toolbox.
To customize
the Toolbox:
- Display the
Toolbox, if it is not already visible.
- Click the
Windows Forms tab. You can add the
XMetaL for ActiveX control to any tab of the toolbar, but for now let's put the
control with other form objects.
- Right-click in the
Toolbox, and choose Customize Toolbox
from the context menu.
- Click the
COM Components tab of the Customize
Toolbox dialog box.
- Enable (check) the
XMetaL 4.5 for ActiveX check box, and
click OK. The
Control icon appears in the Toolbox,
as shown in the picture below:

Now you can
drag the XMetaL for ActiveX Control
from the Toolbox to your Windows form. Once you've done that, you can resize
the control (and the form) as necessary. Leave some room on your form to add a
button later.
Take a look at
the properties for the XMetaL for ActiveX control. You'll notice many of the
standard properties for Windows form objects, such as
Name,
Location,
and Size.
You'll also notice some properties that are specific to XMetaL for ActiveX,
such as
ChangeColorByAuthor,
DeletionColor,
DeletionStyle,
InsertionColor,
InsertionStyle,
and LicenseID.
Change the
default name of the XMetaL for ActiveX control to something more descriptive,
like MyXMControl,
before continuing.
Loading
an XML document into the custom application
In this
exercise, you will load an XML document into XMetaL for ActiveX automatically
when your custom application is started.
To load an XML
document:
- View the form in
design view.
- Double-click the
form. The following code automatically appears:
Private
Sub MyXMContainerForm_Load(ByVal sender As Object, _ ByVal e As
System.EventArgs) Handles MyBase.Load End Sub
- If you installed
XMetaL in the default location, add the following code to the subroutine:
MyXMControl.LoadFromFile("C:\Program
Files\Blast Radius\XMetaL 4.5\" _ &
"Developer\Samples\MiniJournalist\SampleDocs\SimpleGuide.xml")
If you
installed XMetaL in another location, use the full path to
SimpleGuide.xml
as the first argument to
LoadFromFile.
It's not
necessary to load a document when the application starts. Typically, you would
use an Open File dialog box to prompt
the user to load an existing document, then call
LoadFromFile
after the user selects a file and clicks OK. You can also use the
LoadFromString
method to load documents into XMetaL for ActiveX, which works very well when
you want to create a new document.
Next, you will
load a document customization when
SimpleGuide.xml
is loaded. If you are using XACs to deploy document customizations, complete
the Loading a XAC exercise, skip the
next two exercises, and proceed to the Calling the XMetaL API to validate an XMetaL for
ActiveX document exercise. If you are using XMetaL - Central to deploy
document customizations, skip the next exercise and proceed to the
Creating a Mini Journalist package
exercise.
Loading
a XAC (optional)
When you
deploy a document customization as a XAC set, it must be loaded when the
document is loaded.
In this
exercise, you will load the Mini Journalist XAC. If you have not built the Mini
Journalist XAC before, you should do it now. To build the Mini Journalist XAC
to the default location:
- Click
Start>Programs>XMetaL
4.5>Developer>Samples>Mini Journalist Customization.
- Click
Build>Build Solution.
- Close that
instance of VS .NET, and return to the custom container application.
Now that you
have built the XAC, we can use it to load the document customization for
SimpleGuide.xml.
To do this:
- View the code for
the Windows form.
- Replace
MyXMControl.LoadFromFile("C:\Program
Files\Blast Radius\XMetaL 4.5\" _ &
"Developer\Samples\MiniJournalist\SampleDocs\SimpleGuide.xml")
(the line
you wrote in the last exercise) with
MyXMControl.LoadFromFile("C:\Program
Files\Blast Radius\XMetaL 4.5\" _ &
"Developer\Samples\MiniJournalist\SampleDocs\SimpleGuide.xml", _ "C:\Program
Files\Blast Radius\XMetaL 4.5\Developer\Samples\MiniJournalist\" _ &
"BuildProject\MiniJournalist.xac")
If you did not install XMetaL to the
default location, or if you did not build the Mini Journalist XAC to the
default location, change the paths to match the actual paths to
SimpleGuide.xml
and MiniJournalist.xac.
Save your
changes, then try running your container application.
SimpleGuide.xml
loads automatically into XMetaL for ActiveX, complete with its document
customization. Your container application should look something like
this:
Skip the next
two exercises and proceed to the Calling the
XMetaL API to validate an XMetaL for ActiveX document exercise.
Creating
a Mini Journalist package (optional)
XMetaL -
Central uses packages to deploy document customizations. A package can be
created from a XAC set, or it can be created from a collection of individual
customization files (such as
css
or dtd
files).
In this
exercise, you will create a package for the Mini Journalist document
customization. Once you create a package, set the groups for the package, and
initialize the XMetaL - Central Agent, XMetaL for ActiveX will load this
package from XMetaL - Central whenever a matching document is loaded.
For this
exercise, you need access to the XMetaL - Central console. For information
about using the XMetaL - Central console, and creating packages, see the
tutorials included with XMetaL - Central.
To create a
package for the Mini Journalist customization:
- Create a new
XMetaL - Central package for the Mini Journalist customization.
- Add the
journalist.css,
journalist.ctm,
and journalist.dtd
files as assets to the XMetaL - Central package. These files can be found in
C:\Program
Files\Blast Radius\XMetaL 4.5\Developer\Samples\MiniJournalist (if you
installed XMetaL in the default location).
- Create the
following package rules:
- Application
Name equals XMetaL for ActiveX
- and SystemID
equals journalist.dtd
- Set the groups
for the package. Make sure that everybody that needs to use the Mini Journalist
customization has access to the package.
- Save the package.
You can now
load this package in your container application for XMetaL for ActiveX.
Loading
a document customization using the XMetaL - Central Agent (optional)
Before you can
use the package you defined in the last exercise, you have to initialize
communications between XMetaL for ActiveX and the XMetaL - Central Agent.
If you have
not already done so, you should install the XMetaL - Central Agent before
continuing.
To initialize
the XMetaL - Central Agent:
- View the code for
the Windows form, if it is not already visible.
- Scroll to the
MyXMContainerForm_Load
event.
- Add the following
code to the beginning of the
MyXMContainerForm_Load
event, before the call to
LoadFromFile:
Dim
MyXMCentralAgent MyXMCentralAgent = CreateObject("XmcAgent.AgentHost")
MyXMCentralAgent.Synchronize() MyXMControl.XMCentralAgent =
MyXMCentralAgent
This code creates a new XMetaL - Central Agent object,
synchronizes it with the XMetaL - Central server, and makes the XMetaL -
Central Agent available to XMetaL for ActiveX.
Save your
changes, then try running your container application.
SimpleGuide.xml
loads automatically into XMetaL for ActiveX, complete with its document
customization. Your container application should look something like
this:

Calling
the XMetaL API to validate an XMetaL for ActiveX document
You've already had some practice with the XMetaL for ActiveX API.
LoadFromFile
is an XMetaL for ActiveX method for opening an XML document. The XMetaL API is
exposed through the XMetaL for ActiveX API using the
Document
and Selection
properties. These properties are identical to the global
Document
and Selection
objects in XMetaL.
In this
exercise, you will add a button that, when clicked, validates the active
document.
Validate
is one of the many XMetaL API calls that you can use in an XMetaL for ActiveX
container application. The XMetaL Programmer's Guide describes the XMetaL API
in detail.
It's best if
you type the code into Visual Studio yourself. That way, you can explore the
other properties, methods, and events available to each object using
Intellisense.
To validate
the active document in your container application:
- Open the Windows
form in Design view.
- Drag a button from
the Toolbox to the form, resizing as necessary.
- Change the text of
the button caption to
Validate,
and rename the button
ValidateButton.
- Double-click the
button. The following code automatically appears:
Private
Sub ValidateButton_Click(ByVal sender As System.Object, _ ByVal e As
System.EventArgs) Handles btnValidate.Click End Sub
- Add the following
code to the subroutine:
MyXMControl.Document.Validate()
This code calls the XMetaL validation routine on the active document. After
this call, XMetaL knows whether or not the document is valid. However, the user
doesn't know whether or not the document is valid, so we need to write some
more code.
- Add the following
code after the call to the validation subroutine:
If
MyXMControl.Document.ValidationErrorList.count = 0 Then MsgBox("The document is
valid.") Else MsgBox("The document has " _ &
MyXMControl.Document.ValidationErrorList.count _ & " validation error(s).")
End If
This code tells the user the number of validation errors, if any.
Save your
changes, then try running your container application. Click the
Validate button. You should receive a
message stating that the document is valid. Your container application should
look something like this:

Handling
an XMetaL for ActiveX event
In this
exercise, you will handle the
OnViewChange
event, and display the name of the new view whenever the user switches views.
You will learn to retrieve XMetaL for ActiveX event parameters, and how to use
enumerated types.
It's best if
you type the code into Visual Studio yourself. That way, you can explore the
other properties, methods, and events available to each object using
Intellisense.
To handle an
XMetaL for ActiveX event:
- View the code for
the Windows form, if it is not already visible.
- In the left
drop-down box, select
MyXMControl.
- In the right
drop-down box, select
OnViewChange.
The following code automatically appears:
Private
Sub MyXMControl_OnViewChange(ByVal sender As Object, _ ByVal e As
AxXMetaLControlLib._IXMetaLControlEvents_OnViewChangeEvent) _ Handles
MyXMControl.OnViewChange End Sub
Notice that all XMetaL for ActiveX
events are listed in the right drop-down box.
- Add the following
code to this subroutine:
If e.newView = XMetaLControlLib.SQDocViewType.sqViewNormal Then MsgBox("Now
entering Normal View.") ElseIf e.newView =
XMetaLControlLib.SQDocViewType.sqViewTagsOn Then MsgBox("Now entering Tags On
View.") End If
The variable
e
above is used to access the parameters of the XMetaL for ActiveX event. The
XMetaLControlLib
is used to access enumerated constants defined by XMetaL, such as
SQDocViewType.
Note that only Normal view and
Tags On view are available in XMetaL
for ActiveX.
Save your
changes, then try running your container application. Click

to switch to
Tags On view.
You should receive a message telling you that you are entering
Tags On view, and your container
application should look something like this:
Dismiss the
message, and click

to return to
Normal
view.
Testing
the application
You've been
testing your container application as you go, by running it and checking the
functionality.
Before
deployment, though, you should thoroughly test your application under a number
of conditions. Be sure to test your application in an environment that
simulates the desktop of the average user. In most cases, this means testing on
a machine without XMetaL Developer or Visual Studio .NET, and instead testing
on a machine with XMetaL for ActiveX and the .NET Framework.
Note: You cannot use the XMetaL Developer
license key to register XMetaL for ActiveX. Make sure you have a separate
license key for XMetaL for ActiveX before testing.
Our sample
application has some particular areas that deserve testing:
- We've hardcoded
the file name into the
LoadFromFile
call. What happens if the file does not exist in that location, or if the file
exists but is not a well-formed XML file?
- What happens if
XMetaL for ActiveX or XMetaL - Central Agent (if applicable) are not installed?
- What happens if
the document customization is not available, or if the document customization
is corrupt?
While testing,
you should make sure that your container application fails gracefully in any of
the above scenarios. The sample application you created contains no
error-handling code. As an exercise, you can try to make this container
application more robust.
Deploying
the application
You should
carefully consider the different methods of packaging and distributing files
for your container application. Some deployment options include placing
application files on the Internet or on an intranet, creating an installation
CD, or emailing a compressed version of the application files to users.
For this container application, you need to distribute the following
files:
-
MyXMContainerApp.exe
- AxInterop.XMetaLControlLib.dll
- Interop.XMetaLControlLib.dll
- Third-party
installers (if required)
In general,
you should distribute all
dll
and exe
files in the bin subfolder of your
Visual Studio project, along with any required third-party installers.
You should
consider creating an installer to automatically copy these files to the end
user's machine, especially if you are deploying your application widely.
On your
installation CD, you can include all related installers related to your
application. This includes:
- The .NET
Framework. A redistributable installer is available on
Microsoft's
web site. Users of your container application must have the .NET Framework
installed.
- The XMetaL for
ActiveX installer. You can call the XMetaL for ActiveX silent installer from
your installer, and automatically install XMetaL for ActiveX. If you choose to
use the silent installer, you should check to make sure all third-party
software required by XMetaL for ActiveX is installed before installing XMetaL
for ActiveX. Note: Do not install
XMetaL for ActiveX if it is already installed.
- The third-party
software requirements for XMetaL for ActiveX are:
- Microsoft
Internet Explorer (5.0 or higher)
- Microsoft
(MSXML) XML Parser version 3 or higher
The installer for MSXML is available in the
redist folder of the XMetaL CD. See
Microsoft's
web site for information about downloading Internet Explorer.
- The XMetaL -
Central Agent installer, if you are using XMetaL - Central to deploy document
customizations.
- The third-party
software requirements for XMetaL - Central Agent are:
- Microsoft
(MSXML) XML Parser version 3 or higher
- Java Runtime
Environment (JRE) version 1.3.1 or higher
The installers for these products are available in the
redist folder of the XMetaL - Central
CD.
Taking
the next step in application development
The XMetaL
Programmer's Guide provides detailed information about the XMetaL for ActiveX
API and about developing XMetaL for ActiveX container applications. Use it as a
resource when doing your own application development.
You can also
model your custom container application on the sample that comes with XMetaL
Developer. Click Start>Programs>XMetaL
4.5>Developer>Samples>Visual Basic container application to
view the sample.
Last modified: Friday, May 21, 2004 3:55:58 PM