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:
  1. In Visual Studio .NET, click File>New>Project
  2. Select Visual Basic Projects as the project type.
  3. Select Windows Application as the template.
  4. Type a descriptive name for the application, such as MyXMContainerApp.
  5. Change the location to save the application, if necessary.
  6. 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:
  1. Display the Toolbox, if it is not already visible.
  2. 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.
  3. Right-click in the Toolbox, and choose Customize Toolbox from the context menu.
  4. Click the COM Components tab of the Customize Toolbox dialog box.
  5. 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:
  1. View the form in design view.
  2. 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
  3. 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:
  1. Click Start>Programs>XMetaL 4.5>Developer>Samples>Mini Journalist Customization.
  2. Click Build>Build Solution.
  3. 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:
  1. View the code for the Windows form.
  2. 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:
  1. Create a new XMetaL - Central package for the Mini Journalist customization.
  2. 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).
  3. Create the following package rules:
    1. Application Name equals XMetaL for ActiveX
    2. and SystemID equals journalist.dtd
  4. Set the groups for the package. Make sure that everybody that needs to use the Mini Journalist customization has access to the package.
  5. 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:
  1. View the code for the Windows form, if it is not already visible.
  2. Scroll to the MyXMContainerForm_Load event.
  3. 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:
  1. Open the Windows form in Design view.
  2. Drag a button from the Toolbox to the form, resizing as necessary.
  3. Change the text of the button caption to Validate, and rename the button ValidateButton.
  4. 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
  5. 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.
  6. 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:
  1. View the code for the Windows form, if it is not already visible.
  2. In the left drop-down box, select MyXMControl.
  3. 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.
  4. 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:
  1. 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?
  2. What happens if XMetaL for ActiveX or XMetaL - Central Agent (if applicable) are not installed?
  3. 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:
  1. MyXMContainerApp.exe
  2. AxInterop.XMetaLControlLib.dll
  3. Interop.XMetaLControlLib.dll
  4. 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:
  1. The .NET Framework. A redistributable installer is available on Microsoft's web site. Users of your container application must have the .NET Framework installed.
  2. 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.
  3. The third-party software requirements for XMetaL for ActiveX are:
    1. Microsoft Internet Explorer (5.0 or higher)
    2. 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.
  4. The XMetaL - Central Agent installer, if you are using XMetaL - Central to deploy document customizations.
  5. The third-party software requirements for XMetaL - Central Agent are:
    1. Microsoft (MSXML) XML Parser version 3 or higher
    2. 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