Advanced
Lesson 5: Implementing an HTML Container Application for XMetaL for ActiveX
Getting
started
In this
lesson, you'll learn how to create a simple HTML container application for
XMetaL for ActiveX using Visual Studio .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). You should also be familiar with HTML and JavaScript.
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 60 minutes to complete.
Configuring
Internet Explorer for use with XMetaL for ActiveX
Internet
Explorer uses different security settings for different security zones. Certain
security zones are considered more trustworthy than others: for example, your
Local Area Network (LAN) is, by default, considered to be more trustworthy than
the Internet. Running scripts or ActiveX controls can be risky activities:
scripts or controls from a malicious host can cause problems with your
computer. Risky activities are typically restricted to more trustworthy
security zones.
To help
prevent the malicious use of scripting, XMetaL for ActiveX operates only in
domains or HTML pages specified in the Trusted Sites or
Local Intranet security zones. If you
are using the default configuration of Internet Explorer, sites located on a
LAN appear in the Local Intranet
security zone. If your site is on the Internet, you must explicitly add your
site to the Trusted Sites zone before
you can use XMetaL for ActiveX.
To add your
site to the Trusted Sites zone:
- Launch Internet
Explorer.
- Click
Tools>Internet Options The
Internet Options dialog box appears.
- Click the
Security tab.
- Click the
Trusted Sites icon.
- Click
Sites. The
Sites dialog box appears.
- Type the name or
IP address of your domain in the Add this
Web site to the zone box.
- [Optional]
Disable (uncheck) the Require server
verification (https:) for all sites in this zone check box if necessary.
- Click
Add.
- Click
OK to dismiss the
Sites dialog box.
- Click
OK to dismiss the
Internet Options dialog box.
If you are not
using the default configuration of Internet Explorer, and you need to
explicitly add your site to the Local
Intranet zone, the process is similar to the one described above, with a
few revisions.
Certain
security seetings must be enabled before you can run XMetaL for ActiveX. If you
are using the default security settings for the
Trusted Sites or
Local Intranet security zones, it is
not necessary to change them. However, if you are using custom security
settings for these zones, follow these steps to make sure the required security
settings are enabled:
- Launch Internet
Explorer.
- Click
Tools>Internet Options The
Internet Options dialog box appears.
- Click the
Security tab.
- Click the icon of
the security zone you want to modify (Trusted Sites or
Local Intranet).
- Click
Custom Level The
Security Settings dialog box appears.
- Make sure the
following settings are enabled:
- ActiveX
controls and plug-ins:
- Download
signed ActiveX control (required to download XMetaL for ActiveX as a CAB file)
- Run
ActiveX controls and plug-ins
- Script
ActiveX controls marked safe for scripting
- Scripting:
- Active
scripting
- Run
ActiveX controls and plug-ins
- Script
ActiveX controls marked safe for scripting
- Click
OK to dismiss the
Security Settings dialog box.
- Click
OK to dismiss the
Internet Options dialog box.
Other Internet
Explorer settings may affect the operation of XMetaL for ActiveX, particularly
the settings about offline web browsing and caching. You should ensure that the
browser settings meet the needs of your application.
Creating
a Visual Studio project
In this
lesson, you will create an HTML page as the container for XMetaL for ActiveX.
You will also create a Visual Studio Solution for your HTML project. To create
a Visual Studio project with a blank HTML page:
- In Visual Studio
.NET, click File>New>Project
- Select
Visual Studio Solutions as the
project type.
- Select
Blank Solution as the template.
- Type a descriptive
name for the solution, such as
MyXMContainer.
- Change the
location to save the application, if necessary.
- Click
OK. The new project appears in the
Visual Studio environment.
- Right-click the
solution in the Solution Explorer, and select
Add>Add New Item
- Click
HTML page, and type
MyXMContainerPage.htm
in the Name box.
- Click
OK.
Change the
HTML page properties to give the page descriptive title text, like
XMetaL
for ActiveX container application. You may find it easier to use the
GridLayout
page layout for the HTML page.
It's not
necessary to create a Visual Studio Solution and edit your HTML page in VS
.NET. You could edit your HTML page in any text editor or HTML editor. However,
it's helpful to use the VS .NET HTML editor because of the quick access to
XMetaL for ActiveX reference information.
Adding
XMetaL for ActiveX to an HTML page in VS.NET
You can drag
and drop the XMetaL for ActiveX control onto an HTML page in VS .NET, just like
any other 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
HTML tab. You can add the XMetaL for
ActiveX control to any tab of the toolbar, but for now let's put the control
with the rest of the HTML 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 HTML page. Once you've done that, you can resize the
control as necessary.
Take a look at
the properties for the XMetaL for ActiveX control. Change the
(id) of the XMetaL for ActiveX
control to something more descriptive, like
myXMControl.
If you are
deploying the CD installation of XMetaL for ActiveX, skip the next two
exercises and proceed to exercise called Loading an XML document into the HTML container
application.
Downloading
and running the XMetaL for ActiveX CAB file (optional)
You can use
the XMetaL for ActiveX CAB file to deploy XMetaL for ActiveX. When you are
using XMetaL for ActiveX Concurrent User License Server, you must use the CAB
file to deploy XMetaL for ActiveX.
Users do not
need to install XMetaL for ActiveX from CD if you use the CAB file, although
they will still need a CD license key if you are using node-locked licensing.
The web browser will automatically download and install XMetaL for ActiveX when
users launch your HTML container application.
Also, if you
have properly configured your HTML container application, and you upgrade the
XMetaL for ActiveX CAB file on your web server, users will automatically
download the latest version of XMetaL for ActiveX. You do not need to redeploy
your HTML container application to upgrade XMetaL for ActiveX.
Note: Do not use the CAB file when users
already have XMetaL for ActiveX installed, as this will cause problems
uninstalling XMetaL for ActiveX.
There are two
steps to using the XMetaL for ActiveX CAB file: the first is copying the XMetaL
for ActiveX CAB file to a location that will be accessible to both yourself and
your users, and the second is configuring your HTML container application to
use the CAB file.
To copy the
XMetaL for ActiveX CAB file:
- Run
setup.exe from the XMetaL for ActiveX
CD or the XMetaL for ActiveX Concurrent User License Server CD.
- Click
Copy the XMetaL for ActiveX CAB file to a
network server.
- Follow the
instructions in the wizard that appears. For the purposes of this tutorial,
save the XMetaL for ActiveX CAB file to the default location,
C:\Program Files\Blast Radius\XMetaL
4.5\ActiveXCab\
To configure
your HTML application to use the XMetaL for ActiveX CAB file:
- Open your
container application in Design view.
- Click the XMetaL
for ActiveX control.
- View the
properties of the XMetaL for ActiveX control.
- In the
Properties window, type the following
in the codebase
text box:
C:\Program
Files\Blat Radius\XMetaL
4.5\ActiveXCab\XMControl.cab#VERSION=-1,-1,-1,-1
When you set
VERSION=-1,-1,-1,-1, the web browser will automatically download and install
the latest version of the XMetaL for ActiveX CAB file available at the location
specified.
If you are
using node-locked licensing, skip the next exercise and proceed to exercise
called Loading an XML document into the HTML
container application.
Configuring
your application to use XMetaL for ActiveX Concurrent User License Server
(optional)
You can use
XMetaL for ActiveX Concurrent User License Server to provide floating licenses
for XMetaL for ActiveX to users of your container application. When the License
Server is running, end users can obtain a license for XMetaL for ActiveX
without a registration or serial number. The license is granted for the
duration of the editing session in XMetaL for ActiveX.
If you are
using the License Server, there are a few things you should do before
integrating it with your container application:
- Install the
License Server (preferably on a dedicated server).
- Start the License
Server. The License Server must be running before testing your container
application.
See the
documentation provided with the XMetaL for ActiveX Concurrent User License
Server for more information on how to perform these tasks, if necessary.
Make a note of
the network name or IP address of the License Server. If the License Server is
behind a firewall, make a note of the port it is using.
To configure
your HTML application to use the XMetaL for ActiveX Concurrent User License
Server:
- View the HTML for
your container application.
- Click
to expand the
OBJECT
tag.
- Scroll to
<PARAM
NAME="LicenseID" VALUE="">.
- Set the
VALUE
attribute to the network name or IP address of the License Server. For example,
if your License Server is not behind a firewall, use
<PARAM
NAME="LicenseID" VALUE="my-networked-computer"> or
<PARAM
NAME="LicenseID" VALUE="127.0.0.1">. If your License Server is behind
a firewall, use
<PARAM
NAME="LicenseID" VALUE="my-networked-computer:1212"> or
<PARAM
NAME="LicenseID" VALUE="127.0.0.1:1569">.
Loading
an XML document into the HTML container application
In this
exercise, you will load an XML document into XMetaL for ActiveX automatically
when your HTML container application is started.
To load an XML
document:
- View the HTML for
your container application.
- Select
window from the left-most drop-down
box
- Select
onload from the list of events that
appears. The following code appears:
<script
id="clientEventHandlersJS" language="javascript"> <!-- function
window_onload() { } //--> </script>
- 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 HTML code
for your container application, if it is not already visible.
- 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 viewing your container application in a browser.
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 XMetaL - Central 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 HTML code
for your container application, if it is not already visible.
- Add the following
markup to the body of the HTML page:
<OBJECT
CLASSID="CLSID:2ADABEEC-1AE6-4A9B-A3D6-4B23B41CBD0F" ID="myXMCentralAgent">
</OBJECT>
- Scroll to the
window_onload
event.
- Add the following
code to the beginning of the
window_onload
event, before the call to
LoadFromFile:
myXMCentralAgent.Synchronize(); myXMControl.XMCentralAgent =
myXMCentralAgent;
This code synchronizes the XMetaL - Central Agent
object with the XMetaL - Central server, and makes the XMetaL - Central Agent
available to XMetaL for ActiveX.
Save your
changes, then try viewing your container application in a browser.
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.
To validate
the active document in your container application:
- Open the HTML
page for your container application in Design view.
- Drag a button from
the Toolbox to the HTML page, resizing as necessary.
- Change the text of
the button caption to
Validate,
and rename the button
validateButton.
- Double-click the
button. The following code appears between the
<script></script>
tags:
function
validateButton_onclick() { }
- 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) window.alert("The
document is valid."); else window.alert("The document has " &
myXMControl.Document.ValidationErrorList.count & " validation
error(s).");
This code tells the user the number of validation errors, if
any.
Save your
changes, then try viewing your container application in a browser. 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.
To handle an
XMetaL for ActiveX event:
- View the HTML
code for your container application, if it is not already visible.
- Scroll past the
<OBJECT>
declaration for
myXMControl.
- Add the following
HTML below the
<OBJECT>
declaration:
<script
language="javascript"> <!-- function myXMControl::OnViewChange(prevView,
newView) { } //--> </script>
This code declares an event handler
for the
OnViewChange
event. This event has two read-only integer parameters,
prevView
(representing the view type before the view change) and
newView
(representing the view type after the view change).
- Add the following
code to this subroutine:
sqViewNormal = 0; sqViewTagsOn = 1; if (newView == sqViewNormal) alert("Now
entering Normal View."); else if (newView == sqViewTagsOn) alert("Now entering
Tags On View.");
Note that only Normal view and
Tags On view are available in XMetaL
for ActiveX.
Save your
changes, then try viewing your container application in a browser. 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 installed.
Note: If you are using floating licenses,
the License Server must be running before testing your application. If you are
using node-locked licenses, note that 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?
- What happens if
the license server (if applicable) is not available?
- What happens if
your HTML page is not in the user's Trusted
Sites or Local Intranet zone?
- What happens if
the XMetaL for ActiveX CAB file is unavailable?
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:
-
MyXMContainerPage.htm
- XMControl.cab
(if you are using the CAB file to deploy XMetaL for ActiveX).
- Third-party
installers (if required)
For an HTML
container application, you will most likely place application files on the
Internet or on an intranet. Make sure your application is accessible to all
those who need to use it, and that their browsers are configured for use with
the XMetaL for ActiveX control.
If you using
the CD installation of XMetaL for ActiveX, you need to make the XMetaL for
ActiveX installer available to end users of your container application. Both a
regular installer and a silent installer are available on the XMetaL for
ActiveX CD.
If you are
using the XMetaL - Central Agent to deploy document customizations, users must
also have the XMetaL - Central Agent installed. An installer is available on
the XMetaL - Central CD.
XMetaL for
ActiveX works with Microsoft Internet Explorer 5.0 or higher. See
Microsoft's
web site for information about downloading Internet Explorer. If you are
using a HTML container application, you may want to implement a script that
checks the browser version before attempting to load XMetaL for ActiveX.
MSXML must be
installed before installing XMetaL for ActiveX. You can redistribute MSXML in
an installer or in a CAB file. See
Microsoft's
web site for information on redistributing MSXML.
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 HTML container application on the sample that comes with XMetaL
Developer. Click Start>Programs>XMetaL
4.5>Developer>Samples>HTML container application to view the
sample.
Last modified: Friday, May 21, 2004 3:51:46 PM