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:
  1. Launch Internet Explorer.
  2. Click Tools>Internet Options The Internet Options dialog box appears.
  3. Click the Security tab.
  4. Click the Trusted Sites icon.
  5. Click Sites. The Sites dialog box appears.
  6. Type the name or IP address of your domain in the Add this Web site to the zone box.
  7. [Optional] Disable (uncheck) the Require server verification (https:) for all sites in this zone check box if necessary.
  8. Click Add.
  9. Click OK to dismiss the Sites dialog box.
  10. 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:
  1. Launch Internet Explorer.
  2. Click Tools>Internet Options The Internet Options dialog box appears.
  3. Click the Security tab.
  4. Click the icon of the security zone you want to modify (Trusted Sites or Local Intranet).
  5. Click Custom Level The Security Settings dialog box appears.
  6. Make sure the following settings are enabled:
    1. ActiveX controls and plug-ins:
      1. Download signed ActiveX control (required to download XMetaL for ActiveX as a CAB file)
      2. Run ActiveX controls and plug-ins
      3. Script ActiveX controls marked safe for scripting
    2. Scripting:
      1. Active scripting
      2. Run ActiveX controls and plug-ins
      3. Script ActiveX controls marked safe for scripting
  7. Click OK to dismiss the Security Settings dialog box.
  8. 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:
  1. In Visual Studio .NET, click File>New>Project
  2. Select Visual Studio Solutions as the project type.
  3. Select Blank Solution as the template.
  4. Type a descriptive name for the solution, such as MyXMContainer.
  5. Change the location to save the application, if necessary.
  6. Click OK. The new project appears in the Visual Studio environment.
  7. Right-click the solution in the Solution Explorer, and select Add>Add New Item
  8. Click HTML page, and type MyXMContainerPage.htm in the Name box.
  9. 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:
  1. Display the Toolbox, if it is not already visible.
  2. 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.
  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 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:
  1. Run setup.exe from the XMetaL for ActiveX CD or the XMetaL for ActiveX Concurrent User License Server CD.
  2. Click Copy the XMetaL for ActiveX CAB file to a network server.
  3. 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:
  1. Open your container application in Design view.
  2. Click the XMetaL for ActiveX control.
  3. View the properties of the XMetaL for ActiveX control.
  4. 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:
  1. Install the License Server (preferably on a dedicated server).
  2. 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:
  1. View the HTML for your container application.
  2. Click to expand the OBJECT tag.
  3. Scroll to <PARAM NAME="LicenseID" VALUE="">.
  4. 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:
  1. View the HTML for your container application.
  2. Select window from the left-most drop-down box
  3. Select onload from the list of events that appears. The following code appears:
    <script id="clientEventHandlersJS" language="javascript"> <!-- function window_onload() { } //--> </script>
  4. 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 HTML code for your container application, if it is not already visible.
  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 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:
  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 HTML code for your container application, if it is not already visible.
  2. Add the following markup to the body of the HTML page:
    <OBJECT CLASSID="CLSID:2ADABEEC-1AE6-4A9B-A3D6-4B23B41CBD0F" ID="myXMCentralAgent"> </OBJECT>
  3. Scroll to the window_onload event.
  4. 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:
  1. Open the HTML page for your container application in Design view.
  2. Drag a button from the Toolbox to the HTML page, 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 appears between the <script></script> tags:
    function validateButton_onclick() { }
  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) 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:
  1. View the HTML code for your container application, if it is not already visible.
  2. Scroll past the <OBJECT> declaration for myXMControl.
  3. 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).
  4. 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:
  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?
  4. What happens if the license server (if applicable) is not available?
  5. What happens if your HTML page is not in the user's Trusted Sites or Local Intranet zone?
  6. 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:
  1. MyXMContainerPage.htm
  2. XMControl.cab (if you are using the CAB file to deploy XMetaL for ActiveX).
  3. 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