Controlling the Visio HTML Wizard AddOn via Automation

	Controlling the Visio HTML Wizard AddOn via Automation
Home Visio This page

Background

Via the SaveAs dialog, Visio 2000 includes the ability to render a page or series of pages in a plausible HTML format. This generates a series of HTML pages with the Visio drawings embedded as GIFs, and optionally in VML ("Vector Markup Language").

Numerous developers have naturally wanted to invoke this functionality from Automation so that their users don't have to operate that functionality. However, it is built as a separate wizard, and though that wizard is implemented in a DLL (VISHTMLO.dll), and contains a Type Library (VISHTML6), it is not documented by Visio/Microsoft.

Herewith, then, a stab at documentation for this wizard's Automation interface. Much of the credit for the footwork should go to Kevin Wyatt of Viswest Integrated Solutions in Australia, who in turn credits some of this to a nameless developer at Visio who long ago "leaked" some of the Visio 5 HTML version's secrets.

Digging In

The VISHTML6 library defines a number of objects that must be created and built into a structure in order to specify and then run the HTML export. Indeed, the length that you have to go to seems rather excessive considering the simplicity of the result. Doubtless there was a grand scheme behind this wizard, but it apparently didn't reach full fruition before shipping. Consequently, there's probably even more functionality that you can wring out of the mechanism, if you care to explore farther than this discussion here. But for now, on with the explanation of how to at least make the darn thing happy enough to be cooperative.

Because of the moderate complexity, I've created a diagram showing all the objects, their relationships and their properties and methods. The diagram is difficult to present on a webpage (HTML wizard not withstanding!), so I've packaged the diagram with a demo vsd, and I highly recommend downloading and printing the diagram before proceeding.

Download Demo Code and Object Diagram.

The Basic Plot

Once you have the diagram and demo code the following explanation will make some sense. The basic plan works like this:

Your code creates an ExportMgrDrawing object to oversee the whole process. You set a very few ExportMgrDrawing properties.
Your code creates an ExportData object (which will directly or indirectly hold most of the specs for the export operation), and hand it to ExportMgrDrawing.ExportData. You set some properties on ExportData.
Your code creates a Filters collection object, points it at Application, and it finds all available Filters. (Filters are the actual chunks of data or code that know how to write or read various graphics file formats -- stored in Visio\System\Filter32.). From this collection your code selects a raster filter and optionally the VML filter, and hooks them to ExportData.
Your code creates a Utilities object, and uses it to create and load a Themes collection, which in a default installation of Visio will include just the Theme named "Default". A Theme holds some properties specifying how the export will look, and in turn points to the following collections (which are also created when Themes is loaded):
- a FileTemplates collection, which refers to actual files on disk which are templates for the final HTML and scripts) and
- a Substitutions collection, which tells how to substitute codes in the templates for specific strings that make sense for the actual files generated (eg: URLs pointing between the files).
Your code chooses one of the Themes (such as Default), and hands it to ExportData.
That completes the specification, your code can now use the ExportMgrDrawing.Export method to perform the export operation.

You can see in the object diagram the kinds of properties you can set at each level, and the demo code demonstrates setting a few of those properties.

Demo Code Notes

Set Reference! If you're "trying this at home" don't forget to "set a reference" from the VBA project to the VISHTMLO library. To do this use the VBA > Tools > References dialog, and check "Visio HTML Export Support Objects". (If you have more than one version of Visio installed, you may see two or more such entries in the list. Determine the one you need by selecting each and noting the directory "Location" in the area below the list.) If you don't do this, VBA will not understand your attempts to create VISHTML objects (and the code completion function won't work either.).
To just operate the demo code, run either of the macros ThisDocument.ExportHTML_NoVML, or ThisDocument.ExportHTML_WithVML.
There is a DebugFlag which will allow you to get an idea of the contents of the Filters, Themes and ExportPages collections in the VBA Immediate window.
As traditional in demos, there's no error checking. For production purposes you will probably want to wrap the whole thing in error handling, or catch specific errors that might occur on creating files and so forth.

External Apparatus

There are several elements of the apparatus not shown in the object diagram. These include:

Registry Settings pertaining to a particular Theme. These can be studied in the sample Registry extract I've reproduced below. You can see how these entries act as sources of default settings for the Default Theme, and also point to where to find the associated template files (C:\TEMP\Default), along with how to name the output files and substitute various keywords.
The actual Template Files that belong to a particular Theme, and by the wizard as a basis for the HTML page and frame files to be produced.
Presumably, by emulating and judiciously varying the registry settings and template files, it would be possible to add more themes to suit your purposes.
Note that the Default theme's template files are actually produced by the wizard, and can be reconstructed using the Utilities.CreateDefaultTheme method

Some Notes On Properties and Methods

There are a number of properties and methods not exercised by the demo code. Here are some additional notes on a few of them:

Object	Property or Method	Discussion
Utilities	LoadThemes	This is the key method used to create and initialize the Themes structure. See sample code.
	CreateDefaultTheme("c:\Temp")	Can be used to recreate the Default theme's template files.
	DefaultThemeName	Returns "Default". May differ in other languages?
	IsThemeRegistered	Seems to always return True regardless of whether named theme exists.
	IsDefaultThemeRegistered	Seems to always return False.
	SaveDefaultTemplate( "c:\Temp\Default2\file.htm")	This appears to be a vestige left over from Visio 5 as it saves an HTML file which refers to Visio 5 and is unlike any produced by wizard in Default template files.
ExportData	VMLFilter	If you assign a filter (presumably the VML filter) to this property, then the wizard will produce VML output. If you don't want VML output, do not assign a filter to this property.
	MapType	1 = client side, 2 = server side
Filters	Parent	Set Filters.Parent = Application ...will cause the wizard to find all of the available filters and add them to the Filters collection.
Exports	(ie: the ExportPages collection)	The wizard fills this in during the ExportMgrDrawing.Export function. Your code can then use this collection to find and work on the files some more if it needs to.

Sample Registry Settings

This is simply a printout of the registry settings pertaining to the HTML wizard as installed by default.

[HKEY_CURRENT_USER\Software\Visio\Solution\Save As HTML]
  [Application]
    OutputFolder=C:\junk\visiohtmltest2
    Base Name=TwoBoxes4.htm
    Theme=Default
    VML Alternate Filter=GIF
    VML Use Alternate=01,00,00,00
    Filter=GIF
    Optimization=00,00,00,00
    Zoom=64,00,00,00
    Horizontal DPI=60,00,00,00
    Vertical DPI=60,00,00,00
    Screen Width=80,02,00,00
    Screen Height=e0,01,00,00
    JPEG Quality=64,00,00,00
    Interlace=ff,ff,00,00
    Enable Image Mapping=01,00,00,00
    Image Mapping Type=01,00,00,00
    CGI Image Map=
  [Themes]
    [Default]
      BasePath=C:\TEMP\Default
      Root=frame.htm
      VML=_vml.htm
      Raster=_raster.htm
      Doc1=lt_off.gif,,0
      Doc2=lt_over.gif,,0
      Doc3=rt_off.gif,,0
      Doc4=rt_over.gif,,0
      Doc5=_frame.htm,<!--FNAME_BASE_NOEXT-->_frame.htm
      Doc6=_nav.htm,<!--FNAME_BASE_NOEXT-->_nav.htm
      Doc7=_utils.js,<!--FNAME_BASE_NOEXT-->_utils.js
      DocCount=07,00,00,00
      [Document Substitutions]
        BODY_BGCOLOR=#FFFFFF
        BASE_TARGET=<base target="_top">
      [Page Substitutions]
        PAGE_JUMP_JS=javascript:GoToPage(<!--PAGE_JUMP_TGTIX-->-1)

Article Created: 2000-08-14 Last edit: Last edit: 00-10-30 Graham Wideman
Go to: DiagramAntics.com