Microsoft® FrontPage™ Developer’s Kit

Version 1.1

Copyright © 1995, 1996 Microsoft Corporation
All rights reserved.

Your use of this Software Developer Kit is subject to the terms and conditions of an End User License Agreement.  See the file “license.doc” (or “license.rtf”) that accompanies this file.

Microsoft Product Support Services does not support this software.  If you have limited programming experience, you may want to consult one of the Microsoft Solution Providers.  Solution Providers offer a wide range of fee-based services, including creating custom software for use with Microsoft products.  For more information about Microsoft Solution Providers, you can call Microsoft Customer Information Service at (800) 426-9400.

Although we cannot promise a response, we welcome your comments on this kit.  Please e-mail comments to "fpsdk@microsoft.com".

Microsoft FrontPage™ 1.1 can be extended in a variety of ways:

1.	End-users or developers can create templates for webs or web pages (including framesets).  The FrontPage 1.1 editor allows end-users to save a single page as a template (choose “Save As” from the File menu, and click on “As Template”).  In addition, a developer can create an entire web as a template using this kit.
2.	Developers can create wizards for webs or web pages. Wizards and other utility programs can communicate with the Windows version of the FrontPage client software using Object Linking and Embedding (OLE) Automation. 
3.	FrontPage webs are compatible with industry-standard CGI scripts. Developers can create custom CGI programs and add them to webs on servers with the FrontPage Server Extensions installed.

The intended audience for this document is anyone interested in creating wizards or templates to work with FrontPage 1.1. The reader should be familiar with FrontPage and its main components. The section on Templates does not require any special knowledge, but those on Wizards and OLE Automation assume some entry-level programming knowledge; examples are given in Microsoft Visual Basic and Visual C++.

 
SUMMARY OF CHANGES	
1. TEMPLATES	
The Template Directory	
The INF File	
The Info Section	
The FileList Section	
The MetaInfo Section	
The TaskList Section	
Image Files and Disk Layout	
Home Page Management	
Creating Page Templates	
Creating Web Templates	
Frameset Templates	
2. WIZARDS	
INF File	
Web Wizard vs. Page Wizard	
Command-line Arguments	
Input Parameters	
Output Parameters	
Sample Parameter File	
User Interface	
INI File Settings	
Naming Conventions	
FrontPage Interactions	
3. OLE AUTOMATION OVERVIEW	
The FrontPage Explorer Interface	
The FrontPage Editor Interface	
The FrontPage To Do List Interface	
Programming Considerations	
Version Information	
Programming Examples	
4. FRONTPAGE EXPLORER AUTOMATION	
vtiCreateWeb	
vtiRefreshWebFromServer	
vtiPutDocument	
vtiPutWebMetaInfo	
vtiSetWebRecalcDependencies	
vtiGetWebPageMetaInfo	
vtiBringToTop	
vtiGetWebTitle	
vtiGetWebURL	
vtiPromptOpenWeb	
vtiRemoveWeb	
vtiIsPageInWeb	
vtiGetWebMetaInfo	
vtiGetPageList	
vtiPutDocuments	
vtiCancelRequests	
vtiOpenWeb	
vtiEditWebPage	
vtiPutWebPageMetaInfo	
vtiGetDocToFile	
5. FRONTPAGE EDITOR AUTOMATION	
vtiOpenWebPage	
vtiQueryWebPage	
vtiBringToTop	
vtiNewWebPage	
6. FRONTPAGE TO DO LIST AUTOMATION	
vtiShow	
vtiHide	
vtiAddTask	
vtiGetActiveCount	
vtiCompletedTaskByUrl	
vtiWorkedOnTaskByUrl	
vtiAddTaskAskUser	
EXAMPLES	
Documentation	
Templates	
Wizards	
Utility Programs	
CGI Scripts	

SUMMARY OF CHANGES

The major changes to the FrontPage Developer’s Kit for version 1.1 include:

•	The OLE Program Identifiers (ProgIDs) were changed. The new names are FrontPage.Explorer.1.1, FrontPage.Editor.1.1, and FrontPage.ToDoList.1.1. The version-independent names FrontPage.Explorer, FrontPage.Editor, and FrontPage.ToDoList are also registered. The old names were Vermeer.Webber, Vermeer.WPE, and Vermeer.ToDo.

•	All methods that included a proxy argument have been changed. There are no longer any proxy arguments, since this is handled in a global manner by the FrontPage Explorer. The affected methods are in the FrontPage Explorer interface. See the descriptions for vtiCreateWeb and vtiOpenWeb.

•	Command-line processing has changed. In version 1.0, wizards were passed a series of arguments using flagged parameters, such as "-ddirname". In 1.1, all wizards take a single argument: the path to a temporary INI-format file containing all such parameters in name=value format. See the Wizards section of this document for more details on command-line processing.

•	Two new methods were added to the FrontPage Explorer interface. See the descriptions for vtiGetDocToFile and vtiPutWebPageMetaInfo.

•	The delimiter for meta-info values in the FrontPage Explorer’s vtiPutWebMetaInfo method changed from '|' (vertical bar) to newline ('\n'). 

•	The format of the link information stored in the vtiLinkInfo page meta-info variable has changed. See the description for the method vtiGetWebPageMetaInfo in the FrontPage Explorer.

•	A new built-in web meta-info variable, vti_FeatureList, was made available via the FrontPage Explorer’s vtiGetWebMetaInfo method. See the description for details.

•	Wizards can now set the editor for a particular document. Use the FrontPage Explorer’s vtiPutWebPageMetaInfo method to set the page’s vti_Editor attribute to the name of a configured editor. The next time the user open that document from the FrontPage Explorer, the selected editor will be launched on the downloaded file.

•	Some FrontPage Explorer methods can now refer to Internet web documents. Both vtiEditWebPage and vtiGetDocToFile will accept an absolute URL prefixed by “http://” and fetch the referenced document from the Internet.

1. TEMPLATES

A template is a special directory on a user’s local disk that contains prototype web content (web pages, text files, images, etc.). The files in the template directory can be uploaded to a web server and then edited and managed using FrontPage. There are three kinds of templates in FrontPage 1.1: page templates, web templates, and frameset templates. A page template usually creates a single page, while a web template usually creates several interconnected pages. Page and web templates are placed in the directories called “pages” and “webs” under the FrontPage installation directory. Frameset templates are handled differently from web and page templates, and are only used by the FrontPage Frames Wizard.

NOTE: Starting in Version 1.1 of FrontPage, page templates can be easily created by end-users.  In FrontPage Editor, choose the “Save As” item on the File menu, and then click on the “As Template” button.  Templates for whole webs, however, must still be created using the information in this document.
The Template Directory

A page or web template directory must be called *.tem, such as sample.tem. In order to be recognized by FrontPage, this directory must be placed in either the FrontPage webs or pages directory, depending on what kind of content it holds. These are directly underneath the FrontPage root directory, which can be discovered from the frontpg.ini file located in the user’s Windows directory:

[FrontPage 1.1]
FrontPageRoot=C:\Microsoft FrontPage

CHANGE: In Version 1.0 of FrontPage, the INI file was called vermeer.ini, and section was called “FrontPage”.
The INF File

It is important to have a meaningful title and description for a page or web template, since a list of wizards and templates could be quite large. This information is kept in a special file, called *.inf, inside the template directory. The base name of this file must match the base name of the template directory. For example, you would create sample.inf inside the sample.tem directory.

The INF file uses Microsoft’s INI file format. The INF file can have several named sections, each surrounded by angle brackets like this: [Section Name]. Underneath each section are name-value pairs, one on each line. An attribute name (also called a key) and its value are separated by an equal sign (=).
The Info Section

FrontPage reads the [info] section of the INF file when it presents a list of wizards and templates to a user. If the INF file is not found, or if the [info] section does not exist, FrontPage displays the base name of the template directory (such as sample). If the INF file is found, the dialog boxes display the values of the title and description keys found in the [info] section. 

Here’s what an INF file for the sample template might look like:

[info]
title=My Sample Page
description=Create a page from a template.

The INF file can contain three optional sections that are used by the FrontPage Explorer when loading templates: [FileList], [MetaInfo], and [TaskList]. The FrontPage Editor does not use these sections when reading page templates; they are only used by the FrontPage Explorer when it uploads a web template to a web server.
The FileList Section

The [FileList] section allows explicit mappings between the file names inside the template directory and the web-relative URLs where they will be uploaded. It also allows you to upload files from subdirectories of the web template. Each line has  the form filename=URL.

When you do not provide a [FileList] section, the FrontPage Explorer scans the template directory and uploads all available files. However, it does not descend into subdirectories. All file names are converted to lowercase, and the URLs are set to be the same as the file names. Also, all file names with the image extensions .gif, .jpg, and .jpeg are uploaded to the images directory in the web. 

When you provide a [FileList], only the files mentioned in the section are uploaded. The URLs have the exact case as specified. 

When you specify only the file name, the URL will be the same as the file name. Entries must still include the equal sign, like this:

	[FileList]
	fileone.htm=
	filetwo.htm=

You may refer to files in template subdirectories when creating a [FileList] section, however, only valid web URL subdirectories can be used. The valid web subdirectories are images, _private, and cgi-bin. You must use forward-slashes when specifying these directories in URLs. These web directories, and a few others, are created by the FrontPage Server Extensions when you make a new web using the FrontPage Explorer.

The MetaInfo Section

A web can have some persistent meta-info variables, which are a set of name-value pairs stored inside each web. These variables can be used to store configuration information about the web, or when used in conjunction with the Substitution Bot, replace instances of certain strings in all your web pages. You may define a number of these variables in the optional [MetaInfo] section. Keys are case-insensitive. Microsoft reserves names beginning with vti_ for web administration. Each line has the form name=value.

A sample [MetaInfo] section might look like this:

	[MetaInfo]
	CompanyName=Microsoft
	CompanyAddress=One Microsoft Way, Redmond Washington
The TaskList Section

You can upload some tasks for the FrontPage To Do List using items in the optional [TaskList] section. A task consists of six attributes:

1.	TaskName
2.	Priority (1 to 3)
3.	CreatedBy
4.	URL
5.	Cookie
6.	Comment

These attributes are encoded in each line of the [TaskInfo] section as follows:

	TaskNum=TaskName|Priority|CreatedBy|URL|Cookie|Comment

TaskNum is a unique key, such as ‘t01’, ‘t02’, etc. Task attributes are separated by vertical bar characters (‘|’).

Task Attribute	Description	
TaskName	a short phrase, typically 3 or 4 words, telling the user what to do	
Priority	an integer, where 1=High, 2=Medium, and 3=Low	
CreatedBy	the name of the template creating the task	
URL	the page or image the task refers to, such as news.htm or logo.gif	
Cookie	an additional identifier for a point within the target URL; currently limited to HTML bookmarks, specified as  #bookmark	
Comment	a short sentence describing in detail what needs to be done; cannot contain any new-line characters	

Image Files and Disk Layout

Page templates typically use a flat structure, with all images and HTML files stored in the same directory. The FrontPage Editor rewrites the links to images in the page whenever it is saved to a web or a disk file.

Web templates typically mirror the structure of a FrontPage web, with a subdirectory for images. This is so that references to images in the template web have the same relative path in the template pages as when they are uploaded to the web.

If a web template requires images, create a sub-directory inside the template directory called images, and place all GIF and JPEG files inside it. Make sure that all references to images in the template pages use the path prefix for images (such as images/logo.gif). You must also create a [FileList] section in the INF file, as described above, referencing the image files inside the template’s images subdirectory and target URLs inside the web’s images directory.

CHANGE: In version 1.0, all page templates with images were required to have an images directory in order to support the New Page menu option from the FrontPage Explorer. This option was removed in version 1.1.
Home Page Management

If you include a home page in your web template, the FrontPage Explorer will perform some special handling for the URL index.htm. A home page is the default page returned by the web server when a URL that resolves to a web directory is requested, such as “http://www.some-company.com” or “http://www.some-company.com/”. A home page is sometimes called a welcome page, such as with the CERN server, or an index page, such as with the NCSA server. The file name that is used for the home page depends on the server and its configuration. The FrontPage Explorer’s template loader will determine the correct index name for your web, and rename any URL called index.htm with the correct index name. On a CERN server, this might resolve to the name Welcome.html. 

If you want to disable this behavior, add an entry to the [info] section of the INF file that looks like this:

	NoIndexRenaming=1

If you use the index renaming feature, you should change all links in your template web pages that refer to index.htm (or some other home page URL) to refer to the special link ./ (dot-slash).  This forces the server to locate the correct home page and redirect the browser to it.

Creating Page Templates

CHANGE: In version 1.0, page templates had to be created manually. In version 1.1, the FrontPage Editor can save a page as a template, using the Save As menu option.
Creating Web Templates

NOTE:  A Visual Basic program called Web Template Maker that automates the process of creating a web template (as described below) is included in the FrontPage SDK.

The following is a manual procedure to create a web template called Sample:

1.	Create a web using the FrontPage Explorer on your local web server, or copy a web from a remote server to a local web server.
2.	Using the File Manager, locate the directory containing the web’s content. By default, this is a directory under “C:\FrontPage Webs\Content”. For example, if your web is called Test, then the web content is located in “C:\FrontPage Webs\Content\Test”.
3.	Using the File Manager, create a directory called Sample.tem under the FrontPage webs directory.
4.	Copy the web’s images directory into Sample.tem. For example, if the web is called Test, copy “C:\FrontPage Webs\Content\Test\images”into Sample.tem. If you are using File Manager, be sure to hold down the CTRL key when doing the copy, or else the directory will be moved -- not copied.

Next, you need to copy the web pages into the new template. Pages with WebBots (bots) are saved in two versions, one with the bots in source form as a list of name-value pairs and one with the Bots expanded into HTML. When creating a web template, the source version of a page with bots takes precedence over its expanded version. The source version is like the source code for the page, which is “compiled” into the expanded version when it is interpreted by the FrontPage Server Extensions. The expanded version of a page is what a browser fetches and displays. The expanded version is stored in the main web directory, and the source is stored in the _vti_shm subdirectory of the main web directory.

Here’s a procedure for copying pages into the new web template Sample.tem:

1.	Copy the static pages in the main web directory (“C:\FrontPage Webs\Content\Test”) into Sample.tem. Do not copy access control files, such as #haccess.ctl.
2.	Copy the web’s bot pages (“C:\FrontPage Webs\Content\Test\_vti_shm”) into Sample.tem. Do not copy access control files, such as #haccess.ctl. If File Manager asks if it’s okay to overwrite some files, choose the Yes to All button.
3.	Using NotePad, create a “.INF” file in the Sample.tem directory called Sample.inf.
4.	Create an [info] section in Sample.inf with appropriate title and description keys. For example, set the title to “Sample Web” and the description to “Create a sample web from a template.”. Add any tasks or web meta info variables in their appropriate sections.
5.	If you have any content in web subdirectories (such as _private), repeat the above steps, copying the static and then the dynamic versions of the pages to the same  subdirectory (_private) in the web template.
6.	If you have any scripts or programs in your web’s cgi-bin directory, create a cgi-bin directory inside your template dir, and copy the programs into it (cgi-bin). 

If your web includes any content in subdirectories (images, cgi-bin, or _private), you will need to create a [FileList] section in your .INF file as described above in order to make sure those files get uploaded properly by the FrontPage Explorer.\
Frameset Templates

FrontPage 1.1 includes a Frames Wizard for creating and editing HTML frameset pages. A frameset page divides up a page into independent scrollable regions that can each contain a separate web page. Authors can cause documents to be loaded into individual frames regions by using a special “TARGET” attribute that can be attached to most kinds of links.

The Frames Wizard offers an option to create an entire frameset, including its component  pages, from one of several templates. These templates are stored in the Frames Wizard directory, which is underneath the FrontPage “pages” directory.

Frameset templates are stored differently from the web and page template structure described above. Each frameset template is kept in its own file, with the extension “.frm”. The .frm files are kept in INI format so they are easily read by the Frames Wizard. Each .frm file has the following structure:

[info]
title=name of frameset as it will appear in the wizard
description=long description of the purpose of the wizard
noframesURL=ignored; alternate page is assigned by wizard
layout=specification of frameset geometry using compact notation

[frame name 1...N]
title=name of frame as it will appear in the page title
description=long description of what the frame should contain
URL=ignored; page URL for frame is assigned dynamically by wizard
marginWidth=width of margin; default is 1
marginHeight=height of margin; default is 1
scrolling=how scrollbars are displayed; default is ‘auto’
noresize=turns off scrolling; default is ‘False’
target=name of default target frame for this page

The first section, [info], describes the main frameset page. Subsequent sections each describe a component frame page. The section names must match the frame names, which are derived from the frameset layout specification in the [info] section.

The following is a sample frameset layout specification:

layout=[R(15%,85%)F("banner",[C(35%,65%)F("contents","main")])]

Framesets can be recursive (frameset within framesets). Each frameset, including the topmost frameset, is surrounded by square brackets [like these]. Inside the frameset is a row and/or column specification followed by a list of frames. A row specification is an “R” followed by a comma-separated list of row sizes in parentheses (like these), where each entry is expressed as a percentage of the total available height. The column specification is the same format as the row specification, but with an initial “C”. The frame list is an “F” followed by a comma-separated list, where each item is either a frame name (inside double quotes) or a full frameset specification (inside square brackets).

The sample layout string above can be decoded as follows. The frameset consists of two rows, a short one at 15% of the window height and a long one at 85% of the height. A frame called “banner” is assigned to the short row. The long row contains another frameset, this one divided into two columns of 1/3 and 2/3 of the window width. This interior frameset is composed of two frames, the first called “contents” (which is assigned to the leftmost third) and the second called “main” (which is assigned to the rightmost two-thirds).

The Frames Wizard reads the frameset information for any files in its directory with the extension .frm. It uses the layout string to display a preview graphic with the frame names alongside the frameset’s title and description strings. When a frameset template is chosen, the wizard reads the information for each named frame by looking up a section with the same name in the .frm file. For this reason the section names must match the frame names.

Finally, the wizard generates the frameset page and its component pages and loads them into the current web or the FrontPage Editor as appropriate. The wizard will place an Annotation Bot on each page describing its purpose, the frameset it belongs to, what the default target is (if any), and how the page can be edited. 

One of the most useful features of the wizard is that it sets the “Base Target” (also called the default target) for any frame documents that have associated targets in the .frm file. If a base target is set, any links on that page will cause the named frame (the “target”) to be loaded with the referenced pages. This behavior can be overridden by editing the frame page and either setting a different target attribute on particular links or changing the default target frame in the FrontPage Editor’s Page Properties dialog.

2. WIZARDS

A wizard simplifies the process of creating common types of webs and web pages. A wizard is an independent executable program that typically collects input from a user in a series of dialog boxes, then places OLE automation calls to drive FrontPage by “remote control” to create the new webs or web pages. A wizard can be written in any programming language that is capable of calling OLE automation functions. 

Just like a template, a wizard is contained in a special directory on a user’s local disk. 
A wizard directory must be called *.wiz, such as sample.wiz. In order to be recognized by FrontPage, this directory must be placed in either the FrontPage webs or pages directory, depending on what kind of content it holds. The path to these directories can be determined from settings in the frontpg.ini file installed in a user’s Windows directory:

[Ports]
Port 80=
[FrontPage 1.1]
FrontPageRoot=C:\Microsoft FrontPage
PWSRoot=C:\FrontPage Webs
FrontPageLangID=0x0409
FrontPageLexicon=C:\Microsoft FrontPage\bin\mssp2_en.lex
FrontPageSpellEngine=C:\Microsoft FrontPage\bin\mssp232.dll
CheckedHostName=arbus
[Port 80]
servertype=frontpage
serverconfig=C:\FrontPage Webs\Server\conf\httpd.cnf
authoring=enabled
frontpageroot=C:\Microsoft FrontPage

CHANGE: In version 1.0, the INI file was called vermeer.ini. The section was called “FrontPage”, and it contained keys for FrontPageRoot, FrontPageBin, WebWizardsDir, and PageWizardsDir. As of version 1.1, the only required key is FrontPageRoot. If you set one of these keys, the change will take effect the next time the FrontPage Explorer or FrontPage Editor are run.

A wizard can get determine the FrontPageRoot setting in the FrontPage 1.1 section, and then append the directory “webs” for web wizards and templates, or “pages” for page wizards and templates. By default, the base name of the wizard executable program should match the base name of the wizard directory, for example, sample.wiz\sample.exe.
INF File

Wizards also use an INF file. The [info] section contains title and description keys. It can also contain a key called exename giving the name of the wizard program, if it does not match the name of the wizard directory as described above. If a page wizard can function as an editor in addition to a generator, the INF file should contain the line “editor=1”.

Web Wizard vs. Page Wizard

In general, a page wizard creates a single page, while a web wizard creates several interconnected pages. However, this distinction is not enforced. A wizard is not restricted to certain actions because of its type. However, page wizards are always run from the FrontPage Editor, while web wizards are always run from the FrontPage Explorer. 

A web wizard typically presents a series of dialog pages to collect user input, and then generates one or more HTML pages in the FrontPage temp directory (typically “C:\Microsoft FrontPage\temp”) based on the selected options. These pages are then uploaded to the current web, along with any static resources, such as images that are kept in the wizard directory. If a user selects the option to create a new web rather than adding to the current one, then the FrontPage Explorer will create a new web before starting the wizard.

A page wizard typically presents a series of dialog pages to collect user input, then generates a single HTML page in the FrontPage temp directory based on the selected options. The page is then loaded into the FrontPage Editor.
Command-line Arguments

CHANGE: The handling of command-line arguments in version 1.1 is significantly different from version 1.0. Previously, wizards were passed a series of flagged options on the command line.

All wizards are launched with a single argument: the path to a temporary file in INI format containing name-value pairs. If a wizard is run without any arguments, because the user started it from the Windows File Manager or Windows Explorer, it should behave in a reasonable default manner. Typically a page wizard should load a page into the FrontPage Editor, and a web wizard should load pages into the current web.

The format of the parameter file is as follows: 

     [Input]
     arg1=value1
     arg2=value2
     [Environment]
     var1=value1
     var2=value2
     [Output]

The Input section contains all required and optional wizard parameters. The Environment section contains a snapshot of the parent's environment variables. The Output section is initially empty; this is where the wizard can write variables that get sent back to the calling process under certain circumstances.
Input Parameters

All wizards receive the following built-in arguments when run: 

     Dir=absolute path to wizard directory
     Inf=absolute path to wizard’s INF file
     Blocking=0 or 1 (1 if caller is blocked) 
     Editing=0 or 1 (1 if wizard is being invoked as an editor) 

A page wizard's INF file should contain the key/value "editor=1" if it can be launched as an editor (like the Frames wizard in version 1.1); otherwise the Editing key will always be set to 0.

When a wizard is run with Blocking=0 (the typical non-blocking case), it should delete the parameter file mentioned on the command line before exiting, to avoid cluttering up the temporary directory. When a wizard is run with Blocking=1, the launching program is expecting to pick up some output parameters from the wizard; in this case, the launching program will take care of deleting the parameter file when the wizard exits.

A few additional parameters have special meaning to a page wizard: 

     Destination=editor | web | disk
     PageURL=web-relative URL where page should be saved
     PageTitle=title for new web page 
     PageFile=path to file being edited (only set if Editing=1) 

Each page wizard has a notion of its default destination. This is usually the FrontPage Editor; but if a wizard generates content that cannot be edited by the FrontPage Editor, the wizard should load it to the current web instead. 

If Destination=editor, the generated file should be loaded directly into the FrontPage Editor via OLE automation. If Destination=web, the generated file should be loaded directly to the current web via OLE automation. If Destination=disk, the wizard should generate its output into temp files and return a list of filename/URL pairs via the Output section (see below).

PageURL is the web-relative path to the page being created (such as "index.htm"). PageTitle is the title of the page being created (such as "My Home Page"). PageFile is an absolute path to the file being edited, which has typically just been downloaded by the Explorer.

For backward compatibilty, the following arguments are still passed to wizards by the FrontPage Explorer when it runs a web wizard: WebName, ServerName, Proxy, User.
Output Parameters

If Blocking=1, then page wizards should return some values via the parameter file’s Output section.

The ExitStatus key should be set to either "error", "cancel", or "ok.” If ExitStatus is not present, the launching program will assume that an error occurred in the wizard.

If Destination=disk, the wizard should write a FileCount key and a list of keys from File1 to FileN and Url1. The values of these keys should be set to the absolute paths and target URLs of each file generated by the wizard.

For example, a wizard that generated two files might create an Output section like this:

     [Output]
     ExitStatus=ok
     FileCount=2
     File1=c:\temp\wiz01.tmp
     Url1=index.htm
     File2=c:\temp\wiz02.tmp
     Url2 = test.htm

It is assumed that File1 will be the main HTML file created by a page wizard.
Sample Parameter File

Here's an example of a parameter file that a wizard might receive:

     [Input]
     PageURL=test.htm
     PageTitle=Test Page
     Dir=E:\FrontPage\pages\vtiform.wiz
     Inf=E:\FrontPage\pages\vtiform.wiz\vtiform.inf
     Blocking=0
     Editing=0
     [Environment]
     COMPUTERNAME=ARBUS
     ComSpec=E:\WINNT35\system32\cmd.exe
     HOMEDRIVE=E:
     HOMEPATH=\users\default
     MSINPUT=E:\MSINPUT
     OS=Windows_NT
     Os2LibPath=E:\WINNT35\system32\os2\dll;
     Path=E:\WINNT35\system32;E:\WINNT35
     PROCESSOR_ARCHITECTURE=x86
     PROCESSOR_IDENTIFIER=x86 Family 5 Model 2 Stepping 11, GenuineIntel
     PROCESSOR_LEVEL=5
     PROCESSOR_REVISION=020b
     SystemRoot=E:\WINNT35
     SystemDrive=E:
     temp=E:\temp
     tmp=E:\temp
     USERDOMAIN=EMINENT
     USERNAME=rsasnett
     windir=E:\WINNT35
     [Output]
User Interface

A wizard should look like a dialog box but should have the following buttons to step through the dialog pages: Back, Next/Finish, and Cancel. Most wizards should be self-explanatory, but some may require a Help button. These buttons should always be visible and accessible at the bottom of the wizard’s dialog box. If necessary, an image or graphical output area appears to the left of the dialog pages but above the main navigation buttons.
INI File Settings

Wizards should store any settings they wish to preserve in the data subdirectory of the FrontPage installation directory. The name of each INI file should be the same as the base name of the wizard executable program but with an .INI extension. The INI file is separated from the program so that the wizard directory can be mounted on a read-only disk drive, such as in a local-area network or with a CD-ROM. This is also why all wizards place their generated files into the FrontPage temp directory.

The location of the FrontPage webs and pages directories can be modified using the keys WebWizardsDir and PageWizardsDir in the “FrontPage 1.1” section of the file frontpg.ini in the Windows directory.
Naming Conventions

Each wizard must have a unique name within the FrontPage webs or FrontPage pages directory, depending on whether it is a web wizard or page wizard. The name of the wizard directory must have the extension “.wiz” in order to be recognized as a wizard.
FrontPage Interactions

Wizards communicate with the FrontPage components using the OLE APIs described in the OLE Automation section.

3. OLE AUTOMATION OVERVIEW

IMPORTANT:  The OLE automation interfaces described in this section apply only to FrontPage 1.1. These interfaces have changed since the FrontPage 1.0 release, and will continue to evolve further. As a consequence, any OLE automation code you write should localize calls to these methods using macros or function wrappers in order to minimize editing changes later on.

There are three main components in FrontPage that can be controlled externally through OLE automation. Each component has a separate OLE identifier in the Windows Registry on a user’s machine. The identifiers correspond to the FrontPage Explorer (FrontPage.Explorer.1.1), the FrontPage Editor (FrontPage.Editor.1.1), and the FrontPage To Do List (FrontPage.ToDoList.1.1). Each component is also accessible with a generic identifier that resolves to the current release of FrontPage; these names are FrontPage.Explorer, FrontPage.Editor, and FrontPage.ToDoList.

CHANGE: In version 1.0, the registered OLE names were Vermeer.Webber, Vermeer.WPE, and Vermeer.ToDo.
The FrontPage Explorer Interface

The FrontPage Explorer is the main interface for OLE automation. It operates on web-level objects. A web is defined as a set of documents underneath a given URL directory that are made available by a web server running the FrontPage Server Extensions.

For example, http://www.mycompany.com/myweb is a web of interconnected documents all residing under the directory myweb on the server www.mycompany.com. There is also the Root Web on this server (accessed via the URL http://www.mycompany.com/), and several other top-level webs at /web1, /web2, and so on. FrontPage  can administer and author in the Root Web and its immediate descendants.

A web has security attributes that define permissions for administrators, authors, and users. An administrator can create and delete webs, and set permissions for authors. An author can create, edit, and delete documents inside a web, and set permissions for users. A user can view the web using any browser program.

A web can contain persistent meta-info variables. These are stored as name-value pairs inside a configuation file within the web. The meaning of these variables is entirely application-specific, except for read-only variables defined by Microsoft that begin with the characters vti_.

Web pages have similar persistent meta-info attributes. Typically these are used for administrative purposes (such as when was a page was created or last changed). Again, Microsoft reserves variables whose names start with vti_.

The current FrontPage Explorer OLE interface can create a web, delete a web, move documents from a local file system to a web server and vice versa, remove documents from a web, set and get web meta-info variables, get page meta-info variables, retrieve a list of files or images in the current web, launch the To Do List, and get the URL and title of the current web.
The FrontPage Editor Interface

The FrontPage Editor is a WYSIWYG web page editor for HTML documents. Web pages  are stored in .htm or .html files on the web server. The FrontPage Editor can open, edit, and save HTML files in the current web being viewed by the FrontPage Explorer, or in the local file system. 

The current FrontPage Editor OLE interface is primarily for internal use by the other FrontPage components. Operations include creating a new empty page, opening a page from the current web or local file system, and determining if a named page is currently being edited. Operations on page contents have not yet been exposed to OLE automation.
The FrontPage To Do List Interface

The FrontPage To Do List is a flexible grid-like object that manages and displays a list of tasks to be performed on the web currently opened by the FrontPage Explorer. Tasks are removed from the To Do List as they are completed. Each task has a set of attributes that include name, priority, description, creator, and associated web document. Tasks can be added to the To Do List either by typing them in or as a result of running other programs that manipulate web pages. For example, a wizard or template typically places tasks on the To Do List for each web page it creates that requires some further customization.

The current FrontPage To Do List OLE interface can be used to add new tasks and to hide or display the To Do List interface.
Programming Considerations

Before invoking an OLE method, you must establish a connection to the automation server’s exported object interfaces (for more information on the IDispatch object interface, see Inside OLE, Second Edition, by Kraig Brockschmidt). You call the server’s OLE methods by invoking the same methods on an object on the client side of the OLE connection. When you’re finished calling methods, you detach your local object from its connection with the OLE automation server. Most applications want to minimize the amount of time they maintain an open OLE connection, because a user can close the FrontPage application or change its state in ways that will cause the automation operation to fail. Typically you will open and close the OLE connection inside a single function.
Version Information

To connect to this particular version of FrontPage, use the fully-specified identifiers “FrontPage.Explorer.1.1”, “FrontPage.Editor.1.1”, and “FrontPage.ToDoList.1.1”. You may also use the generic identifiers “FrontPage.Explorer”, “FrontPage.Editor”, and “FrontPage.ToDoList”, but you may get an incompatible interface after a future release of FrontPage.

Important: These interfaces have changed since the release of FrontPage 1.0, and will change again in future releases. As a consequence, any OLE automation code you write should localize calls to these methods using macros or function wrappers in order to minimize editing changes later on. 
Programming Examples

The following example demonstrates OLE automation from Visual C++:

#include "webber.h"

void OnSomeEvent()
{
IWebber explorer;
COleException error;

	if(!explorer.CreateDispatch("FrontPage.Explorer.1.1",&error))
	{
		AfxMessageBox("Error connecting to FrontPage Explorer.");
		return;
	}
	explorer.vtiRefreshWebFromServer();
	explorer.ReleaseDispatch();
}

The following is the same example as above, but using Visual Basic:

Function btnSomeEvent_Click()
{
Dim explorer as Object

	Set explorer = CreateObject("FrontPage.Explorer.1.1")
	explorer.vtiRefreshWebFromServer
	Set explorer = Nothing
	‘ NOTE: it is important to set the OLE object variable 
	‘ to Nothing so that the OLE connection is released
}

Note: The remaining sections describe the OLE methods supported by each component in FrontPage. In the top right corner of each page is the OLE component name used to access the method. The method parameters and return value are presented in both C++ and Visual Basic notation.

4. FRONTPAGE EXPLORER AUTOMATION

The following is a list of all the OLE automation methods supported by the FrontPage Explorer (using the OLE identifier FrontPage.Explorer.1.1):

	long vtiCreateWeb(LPCTSTR szServerURL, LPCTSTR szWebName);
	void vtiRefreshWebFromServer();
	long vtiPutDocument(LPCTSTR szFileName, LPCTSTR szURL, BOOL bBlockingRequest);
	long vtiPutWebMetaInfo(LPCTSTR szNameValuePairs);
	void vtiSetWebRecalcDependencies(BOOL bRecalcOn);
	BSTR vtiGetWebPageMetaInfo(LPCTSTR szURL, LPCTSTR szKeyName);
	void vtiBringToTop();
	BSTR vtiGetWebTitle();
	BSTR vtiGetWebURL();
	void vtiPromptOpenWeb();
	long vtiRemoveWeb(LPCTSTR szWebName);
	BOOL vtiIsPageInWeb(LPCTSTR szURL);
	BSTR vtiGetWebMetaInfo(LPCTSTR szKey);
	BSTR vtiGetPageList(long lType);
	BOOL vtiPutDocuments(LPCTSTR szFileList, LPCTSTR szUrlList);
	void vtiCancelRequests();
	BOOL vtiOpenWeb(LPCTSTR pszServer, LPCTSTR pszWebName, LPCTSTR pszUser);
	long vtiEditWebPage(LPCTSTR pszPageURL);
	long vtiPutWebPageMetaInfo(LPCTSTR pszURL, LPCTSTR pszNameValuePairs);
	long vtiGetDocToFile(LPCTSTR pszURL, LPCTSTR pszFilename);

This list was created from the FrontPage Explorer’s exported type library.

vtiCreateWeb

C++: long vtiCreateWeb(LPCTSTR szServerName, LPCTSTR szWebName);

VB: vtiCreateWeb(ServerName as String, WebName as String) as Long

Description

Creates a new web on the web server. The Root Web (‘/’) is created when the Web Extender software is installed. This method will create a top-level web directly under the Root Web’s URL (‘/subweb1’, ‘/subweb2’, etc.). 

This is a blocking call. When it returns successfully, the new web has been created and is ready for use. Most wizards won’t need to use this call, since FrontPage will create a new web (if necessary) before launching a web wizard, if the user hasn’t selected the “Add to Current Web” check-box in the New Web and New Page dialogs.

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

ServerName is the IP name or address of the web server’s host machine. It can include an optional port number. Examples: “www.company.com”, “www.company.com:1800”.

WebName is the name of the new web you want to create. Since this will map into a directory on the web server, it should be a legal 8.3 filename for a Windows web server. Longer names can be used with UNIX web servers. Example: “myweb”.

CHANGE: In version 1.0, this method took an additional proxy argument. Proxies are now handled globally by the FrontPage Explorer. The old interface was:

long vtiCreateWeb(LPCTSTR szServerURL, LPCTSTR szWebName, LPCTSTR szProxyURL);

vtiRefreshWebFromServer

C++: void vtiRefreshWebFromServer();

VB: vtiRefreshWebFromServer

Description

Causes the Explorer to refresh all its views of the current web, by placing a call to the FrontPage Server Extensions to check for any updates on the web server. The Explorer’s interface will then reflect up-to-date information about the web, such as any pages or links that have been added by another author.

This is a blocking call. It is typically used after uploading several documents to the web using vtiPutDocuments.

WARNING: If the FrontPage Explorer has no open web, calling this method will cause the FrontPage Explorer to display the message “System exception: access violation.” To avoid this problem, check that the string returned by vtiGetWebURL is not empty before calling this method.

Return Value

None.

Parameters

None.

vtiPutDocument

C++: long vtiPutDocument(LPCTSTR szFileName, LPCTSTR szURL,
				 BOOL bBlockingRequest);

VB: vtiPutDocument(FileName as String, URL as String, 
			 BlockingRequest as Integer) as Long

Description

Takes a file from the local file system and uploads it to the current web, using the authorization established for the Explorer’s user when the current web was opened. An error occurs if no web is currently open. After the document is uploaded, the FrontPage Server Extensions will expand any Bots in the document, and regenerate any other documents that depend upon the one being uploaded. Finally, the FrontPage Explorer will refresh its views after all server-side updating has finished.

The uploaded document will overwrite any previous web document with the same name. If another user has modified that document since the web was opened or last refreshed, a dialog box will appear giving the user the opportunity to overwrite or preserve the old document. In general, you should use vtiIsPageInWeb to determine if this method would overwrite a particular document. Use vtiPutDocuments to upload several files at once.

This can be a blocking or non-blocking call depending on the BlockingRequest parameter. Currently there is no way to determine when a non-blocking request has completed. 

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

FileName is the absolute path to a file on the local file system. It can be an ASCII or binary file. In Visual Basic, you typically place “App.Path” and “\” into a string before adding the name of a file in the current directory. Example: “C:\test\index.htm”.

URL is what you want the file to be named in your web. You can use “8.3” filenames to be safe; otherwise, you’ll need to use vtiGetWebMetaInfo to examine the filename conventions on the web server. The parameter can contain “/”characters to refer to web subdirectories, as long as they exist in the web. For most webs, valid subdirectories are “images”, “_private”, and “cgi-bin”. Examples: “index.htm”, “images/logo.gif”.

BlockingRequest should normally be set True.

vtiPutWebMetaInfo

C++: long vtiPutWebMetaInfo(LPCTSTR szNameValuePairs);

VB: vtiPutWebMetaInfo(NameValuePairs as String) as Long

Description

This method establishes the dictionary of name-value pairs that are available to any web document. At the moment the main use for these attributes is in conjunction with the Substitution Bot, but many other applications are possible. This method forces an update of all web documents that depend on the meta-info data. See vtiGetWebMetaInfo for information on how to retrieve web meta-info settings, and for a listing of the variables defined by the FrontPage Server Extensions.

All keys beginning with the characters “vti_” are reserved.

This is a blocking call. 

WARNING: If the FrontPage Explorer has no open web, calling this method will cause the FrontPage Explorer to display the message “System exception: access violation.” To avoid this problem, check that the string returned by vtiGetWebURL is not empty before calling this method.

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

NameValuePairs is a string containing a list of names and values separated by colon (“:”) characters. Each name-value pair is separated by a newline delimiter character (“\n” in C++, or “CHR$(10)” in Visual Basic). The names are case insensitive; the web server will store them in all lower-case. Example: “companyname:FooCorp\nfax:555-1212”.

CHANGE: In version 1.0 of FrontPage, the delimiter character between name-value pairs was a vertical bar (“|”).

vtiSetWebRecalcDependencies

C++: void vtiSetWebRecalcDependencies(BOOL bRecalcOn);

VB: vtiSetWebRecalcDependencies(RecalcOn as Integer)

Description

This method turns document dependency updating on or off in the current web by changing the value of the web meta-info variable vti_AutoRecalc. While dependency updating is turned off (vti_AutoRecalc=0), any uploaded documents are kept in a staging area on the web server (the “_vti_shm” directory) in an unexpanded state (with Bots not evaluated) until you turn dependency updating back on (vti_AutoRecalc=1). 

While dependency updating is turned off, none of the documents uploaded by vtiPutDocument will appear to be in the web as seen by browsers.

This is a blocking call. 

NOTE: To upload multiple documents efficiently, use the vtiPutDocuments method instead of combining vtiSetWebRecalcDependencies with vtiPutDocument. The vtiPutDocuments method will  automatically turn off dependency updating when it begins uploading documents and on again when it finishes. 

Using vtiSetWebRecalcDependencies is discouraged, since if you accidentally leave recalculation turned off, authors will perceive the web as being broken. Selecting the Recalculate Links option from the FrontPage Explorer’s Tools menu will fix the problem.

Return Value

None.

Parameters

RecalcOn is set to False to stop dependency updating and True to turn it back on. When RecalcOn is set to True after being set to False, the entire web is checked for dependencies and updated before the method returns. 

vtiGetWebPageMetaInfo

C++: CString vtiGetWebPageMetaInfo(LPCTSTR szURL, LPCTSTR szKeyName);

VB: vtiGetWebPageMetaInfo(URL as String, KeyName as String) as String

Description

This method looks up the value of an attribute in the dictionary of meta-info for the named document in the current web. Each document in the web, including image files, has a separate meta-info dictionary which is independent of the web’s meta-info dictionary. At the moment the dictionary’s keys are fixed; their values are maintained by the FrontPage Server Extensions.

Return Value

The return value is a string containing the value of the requested key, or the empty string if the key doesn’t exist.

Parameters

URL is a string containing the name of a document in the current web. Examples: “index.htm”, “images/logo.gif”.

KeyName is one of the words from the following list. All entries beginning with the characters “vti_” are reserved. All keys are case-insensitive. The currently available keys include:

	vti_Author		 example: “ellen”
	vti_Editor		 example: “FrontPage Frames Wizard”
	vti_ExtenderVersion	 example: “1.0.2.0”
	vti_FileSize		 example: “3243”
	vti_LinkInfo		 example: “FHUS|index.htm FSUS|images/logo.gif”
	vti_ModifiedBy	 example: “jeff”
	vti_TimeCreated	 example: “06 Aug 1995 14:19:19 EDT”
	vti_TimeLastModified example: “02 Nov 1995 08:52:53 EST”
	vti_Title		 example: “Policies and Procedures”

The following are notes about particular keys:

•	The key vti_Editor is new in version 1.1. It is only set by the FrontPage Frames Wizard. This attribute overrides the type of editor used for a particular web document. The value should match the name of an editor configured from the FrontPage Explorer’s Tools menu.
•	The key vti_LinkInfo contains a potentially long list of all the links and external references on the page, with encoded type information. Each link or reference is preceded by a few characters indicating the type of link or reference; these can be stripped off and ignored by many applications. The type information for each link is terminated by a vertical bar (‘|’). See the table on the next page for an explanation of the type code characters.

VtiGetWebPageMetaInfo  (continued)

The following table explains the type coding characters stored in the vti_LinkInfo page meta-info variable. The link information is stored as a space-separated list of URLs, each preceded by four (4) letters encoding the type of link on the page and a vertical bar (‘|’). In FrontPage 1.0, there were only two type coding characters; in FrontPage 1.1, the third and fourth characters are reserved, and the set of possible values for the first two characters has been expanded. The links appear in the list in the same order they appear on the page.

Position	Code	Meaning	
			
0: URL status	N	referenced URL not found	
	F	referenced URL is a file	
	S	referenced URL is an executable script	
	W	referenced URL is a directory (ending in ‘/’), and directory has a valid welcome page (such as index.htm or Welcome.html)	
	D	referenced URL is a directory (ending in ‘/’), but directory doesn’t have a valid welcome page (such as index.htm or Welcome.html)	
			
1: link type	H	link is an HREF (in <A> construct)	
	L	link is an imagemap HREF	
	B	link is a Bot-generated HREF	
	C	link is a Bot-generated HREF	
	A	link is an ACTION (in <FORM> construct)	
	S	link is a SRC attribute (in <IMG> construct)	
	M	link is a SRC attribute (in an imagemap)	
	I	link is an included page (from Include Bot)	
	T	link is a text index (from Search Bot)	
	Y	link is a style source page	
	F	link is a frame SRC attribute (in <FRAME> construct)	
			
2: reserved	U	always set to ‘U’ in FrontPage 1.1	
			
3: reserved	S	always set to ‘S’ in FrontPage 1.1	

As an example, the link information for a page might be as follows:

FHUS|goodpage.htm NHUS|badpage.htm SSUS|cgi-bin/foo.exe FSUS|images/logo.gif

This would mean that the page contains a valid link to “goodpage.htm”, an invalid link to “badpage.htm”, a valid link to the script file “cgi-bin/foo.exe”, and a valid in-line image referencing “images/logo.gif”.

vtiBringToTop

C++: void vtiBringToTop();

VB: vtiBringToTop

Description

This method activates the FrontPage Explorer and brings it to the top of the stack of other application windows.

Return Value

None.

Parameters

None.

 vtiGetWebTitle

C++: CString vtiGetWebTitle();

VB: vtiGetWebTitle as String

Description

This method returns the title of the current web, as set by an author in the FrontPage Explorer. A web’s title is analagous to the TITLE tag in a web page. 

Return Value

The title of the current web. If no title has been set, the returned string will be the same as the web’s URL (see vtiGetWebURL). Returns an empty string if there is no current web, or if the current web is the Root Web (“/”).

Parameters

None.

vtiGetWebURL

C++: CString vtiGetWebURL();

VB: vtiGetWebURL as String

Description

This method returns the full URL of the current web, starting with the string “http://”, then including the web server’s name (and its port number, if not the default of ‘80’), and followed by the web path relative to the server’s root directory. Use this string to construct a valid web address (full URL) for the current web server, or any page or image in the current web.

Return Value

Examples: “http://www.foocorp.com”, “http://foocorp.com:1492/explore”.

Parameters

None.

vtiPromptOpenWeb

C++: void vtiPromptOpenWeb();

VB: vtiPromptOpenWeb

Description

This method causes the FrontPage Explorer’s “Open Web” dialog box to be shown.

Return Value

None.

Parameters

None.

vtiRemoveWeb

C++: long vtiRemoveWeb(LPCTSTR szWebName);

VB: vtiRemoveWeb(WebName as String) as Long

Description

This method removes the named web from the current web server, assuming the user has Administrator permissions for it.

WARNING: If the FrontPage Explorer has no open web, calling this method will cause a run-time OLE error in your program, with the message “The server threw an exception.” To avoid this problem, check that the string returned by vtiGetWebURL is not empty before calling this method. Also, be sure that the web name you pass to this method begins with an initial slash.

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

WebName is the name of the web to remove. The parameter must match the name of a valid subweb on the same server as the current web, and must begin with an initial slash. Example: “/myweb”.

CHANGE: If the web being removed is the same as the current web, the FrontPage Explorer now closes the web first.

vtiIsPageInWeb

C++: BOOL vtiIsPageInWeb(LPCTSTR szURL);

VB: vtiIsPageInWeb(URL as String) as Integer

Description

This method checks to see if a document exists in the current web, with the given web-relative URL.

Return Value

The return value is true (non-zero) if the document is in the web, and false (zero) if not.

Parameters

URL is the web-relative path to the document being checked for existence.

 vtiGetWebMetaInfo

C++: CString vtiGetWebMetaInfo(LPCTSTR szKey);

VB: vtiGetWebMetaInfo(Key as String) as String

Description

This method looks up a key in the web’s meta-info dictionary and returns its value. All keys beginning with the characters “vti_” are reserved. See vtiPutWebMetaInfo for a description of how to define your own web variables. The FrontPage Server Extensions define and maintain the following read-only meta-info keys:

	vti_AutoRecalc		example: “1”
	vti_CaseSensitiveURLs	example: “1”
	vti_ExtenderVersion		example: “1.1.1.40”
	vti_FeatureList		example: “vti_ServiceRename”
	vti_HtmlExtensions		example: “.html.htm.htm.”
	vti_HttpdVersion		example: “Apache/0.6.5”
	vti_LongFilenames		example: “1”
	vti_RetartManual		example: “0”
	vti_TextExtensions		example: “.txt.”
	vti_TimeCreated		example: “28 Jun 1995 20:21:11 EDT”
	vti_WelcomeNames		example: “index.html index.htm”

All time variables are stored in RFC 1123 format. Boolean variables are either “0” (False) or “1” (True). Extensions are reported as a string separated and terminated by dots (“.”). Multiple values are separated by spaces. The following are notes on particular keys:

•	vti_AutoRecalc is the variable that is manipulated by vtiSetWebRecalcDependencies
•	vti_CaseSensitiveURLs is false if the server doesn’t see any difference between URLs like “INDEX.HTM” and “index.htm” (such as on Windows-based servers), and true if it does
•	vti_FeatureList is a space-separated list of features that are not supported by the current web or web server. Typically this string is empty. Possible values in this list include vti_ServiceRename, vti_ServiceRemove, vti_ACAll, vti_ACRegisteredEndUsers, vti_ACIPAddresses, and vti_ACCreateNewUsers. The prefix AC refers to Access Control.
•	vti_HtmlExtensions and vti_TextExtensions show what the server expects for filename endings for HTML and plain-text files, respectively; each list is terminated with a dot (‘.’)
•	vti_LongFilenames is true if the server supports filenames longer than the DOS 8.3 convention (8 characters followed by a dot and a 3-letter extension)
•	vti_RestartManual is true if the HTTPD server program must be restarted every time a new web is created; some web servers cannot be forced to re-read their configuration files while running
•	vtiWelcomeNames is a space-separated list, in order, of all the default “home page” names for the current web; this is the page returned when the server is asked for the web directory URL rather than a specific page in the web (example: a request for “http://www.foocorp.com” returns the page “http://www.foocorp.com/index.htm”)

Return Value

The value of the requested key, or the empty string if no such key exists.

Parameters

Key is the name of the meta-info value to retrieve.

vtiGetPageList

C++: CString vtiGetPageList(long lType);

VB: vtiGetPageList(DocType as Long) as String

Description

This method returns a list of all the documents of a given type (currently HTML, Image, or All) in the current web. Each document in the web has an associated title, analagous to the TITLE tag in a web page. Both the document title and web-relative URL are returned to the caller.

Images are currently defined as any file whose names end  in “.gif”, “.jpg”, or “.jpeg”; this definition is subject to change. HTML files are determined by a match with the vti_HtmlExtensions web meta-info variable (see vtiGetWebMetaInfo).

Return Value

The return string has two lines for each document, the first holding the document title and the second the document URL. If a document  doesn’t have a title attribute, the returned title will be the same as the document URL. Each string ends with a newline character  (“\n” in C++, or “CHR$(10)” in Visual Basic). If there is no current web or there are no documents in the current web, the result is an empty string. 

Example: “Home Page\nindex.htm\nCorporate Logo\nimages/logo.” (where “\n” is the newline character, not “\” followed by “n”).

Parameters

DocType is currently defined as one of three types: All (0), HTML (1), or Image (2). This may be extended in the future to include other document types. If DocType is 0, all documents in the web are returned. If DocType is 1, only documents considered by the web server to contain HTML are returned. If DocType is 2, only documents considered by FrontPage to be a common web image type are returned (currently those with the extensions “.gif”, “.jpg”, “.jpeg”, and various case combinations of these, such as “.GIF”). 

vtiPutDocuments

C++: BOOL vtiPutDocuments(LPCTSTR szFileList, LPCTSTR szUrlList);

VB: vtiPutDocuments(FileList as String, UrlList as String) as Integer

Description

This method uploads a list of files from the local file system to the current web, using the authorization established for the FrontPage Explorer’s user when the current web was opened. An error occurs if no web is currently open. 

When the documents are uploaded, the FrontPage Server Extensions will expand any WebBots in the documents, and regenerate any other documents that depend upon the ones being uploaded. If a URL matches an existing document in the web, a dialog box will appear, giving the user the opportunity to overwrite or preserve the old document.

This method turns off dependency recalculation in the web during upload by setting the web meta-info variable vti_AutoRecalc to 0 when the transaction begins and back to 1 when it finishes. See vtiSetWebRecalcDependencies for more information.

This method blocks until all files have been uploaded and the server has updated all web dependencies, unless an error occurs during the upload process. Since this method does not update the FrontPage Explorer’s views, in most cases you will want to call vtiRefreshWebFromServer soon afterwards.

Return Value

The return value is true (non-zero) if the call succeeds, and false (zero) if it fails.

Parameters

FileList is a list of absolute paths to files on the local file system. Files can be ASCII or binary. In Visual Basic, you typically place “App.Path” and “\” into a string before adding the name of a file in the current directory. Each file name is separated by a newline character (“\n” in C++, or “CHR$(10)” in Visual Basic). Example: “C:\test\index.htm\nC:\test\logo.gif”.

UrlList is a list of the web-relative URLs where each file in FileList (in the exact same order as in FileList) will be stored in the target web. You can use “8.3” filenames to be safe; otherwise, you’ll need to use vtiGetWebMetaInfo to examine the filename conventions on the web server. The parameter can contain “/”characters to refer to web subdirectories, as long as they exist in the web. For most webs, valid subdirectories are “images”, “_private”, and “cgi-bin”. Example: “index.htm\nimages/logo.gif”.

vtiCancelRequests	

C++: void vtiCancelRequests();

VB: CancelRequests

Description

This method will interrupt any pending requests from the FrontPage Explorer to the web server. The effect of this call is the same as pushing the red “Stop” button in the Explorer’s or Editor’s toolbar.

Return Value

None.

Parameters

None.

vtiOpenWeb	

C++: BOOL vtiOpenWeb(LPCTSTR pszServer, LPCTSTR pszWebName, 
   LPCTSTR pszUser);

VB: vtiOpenWeb(Server as String, WebName as String, User as String) 
   as Integer

Description

This method will start to open a given web on a given HTTP server, optionally using an HTTP proxy server, with the given username. The user will still have to provide the password by typing it into the FrontPage Explorer’s authorization dialog box.

This call blocks until the web is opened in the Explorer (unless an error occurs).

Return Value

The return value is true (non-zero) if the web is opened, and false (zero) if not.

Parameters

Server is the designation for the web server, including an optional port number, but without the “http://” prefix. Examples: “www.foocorp.com”, “foocorp.1492”.

WebName is the name of the desired web on the server, or the empty string for the Root Web. No inital slash is required for subwebs. Example: “myweb”.

User holds the name of an Administrator or Author in the target web, or the empty string if the user should type in both the username and password.

CHANGE: In version 1.0, this method took an additional proxy argument. This parameter was removed, since proxies are now handled globally by the FrontPage Explorer. The old interface was:

BOOL vtiOpenWeb(LPCTSTR pszServer, LPCTSTR pszProxy, LPCTSTR pszWebName, LPCTSTR pszUser);

vtiEditWebPage

C++: long vtiEditWebPage(LPCTSTR pszPageURL);

VB: vtiEditWebPage(PageURL as String) as Long

Description

This method will load a web from the current web, or the Internet, into the appropriate editor. For HTML documents, this is typically the FrontPage Editor.

This call is non-blocking; it returns immediately, and does not wait until the page is loaded into an editor.

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

PageURL designates a document in the current web or on the Internet. Examples: “index.htm”, “http://www.some-company.com/”, “logo.gif”.

vtiPutWebPageMetaInfo

C++: long vtiPutWebPageMetaInfo(LPCTSTR pszURL, 
  LPCTSTR pszNameValuePairs);

VB: vtiPutWebPageMetaInfo(PageURL as String, 
  NameValuePairs as String) as Long

Description

This method sets one or more meta-info variables for the named web page.

This is a blocking call.

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

PageURL designates an HTML page in the current web. Example: “index.htm”.

NameValuePairs is a string containing meta-info names and values. Each name is followed by a colon (“:”), then the value, and a newline (“\n” in C++, or CHR$(10) in Visual Basic). Example: “name1:value1\nname2:value2\n”.

vtiGetDocToFile

C++: long vtiGetDocToFile(LPCTSTR pszURL, LPCTSTR pszFilename);

VB: vtiGetDocToFile(URL as String, FileName as String) as Long

Description

This method retrieves a document from the current web or the Internet and saves it to a local file.

The call blocks until the file is finished downloading.

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

URL designates a document in the current web or on the Internet. Examples: “index.htm”, “images/undercon.gif”, “test.doc”, “http://www.some-company.com/”.

FileName is an absolute pathname where the file should be saved. Examples: “C:\temp\index.htm”, “C:\temp\undercon.gif”, “C:\temp\test.doc”.

5. FRONTPAGE EDITOR AUTOMATION

The following is a list of all the OLE automation methods supported by the FrontPage Editor (using the OLE identifier FrontPage.Editor.1.1):

LPDISPATCH vtiOpenWebPage(LPCTSTR szFileName, LPCTSTR szURL, LPCTSTR szWebURL, 
			LPCTSTR szWebTitle);
long vtiQueryWebPage(LPCTSTR szURL, LPCTSTR szWebURL);
void vtiBringToTop();
LPDISPATCH vtiNewWebPage(LPCTSTR szURL, LPCTSTR szWebURL, LPCTSTR szWebTitle);

This list was created from the FrontPage Editor’s type library.

IMPORTANT:  The FrontPage Editor’s methods that create new documents (vtiOpenWebPage and vtiNewWebPage) return a pointer to an OLE object representing the new document. At the moment, there are no automation methods for manipulating these FrontPage Editor documents. You should release this object as soon as it is returned to avoid creating orphan object references, as shown below in both C++ and Visual Basic:

C++:	
LPDISPATCH pNewDoc = editor.vtiOpenWebPage(“C:\test.htm”,
 	“test.htm”,NULL,NULL);
	if(pNewDoc != NULL) pNewDoc->Release();

VB: 	
	Dim newdoc as Object

	Set newdoc = editor.vtiOpenWebPage(“C:\test.htm”,”test.htm”,””,””)
	Set newdoc = Nothing  ‘ release document’s dispatch object

vtiOpenWebPage

C++: LPDISPATCH vtiOpenWebPage(LPCTSTR szFileName, LPCTSTR szURL,
					 LPCTSTR szWebURL, LPCTSTR szWebTitle);

VB: vtiOpenWebPage(FileName as String, URL as String, 
			 WebURL as String, WebTitle as String) as Object

Description

This method causes the FrontPage Editor to open an existing web page from a file on the user’s local disk drive. If you want to open an existing page from the current web (on a local or remote web server) or from the Internet, see the FrontPage Explorer method vtiEditWebPage.

Return Value

A pointer to an OLE dispatch object suitable for further automation calls (when they are defined). For the 1.1 release of FrontPage, you should immediately release this object as described at the start of this section.

Parameters

FileName is an absolute path to a web page file on the user’s local disk drive. Example: “C:\temp\test.htm”.

URL is the suggested web-relative URL for this page that the Editor will use if it is to save the file into a web. Example: “test.htm”.

WebURL is an indication to the Editor of the web that the document should be saved to. You can use the FrontPage Explorer method vtiGetWebURL to set this parameter. Example: “http://www.foocorp.com”.

WebTitle is an indication to the Editor of the web that the document should be saved to. You can use the FrontPage Explorer method vtiGetWebTitle to set this parameter. Example: “FooCorp Main Web”.

vtiQueryWebPage

C++: long vtiQueryWebPage(LPCTSTR szURL, LPCTSTR szWebURL);

VB: vtiQueryWebPage(URL as String, WebURL as String) as Long

Description

This method lets you find out if the FrontPage Editor is currently editing a given page from a given web.

Return Value

The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.

Parameters

URL is a web-relative URL indicating the document being queried. Example: “test.htm”.

WebURL indicates the web that the document came from. You can use the FrontPage Explorer method vtiGetWebURL to set this parameter. Examples: “www.foocorp.com”, “http://www.foocorp.com”.

vtiBringToTop

C++: void vtiBringToTop();

VB: vtiBringToTop

Description

This method brings the FrontPage Editor window to the top of the stack of application windows on the user’s desktop.

Return Value

None.

Parameters

None.

 vtiNewWebPage

C++: LPDISPATCH vtiNewWebPage(LPCTSTR szURL, LPCTSTR szWebURL, 
					LPCTSTR szWebTitle);

VB: vtiNewWebPage(URL as String, WebURL as String,
			WebTitle as String) as Object

Description

This method causes the FrontPage Editor to create a new empty web page, with a given default URL and optional web information.

Return Value

A pointer to an OLE dispatch object suitable for further automation calls (when they are defined). For the 1.0 release of FrontPage, you should immediately release this object as described at the start of this section.

Parameters

URL is the suggested web-relative URL for this page that the Editor will use if it is to save the page into a web. Example: “test.htm”.

WebURL is an indication to the Editor of the web that the document should be saved to. You can use the FrontPage Explorer method vtiGetWebURL to set this parameter. Examples: “www.foocorp.com”, “http://www.foocorp.com”.

WebTitle is an indication to the Editor of the web that the document should be saved to. You can use the FrontPage Explorer method vtiGetWebTitle to set this parameter. Example: “FooCorp Main Web”.

6. FRONTPAGE TO DO LIST AUTOMATION

The following is a list of all the OLE automation methods supported by the FrontPage To Do List (using the OLE identifier FrontPage.ToDoList.1.1):

	void vtiShow();
	void vtiHide();
	BOOL vtiAddTask(LPCTSTR taskName, short priority, LPCTSTR createdBy, LPCTSTR url, LPCTSTR cookie, 
			LPCTSTR comment);
	long vtiGetActiveCount();
	BOOL vtiCompletedTaskByUrl(LPCTSTR url, LPCTSTR cookie);
	BOOL vtiWorkedOnTaskByUrl(LPCTSTR url, LPCTSTR cookie);
	BOOL vtiAddTaskAskUser(LPCTSTR taskName, short priority, LPCTSTR createdBy, LPCTSTR url, 
			LPCTSTR cookie, LPCTSTR comment);

This list was created from the FrontPage To Do List’s type library.

vtiShow

C++: void vtiShow();

VB: vtiShow

Description

This method causes the To Do List dialog to appear.

Return Value

None.

Parameters

None.

vtiHide

C++: void vtiHide();

VB: vtiHide

Description

This method causes the To Do List dialog to disappear.

Return Value

None.

Parameters

None.

vtiAddTask

C++: BOOL vtiAddTask(LPCTSTR TaskName, short Priority, 
			   LPCTSTR CreatedBy, LPCTSTR URL, 
			   LPCTSTR Cookie, LPCTSTR Comment);

VB: vtiAddTask(TaskName as String, Priority as Integer,
		   CreatedBy as String, URL as String, 
		   Cookie as String, Comment as String) as Integer

Description

This method causes a new task to be appended to the To Do List.

Return Value

The return value is true (non-zero) for success, and false (zero) for failure.

Parameters

TaskName is typically a short verb phrase, two or three words in length, which is used to identify the task. Examples: “Fix Mail Address”, “Create Image Map”.

Priority is a number between 1 and 3 identifying the importance of the task. These are displayed to the user as “High” (1), “Medium” (2), or “Low” (3).

CreatedBy is the name of the tool (program) adding the task. Example: “PageWizard”.

URL is the web document associated with this task. Most tasks involve editing some file stored in the web. This could be an HTML file, an image file, a movie file, or any other kind of file. HTML files are edited with the FrontPage Editor. Editors for other types of files can be configured from the Explorer. Examples: “index.htm”, “images/logo.gif”.

Cookie is a string meant to contain a reference to a part of a document, but it can be used for other application-specific purposes. For HTML files, this parameter can be set to a bookmark. Example: “#bookmark”.

Comment is a description of the task that contains details too lengthy to present in the TaskName parameter. Example: “change all email addresses to reflect our new domain name”.

vtiGetActiveCount

C++: long vtiGetActiveCount();

VB: vtiGetActiveCount as Long

Description

This method returns the number of tasks currently in the To Do List.

Return Value

The number of active tasks.

Parameters

None.

 vtiCompletedTaskByUrl

C++: BOOL vtiCompletedTaskByUrl(LPCTSTR url, LPCTSTR cookie);

VB: vtiCompletedTaskByUrl(URL as String, Cookie as String) as Integer

Description

This method marks the first task matching the given URL and cookie as completed, and removes it from the list of active tasks.

Return Value

The return value is true (non-zero) for success, and false (zero) for failure.

Parameters

URL is the web-relative path to a document in the current web.

Cookie is an optional specifier for a part of the document (such as a bookmark in an  HTML file), or some application-specific identifier.

vtiWorkedOnTaskByUrl

C++: BOOL vtiWorkedOnTaskByUrl(LPCTSTR url, LPCTSTR cookie);

VB: vtiWorkedOnTaskByUrl(URL as String, Cookie as String) as Integer

Description

This method adds a notation that the current user has worked on (but not completed) the task specified by the given URL and cookie.

Return Value

The return value is true (non-zero) for success, and false (zero) for failure.

Parameters

URL is the web-relative path to a document in the current web.

Cookie is an optional specifier for a part of the document (such as a bookmark in an  HTML file), or some application-specific identifier.

vtiAddTaskAskUser

C++: BOOL vtiAddTaskAskUser(LPCTSTR TaskName, short Priority, 
				    LPCTSTR CreatedBy, LPCTSTR URL, 
				    LPCTSTR Cookie, LPCTSTR Comment);

VB: vtiAddTaskAskUser(TaskName as String, Priority as Integer,
			    CreatedBy as String, URL as String, 
			    Cookie as String, Comment as String) as Integer

Description

This method causes a new task to appended to the To Do List, but unlike vtiAddTask, it brings up a dialog for assigning the task to a different FrontPage username.

Return Value

The return value is true (non-zero) for success, and false (zero) for failure.

Parameters

TaskName is typically a short verb phrase, two or three words in length, which is used to identify the task. Examples: “Fix Mail Address”, “Create Image Map”.

Priority is a number between 1 and 3 identifying the importance of the task. These are displayed to the user as “High” (1), “Medium” (2), or “Low” (3).

CreatedBy is the name of the tool (program) adding the task. Example: “PageWizard”.

URL is the web document associated with this task. Most tasks involve editing some file stored in the web. This could be an HTML file, an image file, a movie file, or any other kind of file. HTML files are edited with the FrontPage Editor. Editors for other types of files can be configured from the Explorer. Examples: “index.htm”, “images/logo.gif”.

Cookie is a string meant to contain a reference to a part of a document, but it can be used for other application-specific purposes. For HTML files, this parameter can be set to a bookmark. Example: “#bookmark”.

Comment is a description of the task that contains details too lengthy to present in the TaskName parameter. Example: “change all email addresses to reflect our new domain name”.

EXAMPLES

The FrontPage Developer’s Kit includes examples showing how to create wizards and templates for FrontPage, and how to create custom CGI programs that interface with the FrontPage Personal Web Server. There are also some utility programs built with the FrontPage OLE Automation APIs.

The files distributed with the FrontPage Developer’s Kit are as follows:

Documentation

•	this document : in both Microsoft Word (.doc) and Rich Text (.rtf) format

Templates

•	pages\tablepag.tem : a page template containing a table; created with the Save as Template command in the FrontPage Editor
•	webs\testcorp.tem : a web template containing documents from the FrontPage Corporate Presence Web Wizard; created with the Web Template Maker utility
•	frames\sample.frm : a frameset template with recursive frames and multiple targets

Wizards

•	pages\hello.wiz : a very simple page wizard; written in Microsoft Visual Basic 4.0
•	pages\calendar.wiz : a page wizard that creates a calendar for a selected month and year using an HTML table; written in Microsoft Visual Basic 4.0
•	webs\helloweb.wiz : a very simple web wizard; written in Microsoft Visual Basic 4.0
•	webs\realest.wiz : a web wizard that creates a small web of interconnected pages about real estate; written in Microsoft Visual Basic 4.0

•	vb : support modules containing procedures used by the sample wizard programs
•	vc : type libraries and object libraries for using FrontPage automation from C++

Utility Programs

•	APITests : a program that exercises all of the automation interfaces to the FrontPage tools; includes a lot of reusable code for common tasks
•	FPlaunch : a helper application that opens a web and starts editing a page when the user follows a link; uses a parameter file stored on the web server
•	WebTmpl : a program that creates web template directories for FrontPage 1.1 based on a current web managed by a local FrontPage Personal Web Server

CGI Scripts

•	hello : a very simple example showing how to create a CGI program in C using the standard I/O (stdio) interface
•	cgiwin32 : a gateway between the stdio CGI interface and the CGI-WIN interface; written in C
•	olecgi : a gateway between the stdio CGI interface and OLE server DLLs created with Visual Basic 4.0; written in C
•	olecgivb: example CGI handler objects and utility classes for use with olecgi; written in Microsoft Visual Basic 4.0