

MicrosoftR FrontPageR 98
Software Developer's Kit


Copyright c 1995 - 1997 Microsoft Corporation.
All rights reserved.



Information in this document is subject to change without
notice. Companies, names, and data used in examples
herein are fictitious unless otherwise noted. Complying
with all applicable copyright laws is the responsibility
of the user. No part of this document may be reproduced
or transmitted in any form or by any means, electronic
or mechanical, for any purpose, without the express
written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks,
copyrights, or other intellectual property rights covering
subject matter in this document. The furnishing of
this document does not give you any license to these
patents, trademarks, copyrights, or other intellectual
property.






Your use of this Software Developer's Kit is subject
to the terms and conditions of an End User License
Agreement (EULA). See the document "license.doc" that
accompanies this file.

NOTE:  Microsoft Technical Support does not support
the FrontPage 98 Software Developer's Kit. If you have
limited programming experience and require assistance,
you may want to consult a Microsoft Solution Provider.
Our Solution Providers offer a wide range of fee-based
services, including creating custom software for use
with this and other Microsoft products. For more information
about Microsoft Solution Providers, call the Microsoft
Customer Information Service toll-free, at (800) 426
9400.




Audience  
Summary of Changes  
User Interface Terminology Changes  
Sample Files  
Documentation  
Templates  
Wizards  
Utility Programs  
CGI Scripts  
Designer HTML  
Custom FrontPage Components  
Menu Customization  
Customizing the FrontPage Explorer  
Adding New Menus  
Adding New Commands  
Customizing the FrontPage Editor  
Designer HTML  
Some Examples  
How WEBBOT Syntax Works  
Attributes on the WEBBOT Pseudo-Tag  
Valid HTML tag subset for ALT attribute text  
Appearance of Designer HTML Representation in the Editor  
Inserting an Extension File and Importing Images  
Templates  
Creating Page Templates  
Creating Web Templates  
Manually Creating Web Templates  
Frameset 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  
Wizards  
INF File  
Web Wizard vs. Page Wizard  
Command-line Arguments  
Input Parameters  
Output Parameters  
Sample Parameter File  
Wizards vs. Editors  
User Interface  
INI File Settings  
Naming Conventions  
International Output  
FrontPage Interactions  
Themes  
Theme Elements  
Anatomy of a Theme  
Theme Settings  
Fonts  
Default Font Substitutions  
Text Overlays  
Transparency  
Active Graphics (Animations & Hover Buttons)  
Anti-aliasing  
Color Palette  
Theme INF Files  
Theme-Specific INF File  
Font Handling and Themes.inf  
The FrontPage Theme Designer  
Setup  
Designing a New Theme  
Display Options  
Dynamic Properties  
Saving a New or Modified Theme  
Applying Custom Themes  
Sharing Custom Themes with Other Users  
OLE Automation Overview  
The FrontPage Explorer Interface  
The FrontPage Editor Interface  
The FrontPage To Do List Interface  
Programming Considerations  
Version Information  
Programming Examples  
FrontPage Explorer Automation  
vtiCreateWeb  
vtiRefreshWebFromServer  
vtiPutDocument  
vtiPutWebMetaInfo  
vtiSetWebRecalcDependencies  
vtiGetWebPageMetaInfo  
vtiBringToTop  
vtiGetWebTitle  
vtiGetWebURL  
vtiPromptOpenWeb  
vtiRemoveWeb  
vtiIsPageInWeb  
vtiGetWebMetaInfo  
vtiGetPageList  
vtiPutDocuments  
vtiCancelRequests  
vtiOpenWeb  
vtiEditWebPage  
vtiPutWebPageMetaInfo  
vtiGetDocToFile  
vtiGetFoldersList  
vtiGetPagesInFolder  
vtiCreateFolder  
vtiOpenWebWithPassword  
vtiListWebs  
vtiDisableErrorDialogs  
vtiQuit  
vtiPublishWeb  
vtiRemoveWebPages  
vtiRenameDocument  
vtiIsFeatureSupported  
vtiListThemes  
vtiApplyTheme  
vtiGetTheme  
vtiPutTheme  
vtiPutWebStructure  
vtiGetWebStructureRelations  
vtiReturnDBWRoot  
vtiMakeThemeFresh  
vtiSetCurrentView  
vtiIsFolderInWeb  
vtiSetFolderOptions  
vtiRefreshThemeList  
vtiSetEditor  
FrontPage Editor Automation  
vtiOpenWebPage  
vtiQueryWebPage  
vtiBringToTop  
vtiNewWebPage  
vtiListOpenDocs  
vtiRefreshDocument  
vtiGetBookmarkList  
vtiScrollToBookmark  
vtiInsertFile  
vtiInsertImage  
vtiGetTopPageUrl  
vtiInsertHTML  
vtiPaste  
vtiQuit  
vtiBringPageToTop  
vtiSetMetaTag  
vtiListMetaTags  
vtiDeleteMetaTag  
vtiGetMetaTag  
vtiQueryWebPageEx  
FrontPage To Do List Automation  
vtiShow  
vtiHide  
vtiAddTask  
vtiGetActiveCount  
vtiCompletedTaskByUrl  
vtiWorkedOnTaskByUrl  
vtiAddTaskAskUser  
Custom FrontPage Components  
Overview  
HTML Representation of FrontPage Components  
Activating a Custom FrontPage Component  
Editing Custom FrontPage Component Attributes  
Custom FrontPage Components  
Installing Custom FrontPage Components  
The Custom FrontPage Component Directory  
The Component Description File  
Per-Directory Keys  
Per-Bot Keys  
Supporting Multiple Client Bindings  
The Component Template File  
BTL Syntax  
Reserved BTL Attributes  
BTL Data Type Encoding  
The Custom FrontPage Component Implementation File  
Types of Custom FrontPage Components  
Determining Why the Component Was Activated  
Generating MIME Headers  
Clientside Components  
Additional Reserved Attributes  
DLL and Shared Library Implementation  
Example: Creating a client-side DLL  
Standard I/O Implementation  
Creating Custom FrontPage Component Libraries  
Windows Systems  
UNIX Systems  
Common Problems  
Incorrect Name Linkages  
Incorrect File Access Permissions  
Cached FrontPage Component Information Out of Date  
Errors Detected by FrontPage Explorer or Server Extensions  
Sharing Conflict While Installing New FrontPage Component
DLL  


Introduction

Audience

The intended audience for this Software Developer's
Kit (SDK) is anyone interested in extending the capabilities
of Microsoft FrontPage through the use of wizards,
templates, themes, custom FrontPage components, custom
menu commands, or Designer HTML. 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, custom FrontPage components
(formerly "WebBot components"), and OLE Automation
assume entry-level programming knowledge. Examples
are given in Microsoft Visual Basic and Microsoft Visual
C++.

If you have limited programming experience and require
assistance, you may want to consult a Microsoft Solution
Provider. Our Solution Providers offer a wide range
of fee-based services, including creating custom software
for use with this and other Microsoft products. For
more information about Microsoft Solution Providers,
please contact the Microsoft Customer Information Service
toll-free, at (800) 426-9400.

Summary of Changes
The major changes to the Microsoft FrontPage 98 Software
Developer's Kit include:

Additional OLE Automation interfaces for the FrontPage
Explorer and the FrontPage Editor
Additional support for custom FrontPage components,
including client side-only features and Active Server
Pages
New support for Themes

User Interface Terminology Changes
Technical discussion of "framesets" in this document
is equivalent to "frames pages" in the FrontPage 98
user interface.
The term "WebBot component" is retained for technical
discussion in portions of this document. In FrontPage
98, however, these elements are now referred to as
"FrontPage components."


Sample Files

The FrontPage Software Developer's Kit includes examples
showing how to create wizards, templates, themes, and
custom FrontPage components, and how to create custom
CGI programs that interface with the FrontPage Personal
Web Server. There are also some example Designer HTML
files, and several utility programs built with the
FrontPage OLE Automation APIs.

The files distributed with the FrontPage Software Developer's
Kit are as follows:
Documentation
fpdevkit.doc : (this document) in Microsoft Word format
Templates
template\pages\tablepag.tem : a page template containing
a table; created with the Save as Template command
in the FrontPage Editor
template\webs\testcorp.tem : a web template containing
documents from the FrontPage Corporate Presence Web
Wizard; created with the Web Template Maker
template\webs\wbtests.tem : a web template containing
sample pages to test against the example custom FrontPage
components in the SDK.
template\frames\sample.tem : a frameset template containing
two frames
Wizards
wizards\pages\hello.wiz : a very simple page wizard;
written in Visual Basic 5.0
wizards\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 5.0
wizards\webs\helloweb.wiz : a very simple web wizard;
written in Visual Basic 5.0
wizards\webs\realest.wiz : a web wizard that creates
a small web of interconnected pages about real estate;
written in Microsoft Visual Basic 5.0
wizards\vb : support modules with procedures used by
the sample wizard programs
wizards\vc : type and object libraries for using FrontPage
automation from C++
Utility Programs
Utility\APITests : a program that exercises many of
the automation interfaces to the FrontPage tools; includes
a lot of reusable code for common tasks
Utility\FPlaunch : a helper application for web browsers
that opens a web and starts editing a page when the
user follows a link; requires a parameter file on the
server
Utility\WebTmpl : a program that creates web template
directories for FrontPage based on a current web managed
by a local FrontPage Personal Web Server

CGI Scripts
CGI\hello : a very simple example showing how to create
a CGI program in C using the standard I/O (stdio) interface;
works with the FrontPage Personal Web Server
CGI\cgiwin32 : a gateway between the stdio CGI interface
and the CGI-WIN interface; written in C; works with
the FrontPage Personal Web Server
CGI\olecgi : a gateway between the stdio CGI interface
and OLE server DLLs created with Visual Basic 5.0;
written in C; works with the FrontPage Personal Web
Server
CGI\olecgivb: example CGI handler objects and utility
classes for use with olecgi; written in Microsoft Visual
Basic 5.0; works with the FrontPage Personal Web Server
Designer HTML
SpecialSearch.htm : a predefined FrontPage Search component
with default values already set for you.
The Date.htm : a small bit of JavaScript that will
display today's date in the page whenever it is browsed
to.
Image Map.htm :  HTML file with an associated graphic.
It contains a reference to an image map. This lets
you just drag and drop a complete image with the image
map and all of its links already pre-defined.
ExcelIA.htm : a Designer HTML file which gives a textual
display for Microsoft Excel Internet Assistant's template
pseudo-tag.
Custom FrontPage Components
wbtest1 : a very simple custom FrontPage component
that displays "Hello, World"; written in C
wbtest2 : three FrontPage components implemented by
a single module, including a form-handling component
and a component that writes out extra MIME headers;
written in C++
wbtest3 : two simple FrontPage components written in
Perl
wbtest4 : a form-handling components written in Perl
initcaps : a custom FrontPage component that displays
a string in upper-case with the first letter of each
word made larger; written in C++
tcltest : a simple FrontPage component written in Tcl
simple : a simple client-side DLL FrontPage component,
written in C++, showing a custom property editing dialog
for the component.
votebot : a more complex custom FrontPage component
implementing voting functionality; demonstrates both
client-side and server-side functionality



Menu Customization

FrontPage includes an easy way to extend the menus
of the FrontPage Editor and Explorer. This section
describes how you can add registry entries that will
add new menus or new commands to the Editor or Explorer.
These entries can specify the following parameters
for your custom menus:

menu name
location (which menu, where on the menu)
a command line to invoke when the menu is chosen
status bar text to display when the command is selected
a WinHelp file and topic number to invoke when context
sensitive help is used
whether to create a new top level menu
first and last version indicators to allow for version
specific customizations

In addition, the FrontPage Editor includes an additional
customization feature which lets you specify HTML that
should be automatically inserted into the current page
as the insertion point, when the menu command is invoked,
without having to write any code at all. This HTML
can be specified in two ways:

directly in the registry entry
as a reference to an HTML file on disk

The rest of this chapter gives detailed information
about the format of the required registry entries for
menu customization, and provides numerous examples.
Customizing the FrontPage Explorer
At startup time, FrontPage reads the Windows registry,
looking for menu extensibility keys for the Explorer,
either for new top level menus or new commands on existing
menus. 
Adding New Menus
The HKEY_CURRENT_USER\Software\Microsoft\FrontPage\Explorer\Init

Menus key has individual string values that specify
each custom menu. The string name must be a unique
name. Note that this key is independent of the version
of FrontPage.
Each string value under Init Menus has the following
syntax:
first_version, last_version, menu_bar_num, menu_name,
menu_position


Argument  Description  
first_version  The number of the earliest version of
FrontPage which should add this new top level menu
command. Values < 2 are treated as 2 (since this is
first version of FrontPage to support custom menus.)
Values greater than the current running version of
FrontPage tell FrontPage not to create this menu.
last_version  The number of the last version of FrontPage
which should add this new top level menu command. Values
less than the current running version of FrontPage
tell FrontPage not to create this menu. If omitted,
this argument is treated as being higher than the current
running version of FrontPage.
menu_bar_num  Number of the built-in menu bar to which
you want to add the menu. This field is ignored as
there is currently only one set of menus in the Explorer,
but the field value should be set to 1 to allow for
future expansion..
menu_name  Name of the new menu. The menu accelerator
is indicated by an ampersand character preceeding the
accelerator key, e.g. "&Tools".
menu_position  Position of the new menu on the menu
bar. This may be the name of the menu before which
you want to place the new menu, or a number indicating
the menu's position from the left end of the menu bar
(1-based). If the number or name does not exist or
the argument is omitted, then the new menu is placed
to the right of the Tools menu. When comparing this
string against menu names any accelerators present
in the menu names are ignored.
Example: menu1 = 2, ,1, &Site, Tools
The separator between elements is always a comma regardless
of the international version of FrontPage and/or the
system settings for list separator. Whitespace after
the commas is optional, but whitespace within a field
is significant and is preserved, allowing for spaces
in menu item names, for example "Bullets and Numbering".
Commas within a field can be specified by enclosing
the field in double quotes.
Adding New Commands
HKEY_CURRENT_USER\Software\Microsoft\FrontPage\Explorer\Init
Commands key has individual string values that specify
each custom command. The string name must be a unique
name. Note that this key is independent of the version
of FrontPage.
Each string value has the following syntax:
first_version, last_version, menu_bar_num, menu_name,
command_name, command_line, command_position, macro_key,
status_text, help_reference


Argument  Description  
first_version  The number of the earliest version of
FrontPage which should add this new command to the
menus. Values < 2 are treated as 2. Values greater
than the current running version of FrontPage tell
FrontPage not to create this command.
last_version  The number of the last version of FrontPage
which should add this new command to the menus. Values
less than the current running version of FrontPage
tell FrontPage not to create this command. If omitted,
this argument is treated as being higher than the current
running version of FrontPage. Combined with first_version,
this argument allows you to create addins which are
tailored to work only with specific versions of FrontPage.
menu_bar_num  Number of the built-in menu bar to which
you want to add the menu. This field is ignored as
there is currently only one set of menus in the Explorer,
but the field value should be set to 1 to allow for
future expansion.
menu_name  Name or number (1-based) of the menu on which
to insert the new command. If the number or name does
not exist or the argument is omitted, then the new
command is placed on the Tools menu.
command_name  Name of the new command. If a separator
is to be added then the command name is a single dash
character "-". If a separator is added then the only
remaining argument after command_name that is significant
is the command_position argument; the other arguments
are ignored. The menu accelerator is indicated by an
ampersand character preceeding the accelerator key,
e.g. "My &Addin".
command_line  Fully specified file name and path to
the executable file that should be run when the user
chooses this command in the FrontPage Explorer.
command_position  Position of the command on the menu.
This may be the name of the command before which you
want to place the new command, or a 1-based number
indicating the command's position on the menu counting
from the top of the menu (separators are counted).
If the name or position does not exist or the argument
is omitted, the command appears at the end of the menu.
insert_flag  Determines whether to insert the file pointed
to by command_line or to execute it. For the Explorer,
the command_line is always executed and the value of
this field must be 0. In the Editor, see the table
below.
status_text  Message to be displayed in the status bar
when the command is selected.
help_reference  Filename and topic number for a custom
Help topic for the command, separated by an exclamation
point. If you have no help topic to refer to, just
use 1000, which will launch the top level topic of
the FrontPage help file.
Example: command1 = 2,2,1, Site, &View Server Log,
c:\utils\logview.exe,, 0, Displays detailed information
about the web site from the info in the server log.,
logview.hlp!103
Example: command2 = 2, 2, 1, Site, &Reset Server Log,
c:\utils\logview.exe,,0, "Empties and resets the web
site's server log.", logview.hlp!104
Example: command3 = 2, 2, 1, Site,-,,Reset Server Log
Command1 adds the View Server Log command to the end
of the Site menu. Command2 adds the Reset Server Log
command to the end of the Site menu. Command3 adds
a separator between the two items, before the Reset
Server Log item. The commands will be processed in
the order 1, 2, and then 3.
The separator between elements is always a comma regardless
of the international version of FrontPage and/or the
system settings for list separator. White space after
the commas is optional, but white space within a field
is significant and is preserved, allowing for spaces
in menu item names, for example "Bullets and Numbering".
Commas within a field can be specified by enclosing
the field in double quotes (" ").
When comparing menu name strings for the command_position
and menu_name arguments, accelerators in the menu names
are ignored.
Customizing the FrontPage Editor
The HKEY_CURRENT_USER\Software\Microsoft\FrontPage\Editor\Init
Menus key has individual string values that specify
each custom menu. Note that this key is independent
of the version of FrontPage.
HKEY_CURRENT_USER\Software\Microsoft\FrontPage\Editor\Init
Commands key has individual string values that specify
each custom command. Note that this key is independent
of the version of FrontPage.
The syntax for the strings are identical to those used
for FrontPage Explorer extensions. However, the Editor
respects some of the settings which are ignored (and
required to be a fixed value) by the Explorer. Specifically:
menu_bar_num argument is used for both adding new menus
and commands. Legal values are 0 - empty document menu;
and 1 - active document menu.
insert_flag determines what action to take when the
custom menu item is picked by the user. The possible
values are:

0 Execute the command_line argument as an exe program
file.
1 Insert the file pointed to by the command_line
argument as HTML text. The file is inserted with paragraph
breaks before and after.
2 Insert the literal text
contained in the command_line argument as HTML. The
text is inserted without paragraph breaks before and
after, i.e. it is inserted directly inline.
The insert_flag
argument must be 0 if menu_bar_num is set to zero,
since there is no way to insert text into a non-existent
document.
Some examples of using insert_flag with the FrontPage
Editor are:
command1 = 2, 2, 1, Insert, Blin&king Text, "<blink>This
text is blinking</blink>",Marquee, 2, "Inserts blinking
text.", random.hlp!106
command2 = 2, 2, 1, Insert, Microsoft E&xcel Table,
C:\MSOffice\Excel\Library\xlfptabl.htm, Blinking Text,
1, "Inserts a table into an Microsoft Excel Internet
Assistant HTML template.", xlia.hlp!504

Designer HTML
Designer HTML is the term we use to describe an important
new extension to the FrontPage HTML Markup component.
In FrontPage, you could always insert pieces of HTML
into a page, even when FrontPage could not recognize
those HTML tags (e.g., new HTML tags that were invented
after the latest version of FrontPage, or authoring
tool-specific tags that are often used in a pre-processing
step before producing output HTML.) This appeared in
the FrontPage Editor as an "unknown HTML" icon. 

With Designer HTML, developers get two key pieces of
new functionality in FrontPage:

The ability to specify an alternate display in the
Editor for a piece of unknown HTML
The ability to insert, or drag and drop pieces of unknown
HTML into the Editor

Combined with menu customization, these two features
provide a powerful, well-integrated HTML extensibility
mechanism which is WYSIWYG and entirely code free.

This chapter describes the extensions we've made to
our WEBBOT pseudo-tag that allows for alternate representations
of the underlying HTML, when it's displayed in the
FrontPage Editor. We'll also offer several examples
which show off the power and elegance of this HTML
extensibility design.
Some Examples
To make the power of Designer HTML a bit more clear,
consider these scenarios:
A web database connectivity tool includes Designer
HTML files with their product, so that customers can
use the FrontPage authoring environment to create the
pages that connect to their database product. This
means that the web database vendor doesn't have to
worry about creating a great WYSIWYG HTML editor. They
can focus on the database side of the equation, which
is what they do best. (e.g., Cold Fusion, Spider.)
A commercial productivity application includes a utility
to convert proprietary document formats into HTML.
Although this data is generated dynamically by the
application, they would like to make it easy to fit
the legacy document information into a nicely designed
web page. To do this in an automated fashion they have
created their own "special" HTML tags that only their
conversion tools knows about. This lets them use these
HTML files with "special" tags as templates that can
be filled in by the conversion process. However, they
have no authoring tool for these "special" HTML tags
because they just invented them, and they're not standard.
The solution? They ship some Designer HTML files with
their product that integrate with FrontPage, allowing
their customers to use FrontPage as a WYSIWYG editing
environment for their template files with "special"
HTML in them. The user sees a cleanly designed graphic
representation of this "special" HTML, and they can
edit it, or drag and drop it just like any other pieces
of the Web page. (e.g., Microsoft Excel Internet Assistant,
Microsoft Access Internet Assitant.)
A small startup creates a pack of pre-defined JavaScripts,
Java applets, or ActiveX Conrols. Along with these
pieces, they ship Designer HTML files which allow their
users to simply drag and drop pre-defined components
with all of their properties pre-set. For instance,
rather than just inserting a push button into a form
field, they could easily insert an ActiveX push button
control, with color, font, and text display properties
already set, complete with JavaScript code attached
for processing the form.

There are many more exciting integration opportunities
available with Designer HTML, but this gives you some
idea of the range of possibilities. You should also
investigate the sample files in the Designer HTML folder
in the SDK, and the sample files that ship with FrontPage
itself. These offer some very specific examples of
what is possible.

How WEBBOT Syntax Works
Designer HTML is built on the foundation of the WEBBOT
pseudo-tag that we have used since FrontPage 1.0 to
implement our FrontPage components. This specially
formed WEBBOT tag is placed inside of an HTML comment
tag, so that web browsers simply ignore the information
contained in the pseudo-tag, while the FrontPage Editor
can parse the WEBBOT comment tag and use the information
to provide a WYSIWYG authoring environment for that
portion of the HTML.
Spanning WEBBOT syntax takes the syntax we used for
a few WebBot components in FrontPage 1.1, and uses
this syntax for all FrontPage components in FrontPage
97 and FrontPage 98. We use the <!-- WEBBOT StartSpan
--> syntax for starting the component's declaration,
and we add a <!--WEBBOT EndSpan --> closing tag. This
allows us to put our special WebBot attributes inside
the comment, while also producing HTML that is readable
by any browser.
Attributes on the WEBBOT Pseudo-Tag
To let the user specify the display characteristics
of a block of unknown HTML in the FrontPage Editor,
we have three attributes on the WEBBOT pseudo-tag.
They are only valid when the StartSpan attribute is
also specified (can't use with EndSpan.) Also, when
using Designer HTML, the BOT attribute is always set
to "HTMLMarkup". The new attributes are:
U-SRC=filename  Points to an image file to use to display
the unknown HTML block in the FrontPage Editor. If
the image is a file: URL on the local machine then
it will be automatically included into the web and
the URL adjusted to point to the version contained
in the web.
Only image files are allowed for the U-SRC tag. Included
HTML is not allowed. If text is needed for display
then it should either be encoded into the image or
the ALT attribute should be used instead of the U-SRC
attribute.
ALT=text  Limited HTML text to show inside a rectangle
in the FrontPage Editor as the display for the unknown
HTML block. If both U-SRC and ALT are specified, then
U-SRC is used in preference to ALT. Typically, however,
only one or the other would be specified. The set of
allowed HTML tags in the ALT attribute is detailed
below.
TAG=text  An optional attribute which specifies the
tag level that the ALT attribute should be entered
as. You can specify any block-like HTML tag name (without
< > brackets) that is beneath the BODY tag. For instance,
to have the HTML entered into the document at the level
of a <p> paragraph tag, use TAG=p. Or to make it a
heading, use TAG=h1. If omitted, it is inserted as
a text/character-level tag.
Here's an example:

<!--WEBBOT bot="HTMLMarkup" ALT= "<Font Size=+3><I>Foobar
ISV Feature Placeholder</I></FONT>" StartSpan -->

[## amazingly ugly ISV syntax that either a server
pre-processor knows, or that a new version of some
web browser knows, but FrontPage doesn't ##]

<!--WEBBOT bot="HTMLMarkup" EndSpan -->

In this case the ALT attribute is specified for a simple
textual display of the unknown HTML.
Valid HTML tag subset for ALT attribute text
The set of tags usable in the ALT text is basically
the set of tags that are for character formatting,
or those tags that generate objects that appear inline
with text. Tags that cause paragraph breaks or are
for paragraph formatting are not allowed.
The set of available tags is:
SUP, SUB
BIG, SMALL, FONT, B, CITE, CODE, DFN, EM, I, KBD, SAMP,
STRIKE, STRONG, TT, U, VAR, BLINK, MARQUEE
BR, IMG, A, OPTION, MAP, SELECT, INPUT, TEXTAREA, AREA,
OBJECT, EMBED, APPLET

Appearance of Designer HTML Representation in the Editor
Designer HTML appears either as an inline image or
as inline text, depending on whether the ALT or U-SRC
attributes are used for the WEBBOT pseudo-tag. If U
SRC is used, the pointed-to image is rendered at the
full image dimensions. If ALT is used then the marked
up and possibly formatted HTML text is rendered inline
with no additional visual embellishments.
The mouse pointer is changed to the standard WebBot
cursor whenever the cursor is moving or hovering over
the Designer HTML image or text.
Selection in the editor treats the Designer HTML as
a single unit to make it easy to move this unknown
HTML around the page via the standard editing operations.
If you want to edit the ugly unknown HTML tags that
are carried around by the WYSIWYG representation in
the Editor, then you can just double-click to get an
editing dialog.
Inserting an Extension File and Importing Images
There are three main ways to get these extensions into
FrontPage:
Copy and Paste of the HTML (described in a section
below)
Insert File
Drag and drop

FP supports both CF_HTML and CF_TEXT formats. There
is no attempt to ever turn CF_TEXT into HTML or vice
versa. Drag and drop operations work just like their
copy and paste equivalents. FrontPage allows you to
drop in text itself, or text and HTML files. Just drop
the files you create onto the web page and they are
automatically handled - a no-coding extensibility solution!


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:

Template Type Creates Location
Page a single page [FrontPageRoot]\pages
Web several
interconnected pages [FrontPageRoot]\webs
Frameset a
frameset pages [FrontPageRoot]\frames

The designation "[FrontPageRoot]" refers to the top
level directory where you installed FrontPage, such
as "C:\Program Files\Microsoft FrontPage".

The following section describes the easiest way to
create a page template, a web template, and a frameset
template, and then gives the technical details of how
they work for a deeper understanding of FrontPage templates.
Creating Page Templates

Page templates can be easily created by end-users.
In the FrontPage Editor, choose the "Save As" item
on the File menu, and then click on the "As Template"
button. Fill in the information, press OK, and a complete
page template is automatically created.

Creating Web Templates

The FrontPage SDK includes a Visual Basic program called
Web Template Maker that automates the process of creating
a web template when used with the FrontPage Personal
Web Server. The Web Template Maker will not work unmodified
with other kinds of web servers. To use the Web Template
Maker, follow these steps:
Launch the Web Template Maker (webtmpl.exe in the utility\webtmp
l
folder)
Select from the Available Webs list
Enter the New Web Template information
Press the Make Web Template button

Manually Creating Web Templates

This section describes the steps need to create web
templates with FrontPage. This procedure will create
a web template called Sample:

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.
Use the Windows Explorer to locate the folder containing
the web's content. By default, this is a folder 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".
Using the Windows Explorer, create a folder called
Sample.tem under the Webs folder of where the FrontPage
client is installed. By default this is would be the
"C:\Program Files\Microsoft FrontPage\Webs" folder.
Copy the web's images folder (if any) 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 the Windows Explorer, be sure to hold down the
CTRL key when doing the copy, or else the folder will
be moved, not copied.
Copy the web's pages in the main web directory ("C:\FrontPage
Webs\Content\Test") into Sample.tem. Do not copy access
control files, such as #haccess.ctl.
Using NotePad, create a file called Sample.inf, in
the Sample.tem folder.
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.
If you have any content in the web directory _private,
repeat the above steps, copying the pages to the same
subfolder (_private) in the web template.
If your web includes any content in the pre-defined
subfolders (images or _private), you will need to create
a [FileList] section in the Sample.inf file as described
above, in order to make sure those files get uploaded
properly by the FrontPage Explorer.

The FrontPage Explorer will not create new web sub
folders when loading web templates. To create deep
webs from existing content, use the Import Web Wizard,
or simply drag and drop a folder from the Windows Explorer
or desktop onto the appropriate folder in the FrontPage
Explorer's folder view.
Frameset Templates

A frameset 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. Previous
versions of FrontPage included a separate Frames Wizard
for creating and editing HTML framesets. In FrontPage
98, frames documents can be edited in-place directly
with the FrontPage Editor. 

Frameset templates can be easily created by end-users.
In the FrontPage Editor, create a frameset layout,
choose the "Save As" item on the File menu, and then
click on the "As Template" button. Fill in the information,
press OK, and a complete frameset template is automatically
created.

The FrontPage Editor allows authors to choose among
several frameset templates when creating new pages.
These templates are stored in the FrontPage "frames"
directory (c:\Program Files\Microsoft FrontPage\frames\
by default). 

The structure of the frameset template directories
mirrors the structure of the page and web template
directories. Each frameset template has a ".tem" extension,
and contains an INF file and an HTML file. The INF
file contains a special key called "layout" that fully
specifies the frameset geometry:

[info]
title=name of frameset as it will appear in the New
Page dialog
description=long description of the purpose of the
frameset
layout=specification of frameset geometry using compact
notation

The main purpose of the layout string is to display
a miniature preview of the frameset alongside the frameset's
title and description strings in the FrontPage Editor's
New Page dialog. 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 Template Directory

A page or web or frameset 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 or frames 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 3.0]
FrontPageRoot=C:\Microsoft FrontPage

The INF File

It is important to have a meaningful title and description
for a page or web or frames template, since a list
of wizards and templates could be quite large. This
information is kept in an INF file 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 is in standard Windows 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.

There can be other keys depending on the template type.
For example, a frames template should have a "layout"
key as described above. 

In FrontPage 98, a web template can have two new keys
in the info section: "theme" and "border". The theme
key can contain the name of an installed theme along
with its parameters (Vivid Colors, Active Graphics,
Image Background) specified as a 3-digit number. For
example, "theme=citrus 101" means that the template
will use the Citrus theme with Vivid Colors and an
Image Background. The border key can contains one or
more letter from the string "tlrb" (TLRB), where the
letters represent the four possible borders a page
can have: top, left, right, and bottom. If these keys
are present, the specified theme and borders will be
applied to the web after the pages have been uploaded.

Web templates can also specify three optional sections
that are used by the FrontPage Explorer when loading
web templates: [FileList], [MetaInfo], and [TaskList].
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.


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. You must use forward
slashes when specifying these directories in URLs.


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 Component, to 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. Names beginning
with vti_ are reserved 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:

TaskName
Priority (1 to 3)
CreatedBy
URL
Cookie
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 few words 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.

Home Page Management

If you include a home page in your web template, the
FrontPage Explorer will perform some special handling
for the URL. 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://example.microsoft.com"
or "http://www.microsoft.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 to
the correct index name for your web server. On a CERN
server, this might resolve to the name Welcome.html.
On a Microsoft Internet Information Server, this might
resolve to Default.htm.

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, all links in
the web that refer to index.htm will be rewritten to
refer to the correct home page name. You should not
use the special link ./ (dot-slash) in web templates
to refer to the home page, because a browser can only
follow that link for pages fetched from a Web server.

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 3.0]
FrontPageRoot=C:\Program Files\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:\Program Files\Microsoft FrontPage

In FrontPage 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 determine the FrontPageRoot setting from
the FrontPage 3.0 section, and then append the directory
"webs" for web wizards and templates, or "pages" for
page wizards and templates. 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:\Program Files\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 FrontPage web rather than adding to the current
one, 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

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.
If a page wizard is launched with Blocking=1, it must
not make any OLE automation calls to the FrontPage
Editor or it will hang. Finally, if a wizard is run
with Editing=1, it should delete the PageFile when
it exists, since this is a temporary file created by
the FrontPage Explorer.

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

Destination=editor | web | disk
PageURL=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). However, if the
custom wizard creates any non-HTML files, then it must
upload them to the web by itself, rather than returning
it locally on the hard drive (even when the INF file
it receives has a destination of disk.)

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 compatibility, the following arguments
are still passed to wizards by the FrontPage Explorer:
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
to UrlN. 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:\Program Files\Microsoft FrontPage\pages\vtiform.wiz
Inf=E:\Program Files\Microsoft FrontPage\pages\vtiform.wiz\vtifo
rm.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=jdoe
windir=E:\WINNT35
[Output]
Wizards vs. Editors

Page wizards can be used to both create and edit files
of a particular type in FrontPage. It makes sense for
a wizard to be both a generator and editor of a file
type if the documents will contain information which
is not directly editable by FrontPage or another program.

To register a program as an editor for a file type,
use the FrontPage Explorer's Tools : Options : Configure
Editors dialog. This information is stored in the file
fpexplor.ini in the Windows directory, in a section
called [Editors]. Each line is of the form:

  Extension=EditorName,EditorPath,AutoImportFlag

Extension is a file extension without the dot, such
as "idc". EditorName is what the user sees, such as
Database Connector Wizard. EditorPath is the absolute
path to the editor program. AutoImportFlag is 0 if
the program will use OLE automation calls to save the
page to the current web (such as a typical wizard does),
or 1 if the edited page file should be auto-imported
by the FrontPage Explorer. Files are auto-imported
when the FrontPage Explorer window is activated and
the timestamp of the file being edited has changed.

The Explorer will launch a normal editing program with
a single argument: a path to the temporary file that
is to be edited. A wizard program that is invoked as
an editor will be launched with the path to a temporary
file containing its input arguments, as described in
the previous section. In this case the argument Editing
is set to 1, and PageFile is set to the path of the
temporary file being edited, which has just been download
by the FrontPage Explorer. The wizard should delete
the PageFile when it exits if Editing is set to 1.

As mentioned earlier, a page wizard's INF file should
contain the key/value "editor=1" if it can be launched
as an editor.
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 temp subdirectory of the FrontPage installation
directory. This is a change from the FrontPage 1.1
SDK, which suggested that settings files be saved in
the data subdirectory. 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 3.0" 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.
International Output

A wizard should always generate its HTML using the
correct code page for the desired language. In addition,
all wizards should place a META tag containing the
correct charset designation as the first element inside
the HEAD section of each page, before the TITLE tag:

  <HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html;
charset=iso-8859-1">
<TITLE>My Page Title</TITLE>
</HEAD>
<BODY>
</BODY>
</HTML>
FrontPage Interactions

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


Themes

FrontPage 98 themes define elements and settings for
the following categories:

Colors (text, headings, backgrounds, table borders,
and links)
Graphics (bullets, banners, navigation icons, navigation
bar buttons, horizontal lines)

A theme does not define the location of navigation
bars, the layout of a page, the template used in a
page, or the structure of a web. These are all different
features that work closely together but are not specifically
part of a theme.

Themes are selected and applied using either the FrontPage
Explorer's Themes view or in the FrontPage Editor's
Format: Theme command. Both the view and the command
have the same user interface, but they behave somewhat
differently. Specifically, if you apply a theme in
the FrontPage Explorer, you are applying it to all
the pages in the current FrontPage web. If you apply
a theme in the FrontPage Editor, you are applying it
to the active page only.

In the FrontPage Explorer's Themes view, themes are
selected, previewed and applied as entire sets in a
Word Style Gallery-like interface, with a left column
of names and a right preview column. This selection
interface works as one would expect; selecting a theme
from the list at left refreshes the preview pane at
right. Clicking Apply applies the theme to the current
FrontPage web or active page, depending on whether
you are in the FrontPage Explorer or the FrontPage
Editor.

The three checkboxes below the theme list are an important
part of the feature. One of the limitations of themes
in similar applications is that they are not always
applicable enough to many Web sites. Themes that are
fun and informal, like a "Jungle" theme with vines
and bananas might look great the first time you see
them in the application, but they may not look that
great on your web page. Similarly, a large selection
of elegant, professional, yet bland and generic themes
will not look very exciting. FrontPage 98 bridges the
gap by allowing users to easily change the impact of
the theme by picking from three display options:

Vivid Colors
When this option is unchecked, a basic color scheme
for text, hyperlinks, and tables is used. Moderate
use of color will also be applied to hyperlinks and
headings. This is the type of color scheme could be
used for a more professional web page. Selecting the
Vivid Colors option will change the colors of the page,
text, headings, hyperlinks, and tables to something
more in line with the active graphics option (see below).
Depending on the theme applied, the colors will be
brighter and more defined, suitable for less formal
web pages.
Active Graphics
When this option is unchecked, the banners, bullets,
horizontal rules, and navigation bar buttons are all
very abstract, simple and elegant. These graphics will
be fast to download and suitable in most scenarios.
When the Active Graphics option is checked, a more
lively set of graphics is substituted. The banners,
bullets, and horizontal rules may be animated (depending
on the theme chosen), and the navigation bar buttons
become "hover buttons," which change appearance when
moused over and when clicked.
Background Image
Adding a background image to your web pages can have
a big impact on how busy the theme looks. All themes
include a background graphic with either a margin effect
or one that appears to cover the entire page. The Background
Image option toggles between the theme's supplied background
image and a solid background color.
Theme Elements

A theme is made up of settings in several categories:

General Settings - These are the settings which are
consistent throughout the theme
The name of the theme
The font for the body text and the font for the headings
The image for the top-level navigation bar buttons
The background image enabled by the "Background Image"
option

Basic Graphics - These are the theme elements applied
when the "Active Graphics" option is not selected
An image for the page header
A horizontal rule graphic
Three levels of GIF bullets
An image for the horizontal navigation bar button
An image for the vertical navigation bar button
An image for the Home, Next, Previous, and Up navigation
buttons

Active Graphics - These are the theme elements applied
when the "Active Graphics" option is selected
An image for the page header (which may be animated)
A horizontal rule graphic (which may be animated)
Three levels of GIF bullets (which may be animated)
Three images for the horizontal navigation bar buttons,
to create a hover button (normal, hovered, pressed)
Three images for the vertical navigation bar buttons,
to create a hover button (normal, hovered, pressed)
Three images for the Home, Next, Previous, and Up navigation
buttons, to create a hover button (normal, hovered,
pressed)

Basic Colors - These are the colors applied when the
"Vivid Colors" option is not selected
Default text color - usually dark or black
Colors for active, normal and visited hyperlinks
Colors for 3D table borders - usually automatic/gray
Page background color - usually very light or white

Vivid Colors - These are the colors applied when the
"Vivid Colors" option is selected
Default text color
Colors for active, normal and visited hyperlinks
Colors for 3D table borders
Page background color

Theme images are the same size in all themes. This
allows the user to switch the themes without affecting
the layout of the page.


Here is an example of what the same page might look
like in two different themes:






Anatomy of a Theme

The illustration below shows a typical collection of
theme elements; however, the various buttons for navigation
bars contained in a theme are not always immediately
evident. A FrontPage theme can contain up to four different
kinds of navigation bar buttons.



The horizontal and vertical navigation buttons do not
necessarily have to be different for a single theme.
The Home, Next, Previous, and Up navigation buttons
(not shown above) are designed to be used within the
body text, in the page header, or in the page footer.

Global navigation buttons usually appear on the home
page of a Web site. These buttons should be simple
for clarity and fast downloading.

Theme Settings
Fonts
Unlike in a word processor such as Microsoft Word,
you cannot specify fonts in point sizes in the HTML
language. There are only seven settings, and they are
controlled by the Web browser, not by the author of
the page. By default the settings correspond to the
following table:

Value Meaning Example Used in





"normal" default size


1 8pt Text Heading
6
2 10pt Text Heading 5
3 12pt Text Heading 4
4 14pt Text Heading
3
5 18pt Text Heading 2
6 24pt Text Heading 1
7 36pt Text



When selecting a font for a theme, the typeface used
needs to be relatively universal. A font that most
people won't have installed on their system will make
a poor choice for a theme. This means that, other than
the normal Windows system fonts Arial, Times New Roman
and Courier New, you should assume that not all users
will have the font you chose for your theme. In that
case, a substitution font is used. Whenever selecting
a font for the body or for the headers, you should
also specify which font(s) you would like to display
if the first choice isn't available on the user's system.
To specify the alternate font(s) you use a comma and
the second (and third) name. For example:

Verdana, Arial, Helvetica

would specify the Verdana font as the intended choice
for the theme. If Verdana is not installed on the user's
system, the Arial font is used. Since Verdana and Arial
are Windows fonts, you may want to specify a third
choice for other platforms, such as Helvetica, which
is standard on Macintosh computers.


The list of primary fonts from which to choose should
be kept to those that ship with Microsoft FrontPage.
These are:

Arial
Arial Black
Arial Narrow
Arial Rounded MT Bold
Book Antiqua
Bookman Old Style
Brush Script MT Italic
Century Gothic
Century Schoolbook
Comic Sans MS
Courier New
Garamond
Georgia
Haettenschweiler
Impact
Times New Roman
Trebuchet MS
Verdana


Default Font Substitutions

When themed pages are viewed on different browsers
and platforms, the specified fonts may not be available.
The FrontPage themes specify fonts in order of preference
so that they degrade gracefully in such situations,
as illustrated in the following table.

Theme Font
Font Substitution Order




Arial
Arial, Helvetica
Arial
Black
Arial Black, Arial, Helvetica
Arial Rounded MT
Bold
Arial Rounded MT Bold, Arial, Helvetica
Book Antiqua
Book
Antiqua, Times New Roman, Times
Bookman Old Style
Bookman
Old Style, Times New Roman, Times
Brush Script MT
Brush
Script MT, Arial, Helvetica
Century Gothic
Century
Gothic, Arial, Helvetica
Century Schoolbook
Century
Schoolbook, Times New Roman, Times
Comic Sans MS
Comic
Sans MS, Arial, Helvetica
Garamond
Garamond, Times
New Roman, Times
Haettenschweiler
Haettenschweiler,
Arial, Helvetica
Impact
Impact, Arial, Helvetica
Times
New Roman
Times New Roman, Times
Trebuchet MS
Trebuchet
MS, Arial, Helvetica
Verdana
Verdana, Arial, Helvetica


The graphics are what really makes these themes come
to life. The quality of the graphical banners and buttons
is the most important part of a theme. Consider the
following when designing a theme:

Choose a set of colors that go well together but do
not overwhelm
Use a set of basic graphics which are not too theme
specific and can thus be used on almost any page
Integrate a set of active graphics that are lively
and fun, but not annoying


The example below shows what a typical theme looks
like:



What makes this theme a good choice is the use of the
leaves concept. It is present throughout the theme
in the pictures and colors, but it is subtle enough
that the page does not become applicable only to botanists.
Text Overlays
None of the graphics specified in a theme should have
text placed on them by default. FrontPage will add
text to these graphics as needed. For example, the
"Home" button will need to have a specified font, color,
and alignment, but the word "Home" should not actually
be placed on the graphic. The text is added at page
save time because the page names and language of the
text will vary depending on the Web site.

When defining a graphic that has text on it, such as
the banner, the following must be specified:

The font for the text 
The color of the text 
The horizontal alignment of the text 
The vertical alignment of the text 

Theme images that can have text overlays must be saved
in the GIF format.
Transparency
The sizes for each of the graphics are specified by
the theme. To design a button, bullet or banner that
is smaller than this size, use transparent pixels to
pad the image out to the specified size. Keeping all
the images the same size is important because switching
themes should not affect the pagination and layout
of an HTML page.

Navigation bar buttons of all types (top-level, horizontal,
and vertical) stack adjacent to each other; the edges
touch. To have the buttons appear with some space between
them, transparent padding can be used in the images.
Active Graphics (Animations & Hover Buttons)
Active Graphics take two forms. The GIFs that can be
animated, and the hover buttons. Animations should
be used sparingly to subtly convey the sense of a lively
page, but not a loud and busy TV channel. For the GIFs
that can be animated (banners, horizontal rules, bullets)
only a one or two images per theme should be animated.
The image format to be used is the GIF89a specification.

In order to define a hover button, you need to define
the text properties just like you would for a normal
button. However, instead of specifying just one button
image, you specify three. One button image is used
for the normal state of the button, the second image
is used when the mouse hovers over the button, and
the third image is used when the button is clicked
and when the user reaches the page that the button
pointed to. The effect of a "pushed" button is not
necessarily a three-dimensional effect.
Anti-aliasing
If graphics are anti-aliased (smoothed), it is important
to make sure they look good on both of the background
colors as well as on the textured background. The color
palette used for the anti-aliasing pixels in the image
should closely match the color palette used for the
background image or background colors. For example,
an image that has been anti-aliased for a light or
white background will look poor on a dark or black
background.
Color Palette
All colors specified should be in the 216-color safe
palette for Internet Explorer and Netscape Navigator
Web browsers. These are the colors resulting from all
RGB (Red/Green/Blue) combinations of 0, 51, 102, 153,
204, and 255. For table border colors, there are two
settings required to create the 3D beveled effect -
a light color and a dark color.
Theme INF Files
There are two files with the extension INF that control
the properties and handling of a theme. Each theme
has a theme-specific file <theme>.inf which contains
directives applying just to that theme. In addition,
the top-level file themes.inf contains directives which
apply to all themes installed on a computer, or stored
on a server. Directives in the theme-specific file
override directives in the top-level file.
Theme-Specific INF File
The theme-specific INF file contains the following
information:

Section Name: [info]

title The display name of the
theme.
codepage The Windows codepage of this file and
specifically the characters in the above display name.
version The
version of this theme. This version number controls
whether or not a copy of a theme will overwrite another
as themes are propagated between machines.
readonly Prevents
the Themes Designer from overwriting this theme.

For example, the contents of the arcs.inf file is:

[info]
title=Arcs
codepage=1252
version=01.01
readonly=true

Font Handling and Themes.inf 
FrontPage themes specify which fonts to use for different
portions of the author's web page. These fonts are
assumed by FrontPage to be fonts to apply to web pages
stored in the windows-1252 charset. The themes.inf
file is used to specify how a font should be handled
when web pages are stored in different charsets.

Section Name: [Fonts]

<charset>,<font1>=<font1> Directs
FrontPage to use <font1> "as is" when applying a theme
to web pages stored in the specified charset.
<charset>,<font1>=<font2> Directs
FrontPage to use <font2> in place of <font1>, when
applying a theme to web pages stored in the specified
charset.
<charset1>=<charset2> Directs FrontPage to
apply all the font directives for <charset2> to <charset1>.

When FrontPage applies a theme to a web page, and no
specification is available for the charset and font
combination, FrontPage will output no font information.
The absence of font information will allow the browser
to use a default font when displaying the web page.

No directives are required for the charset windows
1252. FrontPage will use the fonts exactly as specified
in the theme.

Section Name: [Families]

<font>=<pitch>,<family> Describes
the font pitch and family attributes. This information
is used when creating text labels to overlay on theme
graphics, such as buttons and banners.

Acceptable values for <pitch> are "variable" or "fixed."
Acceptable values for <family> are as follows:

Font Family Description
Decorative Novelty fonts. Old
English is an example.
Modern Fonts with constant stroke
width (fixed-pitch), with or without serifs. Fixed
pitch fonts are usually modern. Pica, Elite, and Courier
New are examples.
Roman Fonts with variable stroke
width (proportionally spaced) and with serifs. MS Serif
is an example.
Script Fonts designed to look like handwriting.
Script and Cursive are examples.
Swiss Fonts with variable
stroke width (proportionally spaced) and without serifs.
MS Sans Serif is an example.

This information allows FrontPage to provide a reasonable
alternative font when the author does not have the
specified font installed on their machine.

Important:: This font handling system is designed to
avoid applying fonts to inappropriate charsets. If
a new theme is created that uses a font not shipped
with FrontPage, directives for that new font should
be added to the theme's INF files before the new theme
is applied to any charsets besides windows-1252. Alternatively,
these directives could appear in the global themes.inf
file.


The FrontPage Theme Designer

FrontPage 98 ships with over 50 professionally designed
themes that can be applied to your Web site using the
FrontPage Explorer's Themes view. By design, the appearance
and properties of a theme's individual elements cannot
be modified in the FrontPage Editor by the user. However,
you can easily modify or customize a theme using the
FrontPage Theme Designer, a tool that is included on
the FrontPage 98 CD-ROM.
Setup
To install the Theme Designer, exit the FrontPage Explorer
and the FrontPage Editor (if they are running) and
run tdsetup.exe from the \SDK\THEMES\DESIGNER folder
on the FrontPage 98 CD-ROM. After Setup has completed,
launch the FrontPage Explorer. To start the Theme Designer,
choose the Show Theme Designer command from the FrontPage
Explorer's Tools menu. 

The Theme Designer setup program tdsetup.exe also installs
another utility: the FrontPage Theme Verifier. The
program thmveras.exe can be found in the \bin directory
under the FrontPage installation directory. This utility
can be used to verify that the custom themes you create
meet the basic requirements to work well with FrontPage.

The Theme Verifier is most useful if you are going
to create themes without the help of the Theme Designer.
It analyzes one or more theme directories and creates
a report that can be saved and printed.
Designing a New Theme
The easiest way to begin work on a new or customized
theme is to open an existing one. From the Theme Designer's
File menu, choose Open Theme to select a theme from
a list of installed themes (for example, "Network Blitz").
This list matches the installed themes available in
the FrontPage Explorer's Themes view. You can also
choose the New Theme command, which opens a generic
theme that you can then customize.




Unlike the FrontPage Explorer's Themes view, which
only shows partial theme elements, the Theme Designer
window shows all of a theme's design elements, including:

Theme Name
Banner
Top-level navigation buttons
Horizontal navigation buttons
Vertical navigation buttons
Body text
Regular Hyperlink Text
Active Hyperlink Text
Followed Hyperlink Text
Horizontal Rule
Table border colors
Headings
Navigation buttons for Home, Up, Previous, and Next
pages
Horizontal alignment of elements
Vertical alignment of elements

When you mouse over any theme element, the mouse pointer
changes into a hand and the element's name is displayed
on the status bar. Double-clicking a theme element
opens the properties sheet for that element, where
you can make changes to its properties and view a dynamic
preview of your changes. You can also right-click a
theme element in the inital Theme Designer application
window and choose display and property options from
the shortcut menu.
Display Options
Using the Theme Designer, you can display and change
the appearance of elements when the Vivid Colors, Active
Graphics, and Background Image options are selected
in the FrontPage Explorer's Themes view. To do this,
select the desired combination of the V, A, and B buttons
on the toolbar before making changes to an element.
You can also select the appropriate display option(s)
from the Theme Designer's View menu.
Dynamic Properties
While viewing or changing the properties of a theme
element, you can preview the element in its dialog
box. Properties tabs that accept input of a file path
(for example, the location of an image), you can drag
and drop the file over the dialog box and the Theme
Designer will fill in the complete path to the file.

Saving a New or Modified Theme
When you have finished creating a new theme or editing
an existing one, choose the Save As command on the
File menu to save the theme as a new theme, or choose
the Save command to overwrite the original theme with
your changes. Note that you cannot overwrite the original
FrontPage 98 themes that were shipped on your FrontPage
98 CD-ROM. These themes are read only.

If the FrontPage web you want the new theme applied
to was open in the FrontPage Explorer when you edited
and saved the theme in the Theme Designer, the changes
will be applied automatically. However, if the web
was not open when you saved changes in the Theme Designer,
it will be necessary to re-apply the new theme to the
FrontPage web. As with any changes to your FrontPage
web, if your FrontPage web is published on a remote
Web server, you must re-publish the web before the
theme's design changes will be visible to visitors
to your site.
Applying Custom Themes
The Theme Designer saves your newly completed or updated
theme into the FrontPage 98 installation on your computer
where it is available for use by the FrontPage Explorer
and FrontPage Editor. However, the Theme Designer will
not modify any of your FrontPage webs. If you are modifying
an existing custom theme, your FrontPage webs using
previous versions of that custom theme will remain
unchanged.

To use your new or updated custom theme in a FrontPage
web, you must open that FrontPage web in the Explorer
and apply or re-apply the custom theme. If your custom
theme is only applied to selected pages instead of
the entire web, you must apply your custom theme to
at least one of the pages in the FrontPage web and
then recalculate hyperlinks. Repeat this procedure
for all the FrontPage webs on any workstations or Web
servers where you would like to use your custom theme.
Sharing Custom Themes with Other Users
You can easily share your new custom theme or updated
custom theme with other FrontPage 98 users. When a
FrontPage 98 user opens any FrontPage web that uses
your custom theme, the custom theme or new update is
automatically downloaded into the FrontPage 98 installation
on that user's computer, provided that the custom theme
was not present or merely an older version was available.

If you do not wish to grant a user permission to edit
your FrontPage web, you can create a new FrontPage
web specifically for the purpose of distributing your
custom theme. Users that download your custom theme
can then use your new or updated custom theme in a
FrontPage web by opening that FrontPage web in the
FrontPage Explorer and applying or re-applying the
custom theme.

NOTE:  If your custom theme is only applied to selected
pages instead of the entire FrontPage web, re-apply
your custom theme to at least one of the pages in the
FrontPage web and then recalculate hyperlinks. Repeat
this procedure for all the FrontPage webs on any workstations
or Web servers where you would like to use the custom
theme.

Because the distribution of custom themes occurs automatically,
it is important for FrontPage users working together
to give their custom themes different names in order
to avoid accidental overwriting.

OLE Automation Overview

IMPORTANT:  The OLE automation interfaces described
in this section apply to FrontPage 97 and FrontPage
98. There are a number of changes since FrontPage 1.1,
including new methods, and additional or changed arguments
to older methods. Your code should ensure at runtime
that you are running against the appropriate version
of FrontPage.

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.3.0),
the FrontPage Editor (FrontPage.Editor.3.0), and the
FrontPage To Do List (FrontPage.ToDoList.3.0). 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.

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.microsoft.com/myweb is a web
of interconnected documents all residing under the
directory myweb on the server www.microsoft.com. There
is also the Root Web on this server (accessed via the
URL http://www.microsoft.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 configuration
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. 

Operations exposed to automation 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. You can also insert files,
images, or HTML into the current page at the insertion
point.
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 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, we recommend the book 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 FrontPage, you may use the fully-specified
identifiers "FrontPage.Explorer.3.0", "FrontPage.Editor.3.0",
and "FrontPage.ToDoList.3.0". Alternatively, you may
prefer to use the generic identifiers "FrontPage.Explorer",
"FrontPage.Editor", and "FrontPage.ToDoList", but you
may get an incompatible interface in a future release
of FrontPage.

Important: These interfaces have changed since the
release of FrontPage 1.0, FrontPage 1.1, and FrontPage
97. They may 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",&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")
  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.

FrontPage Explorer Automation


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

  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);

The following automation methods were added for FrontPage
97:

BSTR vtiGetFoldersList(LPCTSTR pszParentFolderUrl);
BSTR vtiGetPagesInFolder(LPCTSTR pszFolderUrl, long
lType);
long vtiCreateFolder(LPCTSTR pszFolderUrl);
BOOL vtiOpenWebWithPassword(LPCTSTR pszServer, LPCTSTR
pszWebName, 
  LPCTSTR pszUser, LPCTSTR pszPassword);
BSTR vtiListWebs(LPCTSTR pszServer, LPCTSTR pszUser,
LPCTSTR pszPassword);
void vtiDisableErrorDialogs(BOOL bYesNo);
void vtiQuit();
long vtiPublishWeb(LPCTSTR pszServerUrl, LPCTSTR pszWebName,
long dwFlags, LPCTSTR pszUser, LPCTSTR pszPassword);
long vtiRemoveWebPages(LPCTSTR pszPageList);

The following automation methods were added for FrontPage
98:

long vtiRenameDocument(BSTR pszURL, BSTR pszNewURL,
boolean bUpdateBacklinks, boolean bIsFolder, 
boolean bCopy, boolean bForceOverwrite);
long vtiIsFeatureSupported(BSTR pszFeature);
BSTR vtiListThemes();
long vtiApplyTheme(BSTR pszName, long dParams, BSTR
fileList);
BSTR vtiGetTheme(BSTR pszThemeDirName, BSTR pszLocThemesDir);
long vtiPutTheme(BSTR pszThemeDirname, BSTR pszThemeVersion,
BSTR pszFileList, BSTR pszLocThemesDir);
long vtiPutWebStructure(BSTR pszModifications);
BSTR vtiGetWebStructureRelations(BSTR pszUrl, long
lRelationType);
BSTR vtiReturnDBWRoot(BSTR pszFileURL);
long vtiMakeThemeFresh(BSTR pszWebUrl, BSTR pszThemeName,
boolean bAllowUpload, boolean bAllowDownload);
boolean vtiSetCurrentView(long nViewID, boolean bTransferSelecti
on,
long nFlags);
boolean vtiIsFolderInWeb(BSTR pszFolderUrl);
boolean vtiSetFolderOptions(BSTR pszFolder, boolean
bExecutable, boolean bReadable);
boolean vtiRefreshThemeList();
boolean vtiSetEditor(BSTR szType,BSTR szName,BSTR szCommand);


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 Server Extension 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 dialog.

Users should typically call vtiRefreshWebFromServer
immediately after vtiCreateWeb to make sure the FrontPage
Explorer's views are in sync with the state of the
web on the server. Failure to do so may lead to problems
in subsequent calls.

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 designation for the web server. It
can include the file:// or http:// or https:// prefix.
If no prefix is provided, http:// is assumed. If a
file path like C:\webdir is provided, the file:// prefix
is assumed. Examples: "www.microsoft.com", "http://www.microsoft
.com:8080",
"C:\webdir".

WebName is the name of the new web you want to create.
This name must be a valid directory name in the target
web. Example: "myweb".


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,
or after a new web has been created with vtiCreateWeb.

NOTE: If the FrontPage Explorer has no open web, calling
this method may 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 FrontPage components 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 vtiPutDocument
s
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. Valid subdirectories
are "images" and "_private" or other user-created folders.
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 modifies 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 FrontPage Substitution component, 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. 

NOTE: If the FrontPage Explorer has no open web, calling
this method may 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:Microsoft\nf
ax:555
1212".


vtiSetWebRecalcDependencies


C++: void vtiSetWebRecalcDependencies(BOOL bRecalcOn);

VB: vtiSetWebRecalcDependencies(RecalcOn as Integer)


Description

This method turns dependency updating on or off in
the current web.

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 vtiSetWebRecalcD
ependencies
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 Hyperlinks 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. The
keys in FrontPage dictionaries are case-sensitive,
and all built-in keys are now all lower-case. Wizards
written for FrontPage 1.1 should be changed to always
use all lower-case when accessing built-in keys.

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-sensitive (prior to FrontPage
97, they were 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 1997 14:19:19 EDT"
  vti_timelastmodified   example: "02 Nov 1997 08:52:53
EST"
  vti_title     example: "Policies and Procedures"

The following are notes about particular keys:

The key vti_editor was new as of version 1.1. It is
used 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. If only the Folders view
has been active since the last refresh, FrontPage Explorer
will not have fetched the link information, because
it's expensive to do so and the folder view doesn't
use it. A possible workaround is to use the vtiSetCurrentView
call to change the current view to one that utilizes
the link information, such as the Hyperlinks view.
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 were
reserved, and the set of possible values for the first
two characters was expanded. Links appear in the same
order as they are found 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)

D referenced URL is a directory
(ending in '/'), but directory doesn't have a valid
welcome page (such as index.htm)




1: link type H link
is an HREF (in <A> construct)

L link is an imagemap
HREF

B link is a FrontPage component-generated HREF

C link
is a FrontPage Table of Contents 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 FrontPage
Include component)

T link is a text index (from FrontPage
Search component)

Y link is a style source page

F link
is a frame SRC attribute (in <FRAME> construct)

D link
is a data source, such as for script code

K link is
a bookmark

U link is of an unknown type




2: link security U unknown;
always set to 'U' in FrontPage 1.1

H HTTP protocol

S SSL
protocol

T SHTTP protocol




3: link method S static;
always set to 'S' in FrontPage 1.1

D dynamic; link
to page through SHTML program or library

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.
If the application was minimized, you may need to call
this method twice to make sure it is really on top.

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. If the returned URL is empty, the FrontPage Explorer
has no open web.

Return Value

Examples: "http://www.microsoft.com", "http://microsoft.com:8080
/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.

NOTE: If the FrontPage Explorer has no open web, calling
this method may 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".



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"

The keys in FrontPage dictionaries are case-sensitive,
and all built-in keys are now all lower-case. Wizards
written for FrontPage 1.1 should be changed to always
use all lower-case when accessing built-in keys. 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 and is not always present
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
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
vti_welcomenames 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.microsoft.com"
returns the page "http://www.microsoft.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(Type 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

Type defines which types of files to get back in the
list. The legal values are described below. The list
may be extended in the future to include other document
types.
Value File Type
0 All pages
1 HTML pages
2 Images (currently,
those with the extensions .GIF, .JPG, or .JPEG)
3 Video
files
4 Executable files
5 Sound files
6 Database files
7 HTX
files 
8 PowerPoint animation files
9 CDF files

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 FrontPage components 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 updating in the web
during the upload and turns it back 
on again when the upload completes. It will block 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. 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. It can
include a file:// or http:// or https:// prefix. If
no prefix is provided, http:// is assumed. If a file
path like C:\ is provided, the 
file:// prefix is assumed. Examples: "http://www.microsoft.com",

"http://microsoft:8080".

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.



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 registered
with the FrontPage Explorer. 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.microsoft.co
m/",
"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. The keys in FrontPage dictionaries
are case-sensitive, and all built-in keys are now all
lower-case. Wizards written for FrontPage 1.1 should
be changed to always use all lower-case 
when accessing built-in keys.

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. 

If the given URL is absolute (such as http://webserver/web/page.
htm),
the document will be fetched with an HTTP GET operation,
even if the document is in the current web. Otherwise,
if the URL is relative and in the current web, the
page will be fetched via the FrontPage Server Extensions.

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.microsoft.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".


vtiGetFoldersList


C++: BSTR vtiGetFoldersList(LPCTSTR pszParentFolderUrl);

VB: vtiGetFoldersList (ParentFolderUrl as String) as
String


Description

This method returns a newline-delimited list of folder
URLs that are contained inside of the specified parent
folder URL. Supply an empty string to get the list
of top-level folders.

Return Value

List of folder URLs.

Parameters

ParentFolderUrl designates the folder in which FrontPage
should look for subfolders.


vtiGetPagesInFolder


C++: BSTR vtiGetPagesInFolder(LPCTSTR pszFolderUrl,
long lType);

VB: vtiGetPagesInFolder (FolderURL as String, Type
as long) as String


Description

This method returns a newline-delimited list of page
titles and URLs, of the given type, that are found
in the named folder. Use this method as a general way
to access the list of files in a folder. Supply an
empty string to get the list of pages in the top-level
folder.

Return Value

A newline-delimited list of page titles and URLs. The
format is "title1\nURL1\ntitle2\nURL2\n".

Parameters

FolderUrl is a string containing the name of the folder
to look in for files.

Type is types of files to return in the list of files
in the folder. The legal values are the same as those
for vtiGetPageList, and are described below. The list
may be extended in the future to include other document
types.

Value File Type
0 All pages
1 HTML pages
2 Images (currently,
those with the extensions .GIF, .JPG, or .JPEG)
3 Video
files
4 Executable files
5 Sound files
6 Database files
7 HTX
files 
8 PowerPoint animation files
9 CDF files



vtiCreateFolder


C++: long vtiCreateFolder (LPCTSTR pszFolderUrl);

VB: vtiCreateFolder (FolderUrl as String) as Long


Description

This method creates a folder of the specified name.

Return Value

The return value is 1 is the call succeeds, and 0 if
it fails.

Parameters

FolderURL is a string that specifies the web-relative
URL of the folder to create. E.g. "myfolder". The folder
URL can specify only one level of folder which does
not already exist in the web.


vtiOpenWebWithPassword


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

VB: vtiOpenWebWithPassword (Server as String, WebName
as String, User as String, Password as String) as Integer


Description

Provides the same functionality as vtiOpenWeb, but
allows you to specify a password too. This is useful
for creating automated processes which make calls to
FrontPage and need to make unattended manipulations
of the web.

Return Value

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

Parameters

Server is the designation for the web server. It can
include a file:// or http:// or https:// prefix. If
no prefix is provided, http:// is assumed. If a file
path like C:\ is provided, the 
file:// prefix is assumed. Examples: "http://www.microsoft.com",

"http://microsoft:8080".

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.

Password is the password string for the specified user
account.

WARNING: As with any program that contains password
information, creating a program that uses vtiOpenWebWithPassword

( ) and specifies a Password string creates a potential
security hole unless you can protect against physical
access to the executable. This is because the executable
can be searched for the user account name and password
string parameter used in to the call to vtiOpenWebWithPassword.
Therefore, we recommend that you use this function
with caution.




vtiListWebs


C++: BSTR vtiListWebs(LPCTSTR pszServer, LPCTSTR pszUser,
LPCTSTR pszPassword);

VB: vtiListWebs (Server as String, User as String,
Password as String) as String


Description

Returns a newline-delimited list of FrontPage webs
present on the specified server.

Return Value

Newline-delimited list of FrontPage webs on the specified
server.

Parameters

Server is the designation for the web server. It can
include a file:// or http:// or https:// prefix. If
no prefix is provided, http:// is assumed. If a file
path like C:\ is provided, the 
file:// prefix is assumed. If you specify a protected
web server, then you'll need to provide the User name
and Password. Otherwise they can be left NULL. Examples:
"http://www.microsoft.com", "http://microsoft:8080".

User is the account name to use to log on to the web
site.

Password is the password for the specified User account
to log on to the web site.

WARNING: As with any program that contains password
information, creating a program that uses vtiListWebs
( ) and specifies a Password string creates a potential
security hole unless you can protect against physical
access to the executable. This is because the executable
can be searched for the user account name and password
string parameter used in to the call to vtiListWebs.
Therefore, we recommend that you use this function
with caution.



vtiDisableErrorDialogs


C++: void vtiDisableErrorDialogs(BOOL bYesNo);

VB: vtiDisableErrorDialogs(YesNo as Integer)


Description

This method allows you to turn off the display of any
error message dialog boxes that might be caused by
your OLE Automation calls. This is useful when creating
automated processes which must run without human intervention.

NOTE: There is no way in the current version of FrontPage
to get detailed information, such as an error code
or error text, based on the error that would have been
displayed if the error dialogs has not been disabled.

Return Value

None.

Parameters

YesNo specifies whether to turn error dialogs on or
off. If this value is true, then all Explorer error
dialogs will be suppressed until the object reference
is released, at which time error dialogs are re-enabled.



vtiQuit


C++: void vtiQuit ();

VB: vtiQuit


Description

This method is the same as choosing the Explorer's
File Exit command. If the Explorer is currently displaying
any modal dialogs, the application will not exit.

Return Value

None.

Parameters

None.



vtiPublishWeb


C++: long vtiPublishWeb(LPCTSTR pszServerUrl, LPCTSTR
pszWebName, long dwFlags, LPCTSTR pszUser, LPCTSTR
pszPassword)

VB: vtiPublishWeb(ServerURL as String, WebName as String,
Flags as Long, User as String, Password as String)
as Long


Description

This method provides an interface to the FrontPage
Explorer's File : Publish FrontPage Web command. It
copies the web that is currently open in the Explorer
to the target server and web name. This is a useful
method for automating the transfer of web content from
a staging server to a deployment server.

Return Value

0 for failure
1 for success

Parameters

ServerUrl specifies the web you are publishing to.
It can include a file:// or http:// or https:// prefix.
If no prefix is provided, http:// is assumed. If a
file path like C:\ is provided, the file:// prefix
is assumed. Examples: "http://www.microsoft.com", "http://micros
oft:8080".

WebName is either empty (" ") for the Root Web or it
is a subweb name without a slash (e.g. "MySubWeb".)

User is the user name to use when creating the target
web (if necessary). If User is NULL, then the User
name and password already established for the open
web in the Explorer are used for the publishing operation.

Password is the password corresponding to the User
account to use when creating the target web.

Flags is a bit field that allows the setting of various
options (which correspond to checkboxes in the File,
Publish FrontPage Web dialog box). You can logically
OR these values together and pass the result to set
the following options:

VALUE Meaning
1 Perform an incremental copy (only pages
that have changed are copied)
2 Add to an existing
web (don't create a new one)
4 Copy all subwebs (only
valid for Root Web)



NOTE for Visual Basic Users: The vtiPublishWeb call
can take a long time. To avoid user confusion from
the default Server Busy dialog in VB, you should wrap
your calls to this method from VB with the following
code: 

  App.OleRequestPendingTimeout = 1000
  App.OleRequestPendingMsgTxt = "PublishWeb in progress.
Please be patient."

  ; Your call to vtiPublishWeb goes here

  App.OleRequestPendingTimeout = 5000
  App.OleRequestPendingMsgTxt = " "


WARNING:  As with any program that contains password
information, creating a program that uses vtiPublishWeb(
) and specifies a Password string creates a potential
security hole unless you can protect against physical
access to the executable. This is because the executable
can be searched for the user account name and password
string parameter used in to the call to vtiPublishWeb.
Therefore, we recommend that you use this function
with caution.

vtiRemoveWebPages

C++: long vtiRemoveWebPages(LPCTSTR pszPageList)

VB: vtiRemoveWebPages(PageList as String) as Long


Description

This method provides an interface to delete one or
more documents from the current FrontPage web.

Return Value

0 for failure
1 for success

Parameters

PageList is a newline-delimited list of web-relative
page URLs to remove from the current FrontPage web.


vtiRenameDocument

C++: long vtiRenameDocument(BSTR pszURL, BSTR pszNewURL,
boolean bUpdateBacklinks, boolean bIsFolder, boolean
bCopy, boolean bForceOverwrite);

VB: vtiRenameDocument(URL as String, NewURL as String,
UpdateBacklinks as Boolean, IsFolder as Boolean, Copy
as Boolean, ForceOverwrite as Boolean) as Long


Description

This method provides a way to rename a document or
folder in the web and optionally patch all the links
to it found in other documents in the web. 

Return Value

0 for failure
1 for success

Parameters

URL is the web-relative path to the document being
renamed.

NewURL is the web-relative path where you want the
document to be moved. 

UpdateBacklinks should be normally be set to True so
that all other pages referring to URL are changed to
refer to NewURL.

IsFolder should be set True if URL is a folder instead
of a document.

Copy can be set True if what you really wanted was
to copy the original document rather than move it.

ForceOverwrite will cause any previous document at
NewURL to be overwritten by URL. If it is False and
NewURL exists, the user will receive a warning dialog.



vtiIsFeatureSupported

C++: long vtiIsFeatureSupported(BSTR pszFeature);

VB: vtiIsFeatureSupported(Feature as String) as Long


Description

Provides a way to determine if a given feature is supported
by the FrontPage Server Extensions for the current
web. 

Return Value

0 if not supported
1 if supported

Parameters

Feature is a string describing the feature being tested.
Possible values are:

KEY MEANING
vti_ServerEmailTransport Web server is
configured to send e-mail
vti_ServiceStructureStore Web
supports reading and storing navigational structure
information
vti_ServiceThemes Web supports themes
vti_ServiceMarkUrlDirExec Web
supports making a directory executable
vti_ServiceMarkUrlDirBrowse Web
supports making a directory browsable
vti_ServiceMarkUrlDirScript Web
supports making a directory scriptable




vtiListThemes

C++: BSTR vtiListThemes();

VB: vtiListThemes as String


Description

Retrieves information about all the themes installed
on the user's machine and in the current web.

Return Value

A list of records containing six (6) newline-delimited
fields, with one record for each theme. The order of
the fields is as follows:

name - the short name of the theme (directory name);
example: "mytheme"
title - the string shown to users in FrontPage to identify
the theme; example: "My New Theme"
installed - a flag that is "1" if the theme is installed
on the local machine or "0" if not
uploaded - a flag that is "1" if the theme is used
in the current web or "0" if not
version - a number indicating the version of the theme;
example: "1.01"
codepage - a number indicating the character encoding
(Windows codepage) in which the title string is encoded;
example: "1252"

Parameters

None.


vtiApplyTheme

C++: long vtiApplyTheme(BSTR pszName, long dParams,
BSTR fileList);

VB: vtiApplyTheme(Name as String, Params as Long, FileList
as String) as Long


Description

Applies a theme to all pages in the current web or
just to the specified pages. A theme must be uploaded
to the web before it can be applied; see vtiPutTheme.

Return Value

0 for failure
1 for success

Parameters

Name specifies the theme to apply. This is the short
name of the theme, the same as its directory name.

Params specifies the theme options to use, corresponding
to the checkboxes in the FrontPage Explorer's Themes
View. There are currently three boolean parameters:
Vivid Colors, Active Graphics, and Background Image.
They are represented as nibbles (4 bits) containing
0x0 or 0x1 in a 32-bit integer as follows, where CC
is the value for Colors, GG is the value for Graphics,
and BB is the value for the Background:

  0000 0000 00CC GGBB

FileList should be set to the empty string (" ") to
apply the theme to all pages in the web. To apply the
theme to only certain pages, set it to a newline-delimited
list of web-relative URLs.


vtiGetTheme

C++: BSTR vtiGetTheme(BSTR pszThemeDirName, BSTR pszLocThemesDir
);

VB: vtiGetTheme(ThemeDirName as String, LocThemesDir
as String) as String


Description

Downloads all theme files for a given theme.

Return Value

A newline-delimited list of the downloaded files. The
filenames are relative to the theme directory specified
by the LocThemesDir parameter.

Parameters

ThemeDirName is the short name of the theme, which
is the same as the theme's directory name. 

LocThemesDir is an absolute path to a local directory
where the theme files should be downloaded.



vtiPutTheme

C++: long vtiPutTheme(BSTR pszThemeDirname, BSTR pszThemeVersion
,
BSTR pszFileList, BSTR pszLocThemesDir);

VB: vtiPutTheme(ThemeDirname as String, ThemeVersion
as String, FileList as String, LocThemesDir as String)
as Long


Description

Uploads a theme from the user's machine to the current
web. 

Return Value

0 for failure
1 for success

Parameters

ThemeDirname is the short name of the theme, the same
as the theme's directory name. Example: "mytheme".

ThemeVersion is the version number of the theme, as
recorded in the theme's INF file. Example: "1.01".

FileList is a newline-delimited list of files to be
uploaded. These are not absolute paths, but relative
to the local directory specified by the LocThemesDir
parameter. Example: "mytheme.inf\nmytheme.elm".

LocThemesDir is an absolute path to the local directory
containing the files specified in the FileList parameter.
Example: "c:\temp\mytheme".


vtiPutWebStructure

C++: long vtiPutWebStructure(BSTR pszModifications);

VB: vtiPutWebStructure(Modifications as String) as
Long

Description

Provides a way to add navigational structure to the
current web, just as a user might with the FrontPage
Explorer's Navigation View.

Return Value

0 for failure
1 for success

Parameters

Modifications is a newline-delimited list of records
requesting additions to the structure tree maintained
by the web and displayed in the FrontPage Explorer's
Navigation View. If any of the modifications fail,
the entire list is rejected, the method returns 0 to
indicate failure, and the web is unmodified. Each modification
record contains four fields separated by commas:

  ElementID,URL,Label,ParentID

The URL field is a web-relative path to the page being
added, which must already exist in the FrontPage web.
The Label field is a string that will be displayed
on the corresponding node in the Navigation View, and
on automatically-generated links to the page represented
by the URL parameter.

Each node in the structure tree for the current web
has a unique ElementID. If you are creating a node,
no ID has been assigned to it, so you should provide
some small positive integer to serve as a temporary
identifier. This temporary identifier can be referred
to by other modification records in the ParentID field.

There are two reserved ID numbers: 0 represents the
virtual root node of the structure tree, and 1000 represents
the home page. You can use 0 as the ParentID to create
top-level pages, and 1000 as the ParentID to create
children of the home page.

Here's an example of how you could add two pages as
children of the home page:

  1,page1.htm,First Child,0
  2,page2.htm,Second Child,0

vtiGetWebStructureRelations

C++: BSTR vtiGetWebStructureRelations(BSTR pszUrl,
long lRelationType);

VB: vtiGetWebStructureRelations(Url as String, RelationType
as Long) as String

Description

Provides a way to query the current web for information
about its structure tree, as displayed by the FrontPage
Explorer's Navigation View.

Return Value

A list of newline-delimited records containing URL
and Label information for the nodes that match the
given RelationType. Each record consists of two lines,
the URL followed by the Label. If the given node is
not in the structure tree or does not have any relationships
of the requested type, an empty string is returned.


Parameters

Url is the web-relative URL of the node you want to
query for its structural relations.

RelationType is an integer denoting the type of relationship
being queried. The following table shows the available
type codes and their meanings.

TYPE CODE RELATIONSHIP
0 Nodes on level above given
page (all siblings of its Parent node)
1 Child nodes
for given page
2 Sibling nodes of given page (includes
given page at appropriate position in list)
3 Next
sibling node of given page
4 Previous sibling node
of given page
5 Top-level pages for current web (includes
home node at appropriate position in list)
6 Home node
for current web
7 Parent node for given node
8 Self
(returns info for given node)
9 Home, Up, Previous,
and Next nodes (in that order) for given node; always
returns 4 records, but some may be empty


vtiReturnDBWRoot

C++: BSTR vtiReturnDBWRoot(BSTR pszFileURL);

VB: vtiReturnDBWRoot(FileURL as String) as String


Description

Provides a way to discover the main web directory for
a file in a local disk-based FrontPage web. A disk
based web is one that can be edited locally without
requiring a web server. This call is most useful in
conjuction with vtiListWebs.

Return Value

A path to the root of the local FrontPage web, or the
empty string if the call is not successful.

Parameters

FileUrl is the path to a local file in a disk-based
web for which you want to find the path to the main
web directory.



vtiMakeThemeFresh

C++: long vtiMakeThemeFresh(BSTR pszWebUrl, BSTR pszThemeName,
boolean bAllowUpload, boolean bAllowDownload);

VB: vtiMakeThemeFresh(WebUrl as String, ThemeName as
String, AllowUpload as Boolean, AllowDownload as Boolean)
as Long


Description

Synchronizes the versions of  a FrontPage Theme currently
installed on the local machine and in the current FrontPage
web. The theme with the higher version number is used
to update the theme with the lower version number if
the Boolean flags allow it.

Return Value

0 for failure
1 for success

Parameters

WebUrl specifies the web to be operated on. You can
get this value using vtiGetWebURL.

ThemeName is the short name of the theme to be synchronized.
This is the same as the theme's directory name.

AllowUpload should be set to True to allow the theme
files to be uploaded to the web from the local machine
if necessary.

AllowDownload should be set to True to allow the theme
files to be downloaded from the web to the local machine
if necessary.


vtiSetCurrentView

C++: boolean vtiSetCurrentView(long nViewID, boolean
bTransferSelection, long nFlags);

VB: vtiSetCurrentView(ViewID as Long, TransferSelection
as Boolean, Flags as Long) as Boolean


Description

Changes the view displayed by the FrontPage Explorer.

Return Value

True - success
False - failure

Parameters

ViewID is a small integer representing the desired
view. The following table shows the possible values
and their meanings.

ID VIEW
0 Hyperlinks View
1 Folder View
2 Navigation
View
3 Themes View
4 All Files View
5 Tasks View
6 Hyperlink
Status View

TransferSelection is normally set True. If possible,
it causes the selection in the current view to be made
the current selection in the new view.

Flags should be set to 0 and is currently unused.


vtiIsFolderInWeb

C++: boolean vtiIsFolderInWeb(BSTR pszFolderUrl);

VB: vtiIsFolderInWeb(FolderUrl as String) as Boolean


Description

Tests whether a given web-relative folder exists in
the current FrontPage web.

Return Value

True - folder exists
False - folder does not exist

Parameters

FolderUrl is a web-relative path to the folder whose
existence is being queried.


vtiSetFolderOptions

C++: boolean vtiSetFolderOptions(BSTR pszFolder, boolean
bExecutable, boolean bReadable);

VB: vtiSetFolderOptions(Folder as String, Executable
as Boolean, Readable as Boolean) as Boolean


Description

Provides a way to set whether or not a folder in the
current FrontPage web has execute and read permissions.

Return Value

True - success
False - failure

Parameters

Folder is the web-relative path to the folder whose
permissions are to be changed.

Executable should be set True to turn on execute permission
or False to turn it off. 

Readable should be set True to turn on read permission
or False to turn it off.


vtiRefreshThemeList

C++: boolean vtiRefreshThemeList();

VB: vtiRefreshThemeList as Boolean


Description

Provides a way to force the FrontPageExplorer to re
read the list of FrontPage themes installed on the
local machine. This might be used after installing
a new theme created by  a wizard or other program.

Return Value

True - success
False - failure

Parameters

None.


vtiSetEditor

C++: boolean vtiSetEditor(BSTR szType, BSTR szName,
BSTR szCommand);

VB: vtiSetEditor(Type as String, Name as String, Command
as String) as Boolean


Description

Provides a way to set the program that will be used
to edit a file type based on its extension. The name
of the program will appear in the FrontPage Explorer's
list of configured editors, and when a file with the
given extension is opened, the program will be invoked
and passed a path to the file on the command line.

Return Value

True - success
False - failure

Parameters

Type is a three-letter extension, without the initial
dot ("."). Example: "dat".

Name is the friendly name for the given program. Example:
"My Data File Editor".

Command is the command line that will be used to invoke
the program. Example: "c:\myeditor\dataedit.exe".


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):

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);

The following automation methods were added in FrontPage
97:

CSTRING vtiListOpenDocs();
void vtiRefreshDocument(LPCTSTR szPageUrl, LPCTSTR
szWebUrl);
CSTRING vtiGetBookmarkList(LPCTSTR pszPageUrl, LPCTSTR
pszWebUrl);
long vtiScrollToBookmark(LPCTSTR pszPageUrl, LPCTSTR
pszWebUrl, LPCTSTR pszBookmark);
long vtiInsertFile(LPCTSTR pszPageUrl, LPCTSTR pszWebUrl,
LPCTSTR pszFile);
long vtiInsertImage(LPCTSTR pszPageUrl, LPCTSTR pszWebUrl,
LPCTSTR pszFile);
BSTR vtiGetTopPageUrl();
long vtiInsertHTML(LPCTSTR pszHTML);
void vtiPaste(); 
void vtiQuit();
long vtiBringPageToTop(LPCTSTR szURL, LPCTSTR szWebURL,
LPCTSTR szCookie, long toDoTaskId);

The following automation methods were added in FrontPage
98:

long vtiSetMetaTag(BSTR pszPageUrl, BSTR pszWebUrl,
BSTR pszKey, BSTR pszValue, long lIndex, long flags);
BSTR vtiListMetaTags(BSTR pszPageUrl, BSTR pszWebUrl,
long flags);
long vtiDeleteMetaTag(BSTR pszPageUrl, BSTR pszWebUrl,
BSTR pszKey, long lIndex, long flags);
BSTR vtiGetMetaTag(BSTR pszPageUrl, BSTR pszWebUrl,
BSTR pszKey, long lIndex, long flags);
long vtiQueryWebPageEx(BSTR szURL, BSTR szWebURL, boolean*
bDirty, boolean* bWritable);


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",
  NULL,NULL,NULL);
  if(pNewDoc != NULL) pNewDoc->Release();

VB:   
  Dim newdoc as Object
  Set newdoc = editor.vtiOpenWebPage("C:\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 document from
the current web (on a local or remote web server) or
from the Internet, see the FrontPage Explorer method
vtiEditWebPage. Most page wizards use this call to
load a temporary file they have created into the FrontPage
Editor, setting a suggested page URL and leaving the
web URL and web title arguments empty. 

IMPORTANT: If the file referenced by FileName is in
the FrontPage temp directory, it will be deleted after
it is loaded into the FrontPage Editor.

Return Value

A pointer to an OLE dispatch object suitable for further
automation calls (when they are defined). For this
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. If you leave it blank, the Editor will
suggest a URL for you. Example: "test.htm".

WebURL is either empty or 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.microsoft.com".

WebTitle is either empty or 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: "Microsoft 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 either an absolute URL or a URL relative to
WebURL indicating the document being queried. Example:
"test.htm".

WebURL is either empty or an indication of the web
that the document came from. You can use the FrontPage
Explorer method vtiGetWebURL to set this parameter.
Examples: "www.microsoft.com", "http://www.microsoft.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 this
release of FrontPage, you should immediately release
this object as described at the start of this section.

Parameters

URL is either empty or 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 either empty or 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.microsoft.com".
(Note: If the value is passed without the http:// appended
to the front of the URL, value szWebURL is ignored
by the Editor, instead of showing up in the Properties
and Save As... dialog boxes after the function has
been called.)

WebTitle is either empty or 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: "Microsoft Main Web".



vtiListOpenDocs


C++: CSTRING vtiListOpenDocs();

VB: vtiListOpenDocs as String


Description

This method is used to get a list of all of the documents
currently open in the FrontPage Editor.

Return Value

A newline-delimited list of absolute PageUrls (including
file:/// or http://) of the pages currently open in
the Editor.

Parameters

None.


vtiRefreshDocument


C++: void vtiRefreshDocument(LPCTSTR szPageUrl, 
LPCTSTR szWebUrl);

VB: vtiRefreshDocument (PageUrl as String, WebUrl as
String)


Description

This command immediately reloads the named page into
the FrontPage Editor from the web, overwriting any
previous unsaved changes which have been made to the
page.

Return Value

None.

Parameters

The typical usage is to pass in the full PageUrl and
leave WebUrl empty. But for convenience, you can specify
the WebUrl as an absolute URL and the PageUrl as a
web-relative URL.

PageUrl is the either the absolute URL of the page,
or a web-relative URL of the page that you want to
reload into the Editor.

WebURL is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

Examples: 
vtiRefreshDocument("http://www.microsoft.com/status/january.htm"
,
NULL);
vtiRefreshDocument("status/january.htm", "http://www.microsoft.c
om");


vtiGetBookmarkList


C++: CSTRING vtiGetBookmarkList(LPCTSTR szPageUrl,

LPCTSTR szWebUrl);

VB: vtiGetBookmarkList(PageUrl as String, WebUrl as
String) as String


Description

Retrieves a list of all of the internal bookmarks present
in the specified HTML page.

Return Value

A newline-delimited list of bookmarks on the specified
HTML page.

Parameters

The typical usage is to pass in the full PageUrl and
leave WebUrl empty. But for convenience, you can specify
the WebUrl as an absolute URL and the PageUrl as a
web-relative URL.

PageUrl is the either the full URL of the page, or
a web-relative URL of the page for which you want to
get the list of bookmarks.

WebURL is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

See vtiRefreshDocument( ) for example usage.


vtiScrollToBookmark


C++: long vtiScrollToBookmark(LPCTSTR pszPageUrl, LPCTSTR
pszWebUrl, LPCTSTR pszBookmark);

VB: vtiScrollToBookmark(PageUrl as String, WebUrl as
String, Bookmark as String) as Long


Description

Scrolls the display of the FrontPage Editor window
to the specified bookmark in the specified HTML page.


Return Value

1 if the bookmark was found and was scrolled to
0 if the bookmark was not found in the specified document

Parameters

The typical usage is to pass in the full PageUrl and
leave WebUrl empty. But for convenience, you can specify
the WebUrl as an absolute URL and the PageUrl as a
web-relative URL.

PageUrl is the either the full URL of the page, or
a web-relative URL of the page that have the bookmark
you want to scroll to.

WebURL is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

Bookmark is the name of the HTML bookmark to which
you want to scroll.


vtiInsertFile


C++: long vtiInsertFile(LPCTSTR pszPageUrl, LPCTSTR
pszWebUrl, LPCTSTR pszFile);

VB: vtiInsertFile(PageUrl as String, WebUrl as string,
File as String) as Long


Description

This method inserts the specified file at the insertion
point in the specified page. This is equivalent to
the FrontPage Editor's Insert : File command. The type
of the file is inferred from the file extension. This
method is useful for FrontPage addins which follows
these general steps:
Addin is invoked from a custom menu command
A dialog is presented to get user input
User presses Ok, and addin generates an output HTML
file and inserts it into the page at the insertion
point.

Return Value

0 if the file does not exist
1 if the insertion succeeded

Parameters

The typical usage is to pass in the full PageUrl and
leave WebUrl empty. But for convenience, you can specify
the WebUrl as an absolute URL and the PageUrl as a
web-relative URL.

PageUrl is the either the full URL of the page, or
a web-relative URL of the page into which you want
to insert another file.

WebURL is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

File is the name of the locally accessible file which
you want to insert into the page. That is, it must
be a standard file or UNC path reference and not a
URL. (e.g. c:\insertme.htm; or \\server\share\thefile.txt)



vtiInsertImage


C++: long vtiInsertImage(LPCTSTR pszPageUrl, LPCTSTR
pszWebUrl, LPCTSTR pszFile);

VB: vtiInsertImage(PageUrl as String, WebUrl as String,
File as String) as Long


Description

This method inserts the specified image file at the
insertion point in the specified page. This is equivalent
to the FrontPage Editor's Insert : Image command's
Other Location option. The type of the image is inferred
from the file extension. The image is automatically
converted to a GIF or JPEG based on the size of the
color palette in the image (GIF = 8-bit; JPEG = 24
bit.)

This method is useful when writing FrontPage addins
or companion programs which provide an alternate user
interface for inserting images into a web page.

Return Value

0 if the file does not exist
1 if the insertion succeeded

Parameters

The typical usage is to pass in the full PageUrl and
leave WebUrl empty. But for convenience, you can specify
the WebUrl as an absolute URL and the PageUrl as a
web-relative URL.

PageUrl is the either the full URL of the page, or
a web-relative URL of the page into which you want
to insert an image.

WebURL is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

File is the name of the locally accessible image file
which you want to insert into the page. That is, it
must be a standard file or UNC path reference and not
a URL. (e.g. c:\insertme.gif; or \\server\share\thefile.jpg)



vtiGetTopPageUrl


C++: BSTR vtiGetTopPageUrl();

VB: vtiGetTopPageUrl as String


Description

This method returns the full URL of the current (on
top) page in the FrontPage Editor. The return value
from this call can be used in other Editor automation
calls which take a pszPageUrl parameter.

Return Value

The full URL of the active page in the FrontPage Editor.

Parameters

None.


vtiInsertHTML


C++: long vtiInsertHTML(LPCTSTR pszHTML);

VB: vtiInsertHTML(HTML as String) as Long


Description

This method inserts the HTML contained in passed string
into the current page in the FrontPage Editor at the
insertion point. This is designed to be a very simple,
single API method for FrontPage addins to insert HTML
into a web page.

Return Value

0 if the insert failed
1 if the insertion succeeded

Parameters

HTML is a string containing the exact pieces of HTML
to insert into the active page in the Editor. FrontPage
will automatically insert the specified HTML into a
position in the page's HTML where it is syntactically
correct.


vtiPaste


C++: void vtiPaste();

VB: vtiPaste


Description

This method pastes whatever's on the Windows clipboard
into the active page in the FrontPage Editor, at the
insertion point. This is equivalent to the Editor's
Edit : Paste command.

Return Value

None.

Parameters

None.


vtiQuit


C++: void vtiQuit();

VB: vtiQuit


Description

This method is the same as clicking on the Editor's
application close button or using the File : Exit command.
If the Editor is displaying any modal dialogs the application
will not exit.

Return Value

None.

Parameters

None.

vtiBringPageToTop

C++: long vtiBringPageToTop(LPCTSTR szURL, LPCTSTR
szWebURL, 
  LPCTSTR szCookie, long toDoTaskId);

VB: vtiBringPageToTop(URL as String, WebURL as String,
Cookie as String, toDoTaskId as Long) as Long


Description

This method causes the specified page to be brought
to the top of the stack of page windows in the FrontPage
Editor.

Return Value

1 - success
0 - failure

Parameters

URL is an absolute page URL

WebURL should be an empty string. (Or, WebURL can be
the web's URL and URL is the web-relative page URL.)

Cookie should be an empty string.

toDoTaskId should be 0.



vtiSetMetaTag

C++: long vtiSetMetaTag(BSTR pszPageUrl, BSTR pszWebUrl,
BSTR pszKey, BSTR pszValue, long lIndex, long flags);

VB: vtiSetMetaTag(PageUrl as String, WebUrl as String,
Key as String, Value as String, Index as Long, Flags
as Long) as Long


Description

Provides a way to set a meta tag in the HEAD section
of the given FrontPage document.

Return Value

1 - success
0 - failure

Parameters

PageUrl is the either the full URL of the page, or
the web-relative URL of the page.

WebUrl is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

Key is the name that will be used for the tag.

Value is the value that will be used for the tag.

Index is a number specifying which tag you want to
set in case there are several with the same name (as
given by the Key parameter). Set it to -1 to always
append a new meta tag.

Flags should be set to 0 to set a normal meta tag or
1 to set an "http-equiv" meta tag. When set to 0, the
HTML will look like this:

  <meta name="key" content="value">

When set to 1, the HTML will look like this:

<meta http-equiv="key" content="value">


vtiListMetaTags

C++: BSTR vtiListMetaTags(BSTR pszPageUrl, BSTR pszWebUrl,
long flags);

VB: vtiListMetaTags(PageUrl as String, WebUrl as String,
long Flags) as String


Description

Provides a way to get a list of all the meta tags in
the HEAD section of a document being edited by the
FrontPage Editor.

Return Value

A newline-delimited list of records containing all
the meta tags in the document. Each records consists
of two lines, the first holding the tag name and the
second the tag value. If there are no meta tags the
empty string is returned.

Parameters

PageUrl is the either the full URL of the page, or
the web-relative URL of the page.

WebUrl is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

Flags should be set to 0 to select normal meta tags
or 1 to select "http-equiv" meta tags.


vtiDeleteMetaTag

C++: long vtiDeleteMetaTag(BSTR pszPageUrl, BSTR pszWebUrl,
BSTR pszKey, long lIndex, long flags);

VB: vtiDeleteMetaTags(PageUrl as String, WebUrl as
String, Key as String, Index as Long, Flags as Long)
as Long


Description

Provides a way to remove one or all meta tags with
the given key from the HEAD section of a document being
edited by the FrontPage Editor.

Return Value

1 - success
0 - failure

Parameters

PageUrl is the either the full URL of the page, or
the web-relative URL of the page.

WebUrl is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

Key is the name that will be used for the tag.

Index is a zero-based number specifying which tag you
want to delete in case there are several with the same
name (as given by the Key parameter). 

Flags should be set to 0 to remove a normal meta tag
or 1 to remove an "http-equiv" meta tag. You can also
add 2 to this value to indicate that all meta tags
from Index to the last should be deleted.


vtiGetMetaTag

C++: BSTR vtiGetMetaTag(BSTR pszPageUrl, BSTR pszWebUrl,
BSTR pszKey, long lIndex, long flags);

VB: vtiGetMetaTag(PageUrl as String, WebUrl as String,
Key as String, Index as Long, Flags as Long) as String


Description

Provides a way to retrieve the value of a meta tag
with the given name in a document being edited by the
FrontPage Editor.

Return Value

The value of the given meta tag.

Parameters

PageUrl is the either the full URL of the page, or
the web-relative URL of the page.

WebUrl is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

Key is the name that will be used for the tag.

Index is a zero-based number specifying which tag you
want to get the value for in case there are several
with the same name (as given by the Key parameter).


Flags should be set to 0 for a normal meta tag or 1
for an "http-equiv" meta tag. 


vtiQueryWebPageEx

C++: long vtiQueryWebPageEx(BSTR szURL, BSTR szWebURL,
boolean* bDirty, boolean* bWritable);

VB: vtiQueryWebPageEx(URL as String, WebURL as String,

  Dirty as Boolean, Writable as Boolean) as Long


Description

Provides a way to query the state of the "has-changed"
and "is-writable" flags of a document being edited
by the FrontPage Editor. 

Return Value

1 - success
0 - failure

Parameters

URL is the either the full URL of the page, or the
web-relative URL of the page.

WebURL is either NULL (if you specify a full PageUrl)
or the URL of the FrontPage web which contains PageUrl.

Dirty is an output parameter that is set to True if
the document has been changed since being loaded.

Writable is an output parameter that is set to True
is the document can be modified.


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):

  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);




vtiShow


C++: void vtiShow();

VB: vtiShow


Description

In FrontPage 98, this method causes the Tasks View
to become the current view in the FrontPage Explorer.
In older versions it caused a To Do List dialog to
appear.

Return Value

None.

Parameters

None.



vtiHide


C++: void vtiHide();

VB: vtiHide


Description

In FrontPage 98, this method causes the Folder View
to become the current view in the FrontPage Explorer.
In older versions it caused a 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".

Custom FrontPage Components

Overview

FrontPage lets anyone create custom FrontPage components
(formerly "WebBot components"). These components allow
end users to insert interactive features on a web page
without any programming. Each FrontPage component has
three main parts:
A property editing user interface
A presentation in the WYSIWYG editor
A server side component which delivers the interactivity

The FrontPage component stores its persistent state
in a list of typed properties encoded inside of a standard
HTML comment on a web page. At save-time or at browse
time, the server side component performs an expansion
operation which takes this persisted information and
outputs the final HTML that should be displayed in
a web browser.

FrontPage ships with a set of a dozen built-in components.
For convenience, custom FrontPage components only need
to be installed on web servers with the FrontPage Server
Extensions. Custom FrontPage components can be installed
so they are available from any web server on the host
machine, or just from a single web server. Custom components
become available to all FrontPage authors when they
open a web where the FrontPage components are installed.
The information needed to insert the custom components
into a web page is automatically downloaded by the
FrontPage client at authoring time.
HTML Representation of FrontPage Components 

In previous versions, most FrontPage components were
represented inside a single HTML comment using a syntax
like this:

<!--VERMEER Bot=BotName Attr1="Xxx" Attr2="Yyy" -->

Pages that contained FrontPage components were stored
in a subdirectory of each web called "_vti_shm", with
the expanded browse-time presentation of the pages
kept in the main web directory.

Most FrontPage components use a variation of this syntax
that allows for storage of both the authoring-time
attributes and the expanded browse-time HTML presentation
inside a single logical construct, and removes the
need to store two versions of each page. Here is an
example of the new "spanning" syntax:

<!--WEBBOT Bot=BotName Attr1="Xxx" Attr2="Yyy" StartSpan
-->
<P><STRONG>Expanded version of BotName</STRONG></P>
<!--WEBBOT Bot=BotName EndSpan I-CheckSum=Zzz -->


The new spanning syntax consists of a StartSpan comment,
the spanned HTML that is generated by the FrontPage
component, and an EndSpan comment. The EndSpan comment
contains a computed checksum of the spanned HTML. The
checksum allows the FrontPage Server Extensions and
the FrontPage Editor to detect manual changes made
to the spanned HTML, and either discard the changes
or regenerate the spanned HTML as appropriate.

For backwards compatibility, the FrontPage Editor and
the FrontPage Server Extensions can read the old syntax
for FrontPage components. However, when the FrontPage
component is expanded and saved, it will be stored
using the new syntax unless the page is saved into
a web with an older version of the FrontPage Server
Extensions (prior to FrontPage 97).
Activating a Custom FrontPage Component

A FrontPage component becomes active momentarily whenever
the containing page is:

saved by the FrontPage Editor
regenerated by the FrontPage Server Extensions due
to a dependency which required updating
the target of an HTTP POST request, such as when a
browser submits a form
fetched through the SmartHTML interpreter by an HTTP
GET request (with a URL like webname/_vti_bin/shtml.exe/pagename
.htm).


When a component is activated, it can perform different
operations depending on the current values of its properties,
the standard CGI environment variables, or any form
data that a user may have submitted. Typical component
operations include:
inserting generated HTML into the page at the FrontPage
component's location
handling a form submitted to the page
generating a completely new HTML page
redirecting the browser to an alternate page. 

To improve web performance, the FrontPage Server Extensions
store the static HTML that is generated by the component
directly inside the HTML page, when it is saved by
the FrontPage Editor or is updated by the FrontPage
Server Extensions due to a dependency change. Since
this static HTML is inside of a static page, it can
be fetched with a simple HTTP-GET request rather an
HTTP-POST. This avoids having to spawn a CGI process
to view the page.

The following two diagrams illustrate the process of
first saving a page with custom components to a web
using FrontPage, and then submitting a form to the
same page with a browser.


1. Saving a page with custom FrontPage components


2. Submitting a form to a page with custom FrontPage
components

Editing Custom FrontPage Component Attributes

Custom components are placed into pages from the FrontPage
Editor, using either the Insert : FrontPage Component
dialog or the Form Properties dialog. An author can
configure a FrontPage component by editing its properties.
This causes the dialog box appropriate for the given
type of component to be displayed. If no dialog is
registered for the component's type, it can still be
modified with the generic FrontPage Component Properties
dialog. When the component's dialog is dismissed, its
attribute list is written back into the page inside
the HTML comment.


The generic FrontPage Component Properties dialog
Custom FrontPage Components

There are three parts to a custom component: the component
description file, the component template file, and
the component implementation file. 

All of the pieces are installed in a special directory
for the custom FrontPage components. Each directory
can contain one or more components, and contains a
single FrontPage component description file and, optionally,
component template and implementation files.

The component description file identifies the name,
type, and capabilities of each component in that directory,
and tells where to find each component's template and
implementation files. The information kept in the description
files of all of custom component directories is downloaded
to the FrontPage client when a web is opened or has
its links recalculated. This information is used to
construct the merged list of built-in FrontPage components
and custom FrontPage components displayed in the FrontPage
Editor's Insert : FrontPage Component dialog.

The component template file is an HTML document containing
type information about each of the component's attributes
and their initial state. Each user-editable parameter
is classified as one of the basic types: Boolean, Integer,
String, Date, URL, or Color. In addition, Integer and
String parameters can be given MIN and MAX ranges (which
apply to a String's length), and a String parameter
can be specified as a RADIO choice (a one-of-many selection).
This information allows the generic FrontPage Component
Properties dialog to display type-appropriate editing
controls for each attribute. The component template
files are downloaded by the FrontPage Editor only when
needed, such as the first time a component of a given
type is inserted into a page. The component template
file is used only if the clientbinding=BTL parameter
is used (see below for more information on the clientbinding
setting.)

The component implementation file can be a dynamic
link library or program written in C or C++, or an
interpreted script file written in a language like
Perl or Tcl. If the implementation file is for a component
with a clientbinding=DLL setting, it is downloaded
to the client automatically. The C and C++ implementations
can be compiled into libraries or executable programs
for Win32 or UNIX-based web servers. A custom component
library is loaded by the FrontPage Server Extensions
or the FrontPage Editor, as required. A server-side
component program or script is launched by the FrontPage
Server Extensions, with parameters sent back and forth
via the UNIX-style standard input/output (stdio) file
mechanism. A client-side component program is launched
by the FrontPage Editor (if clientbinding=DLL) and
parameters are sent back and forth via standard DLL
function parameters.

Installing Custom FrontPage Components

All custom components are installed on the server.
No client-side installation is required.

Web server administrators have two options when installing
new custom components:
make them available to all web servers on a machine
make them available to only one web server on a machine.


To make custom components available to all web servers
on a machine, the components should be installed in
the FrontPageRoot/bots directory, where FrontPageRoot
is c:\Program Files\Microsoft FrontPage by default
for Windows 95 and Windows NT, or /usr/local/frontpage
by default for UNIX. These components can be used in
any FrontPage web hosted by that machine.

To make custom components available to just one web
server on a machine, the components should be installed
in content/_vti_bot directory, where content is the
Root Web's content directory for the chosen web server.
These components can be used in the Root Web and all
of its sub-webs. 

In the case of conflicts (duplicate custom components
in the per-machine and per-server directories), the
per-server custom components take precedence. 

NOTE:  After installing a custom FrontPage component
(such as the Electronic Commerce Wizard), the root
web needs to have a Recalculate Hyperlinks operation
performed by a root web author or administrator before
the component is made available. Only after this operation
is performed will the newly-installed custom component
appear in the Insert FrontPage Component dialog box
in the FrontPage Editor. This behavior is new for FrontPage
98 as an added security measure; in prior versions,
recalculating any FrontPage web was sufficient.
The Custom FrontPage Component Directory

Each custom component is installed in a custom component
directory. There can be many custom component directories
underneath the main FrontPageRoot/bots directory or
content/_vti_bot installation directories. 

Each component directory can contain one or more custom
FrontPage components. The API supports this grouping
by requiring uniquely named objects and methods for
each component, and by using a map of component names
to their (possibly shared) implementation modules in
the component description file. Having more than one
component in the same module is only supported if all
the implementations are in a single module. 

There is a single component description file for all
the components in the directory (see below for details
on the file format). The name of the component description
file is the same as the component directory name, but
with the ".inf" suffix added.

For example, the component directory FrontPageRoot/bots/foo
should contain a component description file called
FrontPageRoot/bots/foo/foo.inf. 


The Component Description File

Each component must be named in the component directory's
description file, and associated with another file:
the component implementation file. The binding between
a given component and this file is established by the
component description file. A single component template
file can describe multiple custom components, and a
single object library, executable program, or script
file can contain the implementation for multiple custom
components. 

A component description file uses the Windows INI file
format. The following is a sample component description
file specifying two components that use the same implementation
and template files:

[info]
list=ComponentOne,ComponentTwo
clientarchitectures=All
serverarchitectures=All
vendor=Microsoft
contact=http://www.microsoft.com
version=0.1
serverbinding=stdio
servermodule=newbots.pl
clientbinding=BTL
clientmodule=newcomponents.htm

[ComponentOne]
name=New Component One
description=something or other
type=insert

[ComponentTwo]
name=New Component Two
description=something or other
type=insert

The component description file must contain an [info]
section; its keys apply to all of the components in
the directory. If the directory contains only one component,
then all of the keys can go into the [info] section.
If there are multiple components in the directory,
each one must have a separate section with the same
name as the component.

Per-Directory Keys

The keys stored in the component description file's
[info] section are:

list 
A comma-separated list of component shortnames enumerating
the components in this directory. The shortnames must
be unique across all components in the web. An easy
way to do this is to pre-pend a company name to the
name of the component. This is an optional parameter;
if not present, there is only one component in this
description file (whose shortname is the basename of
the info file) and all keys are in the [info] section.
serverarchitectures 
Reserved for future use. This is an optional parameter.
If present, the value should be "All".
clientarchitectures 
Must be present for the client to be able to insert
a new FrontPage component of this type into a page.
For this release, the value should be either "All"
or "WinI386". If you set the clientBinding key (see
below) to type "DLL", you should use "WinI386" so that
only Windows clients will download the module. For
a clientBinding of type "BTL", you should use "All"
so that any client can use it. You should always provide
a BTL binding in addition to any DLL binding, so that
all FrontPage clients can use the component. This key
is mandatory for the client and optional for the server.
version 
A version number, which can be an integer or decimal
number. This is a mandatory parameter. The FrontPage
client compares the FrontPage component's version number
in the \botcache directory with the version number
reported by the FrontPage server during a recalculate
links or open web operation. The client will not download
a fresh DLL from the server unless the version number
on the server is greater than the version number cached
on the client. To make sure all clients will recognize
a new version of a FrontPage component DLL, you should
increment the FrontPage component's version number
(even if it's by .01) and do a Recalculate Hyperlinks
operation in the FrontPage Explorer.
vendor 
The component vendor's name. This is an optional parameter.

contact 
How to contact the vendor (by URL, telephone, etc.).
This is an optional parameter. 
serverBinding 
The method for interfacing with the server-side implementation.
Possible values are "DLL" or "Stdio". Windows servers
This is a mandatory parameter if this directory includes
a component implementation file.
serverModule 
References the server-side implementation file (library,
executable file, or script). This is a mandatory parameter
if this directory includes a server-side implementation.
serverInterpreter 
If the serverModule is a script (which implies that
serverBinding must be Stdio) and the server OS cannot
auto-execute scripts (such as Windows) then this key
identifies the script interpreter. If this directive
is present then instead of executing serverModule,
FrontPage will execute serverInterpreter and pass it
serverModule as its first argument.
clientBinding 
The method for interfacing with the client-side implementation.
There are two possible values: "DLL" or "BTL" (Bot
Template Language - described below). This is a mandatory
parameter if this directory includes a client-side
implementation.
clientModule 
References the client-side implementation file. This
is a mandatory parameter if this directory includes
a client-side implementation. This points to the file
containing the template or the DLL. For convenience,
template files usually have a .htm extension. 


Per-Bot Keys

If more than one custom FrontPage component is specified
in the description file, then each component mentioned
in the [info] section's "list" key should have its
own section with the same name (which is called the
component's shortname) and the following keys. If only
one component is specified in the component directory,
then these per- component keys can be placed in the
[info] section.

The keys stored in the per- component sections are:

name 
The displayable name of the component (also called
the component's longname), as shown in the FrontPage
Editor's Insert : FrontPage Component dialog. This
is an optional parameter. It defaults to the component's
shortname. 
description 
A short description of the component. This is an optional
parameter. 
type 
The type of component. Possible values are "insert"
or "form". A form component handles form submissions,
while an insert component usually replaces itself with
some HTML. This is a mandatory parameter.

Supporting Multiple Client Bindings

A component can provide more than one client binding.
In fact, any component that provides a DLL interface
should provide at least two: a DLL binding for the
WinI386 client architecture, and BTL client binding
for all other client architectures. The following example
shows how to specify both platform-dependent and platform
independent client bindings in a component's INF file,
with a preference for the platform-dependent version:

[info]
list=HitCounter
clientarchitectures=WinI386,all
vendor=Microsoft
contact=http://www.microsoft.com
version=2.1
serverbinding=dll
servermodule=fpcntsrv.dll
clientbinding=BTL
clientmodule=fpcntclt.btl

[WinI386]
clientbinding=dll
clientmodule=fpcntclt.dll

[HitCounter]
name=Hit Counter
description=Adds a hit counter to your page
type=insert

The Component Template File

A component template specifies the name, type, and
initial state of all the component's attributes with
the FrontPage Bot Template Language (BTL, or "bottle").
This is the same format used to store the persistent
state of a FrontPage component instance after it is
inserted on a page. The presence of BTL on a page is
what distinguishes SmartHTML from HTML.

Here is a simple example component described in BTL
to refer to as you read this section: 

<!--WEBBOT BOT=SampleBot S-PARAM1="This is a string"
-->

BTL Syntax

FrontPage component templates and instances stored
in BTL are legal HTML comments. They begin with the
string <!--WEBBOT and end with the string -->. No white
space is allowed between the opening <!-- and WEBBOT,
which must be all upper-case. There must be at least
one white space character before the closing -->. HTML
allows white space between the final -- and the >,
but BTL does not.

Between the delimiters are one or more space-separated
attributes which have essentially the same syntax as
the attributes of an HTML tag. The attributes are name
value pairs with an equal sign between the name and
the value. White space is allowed around the equal
sign. The name begins with a letter and is followed
by up to 71 letters, digits, periods, or hyphens. The
name is case-insensitive. The value may be either a
string literal enclosed in double quotes or a name
token (with a leading digit allowed). Some attributes
may consist of a name only with the equal sign and
value omitted. 

String literals may not contain a double-quote, ampersand,
or greater-than character, but they may include new
lines. To include a quote, ampersand, or greater-than
character in a string-literal, escape it using HTML
syntax: For example: 

"You must escape the &quot; &amp; and &gt; characters"

The first attribute of a component must be BOT=shortname.
The shortname may be written in mixed case for readability,
but it is case insensitive; MACRO, Macro, and macro
refer to the same type of component.

Repeated attributes with the same name but different
values are allowed, this is how components can store
arrays of values. For example: 

<--WEBBOT BOT=ClickImage RECT="10,10,50,20" RECT="10,30,50,20"
-->

Components are not allowed inside an HTML tag (for
example as the value of an HREF attribute), but otherwise
components are allowed anywhere in the HTML stream
that the text returned by the component's evaluate
method would be allowed. 

HTML comments (and thus components) do not generate
any white space when processed. Thus:

some<!--WEBBOT BOT=NoOpBot -->pig

will be displayed as somepig by the editor or a browser.

Reserved BTL Attributes

Certain reserved attributes have special meanings that
are understood by the generic FrontPage Component Properties
dialog. These reserved attributes are not required,
but if present must be used as described below. Other
attributes have a leading character and a dash in their
name to indicate their data type. This information
is used by the generic FrontPage Component Properties
dialog to display type-appropriate controls for modifying
the attribute's value.

The following table summarizes the reserved BTL attributes
and what they mean: 

Attribute Meaning
NAME A short user-readable name for
the component type. Often just the shortname with spaces,
i.e. BOT=TextSearch NAME="Text Search". This defaults
to the shortname
TAG The HTML tag type returned by
the Evaluate method of the component. The value should
be a valid HTML tag (with no < or >; example: TAG=H3).
If TAG is not provided, the component should evaluate
to plain text with no embedded HTML tags.
PREVIEW A
preview string, possibly containing some HTML tags.
If present, the FrontPage Editor uses this as the edit
time representation of the component. If it is missing
(and the component is unknown), the FrontPage Editor
displays the component name in a pair of square brackets,
like this: [WebBotName]

If a TAG is provided, then the PREVIEW string must
match the tag type. For example, if TAG=H2, then a
valid PREVIEW string would be something like "<H2>Test
Component</H2>".

The PREVIEW string must have any embedded <, &, >,
and " characters properly escaped. The previous example
would be stored in BTL file as:

  PREVIEW="&lt;H2&gt;Test Bot&lt;/H2&gt;".
DESCR A short
(one or two sentences at most) description of what
the component is and does. This is displayed by the
generic FrontPage Component Properties dialog. Extra
white space and new lines are removed from the description
string before it is show to the user.
HELP A slightly
longer (a paragraph or two at most) description that
is displayed when the user clicks the Help button in
the generic FrontPage Component Properties dialog.
Extra white space and new lines are removed from the
help string before it is shown to the user. To force
a new line, put \n in the string. Use \\ for a single
back-slash.
Reserved BTL attributes
BTL Data Type Encoding

Component attributes that are user-editable should
begin with a letter that specifies the data type of
the attribute's value, followed by a dash. For example,
an integer parameter named count would be represented
as "I-Count=23".
The main data types supported by the generic FrontPage
Component Properties dialog are: 

CODE DATA TYPE
I Integer
S String
B Boolean (TRUE or
FALSE)
D Date (in RFC-1123 format)
U URL (a reference
to a document in the same web)
C Color (in HTML hexadecimal
format: "#ff00ff")
Basic data types supported by the
generic FrontPage Component Properties dialog

When attribute names are displayed to the user, the
leading data-type letter and dash are removed, and
dashes are converted to spaces. For example, I-Maximum
Matches becomes "Maximum Matches."

There are three additional attribute name prefixes
which change the way a value is modified with the generic
FrontPage Component Properties dialog: MIN-, MAX-,
and RADIO-. 

The prefixes MIN- and MAX- allow the component to specify
a range of legal values for integer attributes, and
a minimum and maximum length for string attributes.
For example, the component could contain:

I-COUNT=10 MIN-COUNT=0 MAX-COUNT=255

The prefix RADIO- allows the component to specify that
a parameter represents a one-of-many choice. Each subsequent
RADIO- modifier supplies another legal value for that
parameter. For example: 

S-FLAVOR="Vanilla" RADIO-FLAVOR="Vanilla" RADIO-FLAVOR="Chocolat
e"

Any other attributes which encode the persistent state
of the component but are not user-editable must not
have a dash anywhere in their name.


The Custom FrontPage Component Implementation File


A custom FrontPage component implementation file is
either a dynamic link library, a shared library, a
stand-alone program, or a script. It can contain software
implementing one or more components.

A custom component implementation is analogous to a
CGI script. The component's procedure is given three
sets of name-value pairs:

the component attributes dictionary
the CGI environment dictionary
the form variable dictionary

Based on this information, the component must return
some HTML representing a page fragment or an entire
page.

A component can be implemented with a single procedure.

When using the Standard I/O interface, this procedure
is called implicitly by invoking the executable. A
Standard I/O component implementation reads the dictionaries
from its standard input and writes HTML to its standard
output.

When using the DLL or shared library interface, you
must export a single entry point named Xxx_Expand,
where Xxx is the shortname of the component, exactly
as specified (including case) in the component description
file.
Types of Custom FrontPage Components

The custom component API supports two types of components,
as indicated in the component definition file:

Insert components, which replace themselves with some
HTML. The SmartHTML interpreter expands Insert components
at authoring time, or at browse time if the page is
fetched dynamically using a URL like _vti_bin/shtml.dll/webpage.
htm.
The component is replaced in the output page with the
HTML it generates.

Form components, which handle the submission of HTML
form data. SmartHTML expands Form components at authoring
time, but they typically do not generate HTML at that
time. Instead, they wait until receiving a POST request
(which they detect because the attribute Method is
set to Evaluate) and typically generate an entire HTML
page or redirect to a different URL.

The Insert components will appear in the Insert: FrontPage
Component dialog box. The Form components will appear
in the Form Properties dialog box, in the drop-down
list inside the Form Handler group box.
Determining Why the Component Was Activated 

The component attributes dictionary contains six extra
synthesized state variables, in addition to the component's
own state variables. They tell you why the component
was activated, and give you information about the location
of the page.

The Method attribute is used to tell Form components
they are being awakened as a result of a HTTP POST
method from their own form.

If Method = Expand, then the component should generate
its appearance consistent with an HTTP GET request.

If Method = Evaluate, then the component should interpret
the form data submitted by the HTTP POST request and
generate the appropriate results. 

The Parse attribute can be used to determine if the
page is going to be cached or not.

If Parse = Static, the page is either being saved from
the FrontPage Editor or regenerated due to a dependency
change
If Parse = Dynamic, the page is either handling a form
submission or being fetched dynamically with a URL
like _vti_bin/shtml.exe/webpage.htm.

The PageURL attribute provides the web-relative URL
of the page on which the component lives.

The DocumentRoot attribute provides the absolute path
to the web's root directory on the local file system.
This path uses the local filesystem convention for
path separator characters, so on a Windows system it
will use a backslash ("\") instead of the forward-slash
("/") used in URLs.

The WebURL attribute provides the absolute URL of the
web. 

The BaseDocURL attribute is new for FrontPage 98; it
provides the web-relative URL of the outer-most containing
page in which the component is being expanded. This
information is useful when the page where the component
lives is included inside another document. For example,
if a FrontPage component is defined in the top border
page of a FrontPage 98 web and then the page "test.htm"
that includes the top border is saved, the component
will be expanded with PageURL set to "_borders/top.htm"
and BaseDocURL set to "test.htm".
Generating MIME Headers

The HTML generated by the component can be preceded
with some optional MIME headers, which control how
the resulting HTML is interpreted by the FrontPage
Server Extensions. Each header is terminated by a single
newline character ("\n"). Indicate the end of all headers
with a blank line, so there are two newline characters
("\n\n") in a row. 
All headers are optional. Normally any HTML generated
by the component is inserted in-line into the page
at the point where it occurs.

You can change this behavior with one of the following
types of headers:

header INterpretation
Content-type: MIME-type Causes
the current SmartHTML page to be replaced with the
entire result page following this header.
Location:
some-URL Causes the current page to be replaced with
the referenced page. The SmartHTML program starts interpreting
the some-URL page if it is in this web, or else causes
the browser to fetch some-URL. This only works for
a dynamically-accessed page (Parse=Dynamic).
Redirect:
some-URL Works just like the Location header, but if
some-URL is absolute (as in http://myweb/mypage.htm),
it causes the browser to fetch it directly instead
of going through the SmartHTML program.
Links: url
list A space-separated list of URLs to which this component
generates links. If any of the pages in the Links list
contain spaces, they must be URL-encoded. For example,
"my page.htm" should be output as "my%20page.htm".
This information is used by the FrontPage Explorer's
Link View and the FrontPage Table-of-Contents component.

WriteLinks: url-list If you set any write links, the
FrontPage Server Extensions will set the permissions
for this file so that Web browsers can write to the
file. This allows the component to update the file
when used dynamically (for example, a FrontPage Form
Results component).  Also, files specified in the WriteLinks:
mime header for a component are now treated as ancillary
files. Such files will be deleted if the page containing
the component is deleted, moved if the page containing
the component is moved, etc. 
Error: Error-string Components
can already specify mime headers to communicate certain
information. Now they can specify a new mime header,
"Error:", which causes FrontPage to mark the component's
page as containing an error. In the FrontPage Explorer's
Hyperlinks view, this results in a red-triangle image
that appears in front of the page name. Right-clicking
for properties on this page displays a dialog that
displays the error string as specified by the component.

It is important to understand the difference between
the static and dynamic versions of a page in a FrontPage
web in order to use the redirection options availabe
with the Location and Redirect headers. The static
version is exactly as the page appears on disk; the
dynamic version has its FrontPage components expanded
when the page is fetched and a newly-generated page
is returned to the browser. The static version of a
page is fetched with a normal absolute or relative
URL, such as "http://myweb/mypage.htm" or "mypage.htm".
The dynamic version of a page is fetched through the
SmartHTML interpreter with a special dynamic URL prefix,
such as "_vti_bin/shtml.dll/mypage.htm".
The dynamic URL prefix comes in two flavors, depending
on the web server. The prefix is either "_vti_bin/shtml.dll/"
or "_vti_bin/shtml.exe/". 

There are three page redirection options available
to a FrontPage component: 

Use the Location header to return the dynamic version
of another page in the web by restarting the SmartHTML
interpreter on another page in the web. The second
page will be expanded with the same form data (if any)
and CGI dictionary as the first page. If the second
page contains a form with form handler FrontPage components,
they will respond just as if the form had been submitted.
Use the Redirect header to get the browser to fetch
the static version of another page in the web. You
must supply an absolute URL to the static version.

Use the Redirect header to get the browser to fetch
the dynamic version of another page in the web. Supply
a relative URL to get the dynamic version.
Clientside Components

FrontPage 98 introduces a new reserved attribute, "CLIENTSIDE",
to designate components that have no server-side expansion.
Instead of expanding on the server at save-time or
browse-time, a clientside component generates its expansion
at edit-time when the FrontPage Editor calls the component's
edit() function.  To accomplish clientside expansion,
the component uses three other reserved attributes.

Using the "S-HTML" attribute, a client-side component
can specify the exact HTML that will appear between
its startspan and endspan in the final saved page.
This can be combined effectively with the existing
"PREVIEW" attribute to display one block of HTML while
the component is viewed in the editor, and an entirely
different block of HTML when viewed in the browser.


For instance, an ASP-based component might want to
display a pretty version of its name and logo while
the user is editing the page, but be interpreted as
real ASP code once the page is browsed.  If it declares
itself to be a clientside component, it can use the
PREVIEW attribute to specify the name and logo, and
the S-HTML attribute to specify the ASP code.  

Finally, with the addition of the Preview tab to the
FrontPage Editor, components have a third environment
in which they may want to expand differently.  Using
the "LOCAL_PREVIEW" attribute, a clientside component
can specify distinct HTML for substitution when the
user views the page from the Preview tab.  In the example
above, since the component's ASP code won't be interpreted
before the Preview tab is rendered, the component may
want to use LOCAL_PREVIEW to insert a reasonable facsimile
of its final output and/or a warning message that the
preview is not wholly accurate.

The following table outlines the clientside reserved
attributes:

ATTRIBUTE MEANING
CLIENTSIDE This attribute has no
right-hand-side value.  If present, it indicates that
the component has no server-side expand function, and
that the S-HTML, LOCAL_PREVIEW, and PREVIEW attributes
should be used instead.
S-HTML The value of this attribute
specifies the HTML to be used when the component is
written to a page.  
LOCAL_PREVIEW The value of this
attribute specifies the HTML to be used when the editor
is on the Preview tab.  If the S-HTML attribute does
not exist, this value is also used when saving the
component to a file.
PREVIEW The value of this attribute
specifies the HTML to be used when the editor is displaying
the Normal tab.  If the LOCAL_PREVIEW attribute does
not exist, this is also what is used on the Preview
tab.  If neither the S-HTML or the LOCAL_PREVIEW attributes
are present, this is also is what is written to the
file.

Additional Reserved Attributes

In addition to the clientside reserved attributes describe
above, FrontPage 98 introduces two other attributes
that can be used to alter the behavior of a component.

ATTRIBUTE MEANING
PageAspPrefix Whenever a component
wants to insert ASP at the very beginning of a document
(not in the middle of the page, where the component
itself resides), it can use this reserved attribute
to specify that block of ASP code. 

ASP prefixes appear at the top of the document in the
same order as the components which generated them appear
in the body of the document (so multiple PageAspPrefix
using components can appear on the same page). FrontPage
98 keeps track of all the ASP prefixes it is responsible
for by inserting a special comment into the ASP code
that begins with ' FP_ASP.  Also, if not already present,
<% and %> are added before and after the ASP provided
in the attribute.  

The PageAspPrefix attribute is only checked when the
component returns from its server-side expand( ) function,
and once the attribute is read and the ASP is inserted
at the top of the page, the attribute is stripped out
of the component's attribute list. This means that
the PageAspPrefix attribute never actually appears
in the component's WEBBOT syntax.  It also means that
the component's expand( ) function must add the attribute
each time it returns, or else the ASP will not be regenerated.
Note that the ASP-code referred to by PageAspPrefix
must start with <%newline, or the prefix becomes wrapped
in <%newline and %>.
SuggestedExt When a component
is inserted into a page, it can request that the FrontPage
Editor use a particular file extension when the page
is saved by using the SuggestedExt attribute. If the
page has not yet been saved, the FrontPage Editor will
use this attribute to propose a file extension in the
SaveAs dialog.  If the page has already been saved
with a different extension, the Editor will pop up
a message instructing the user how to change the file
extension. SuggestedExt is particularly useful when
a component relies on a technology that requires a
certain file type extension, such as ASP.

DLL and Shared Library Implementation

In the DLL and shared library implementation, the component's
Expand method is passed opaque pointers to dictionary
and string objects, and a pointer to an array of functions
for accessing and manipulating them. You must include
the file "webbot.h" to obtain definitions for these
types.

The Expand method's interface is as follows:

void Xxx_Expand (
WebBotString* retString,
WebBotDict*   botAttributes, 
WebBotDict*   cgiEnvironment,
WebBotDict*   formData,
WebBotFuncs*  funcs )

The file "webbot.h" defines two in-line C++ classes,
CWebBotDict and CWebBotString, for easy access to WebBotDict
and WebBotString parameters:


class CWebBotDict
{
CWebBotDict(WebBotDict* dict,const WebBotFuncs* funcs);
// Constructs a new CWebBotDict from a WebBotDict.

long NumValues(const char* key);
// Returns number of values for this key.

const char* GetValue(const char* key);
// Returns a string value for a particular key. 

const char* GetValueN(const char* key, short ValueNum);
// Returns the nth value of a multi-valued key
(or the only value of a single-valued key).

const char* NextKey();
// Returns the next key in the dictionary.
      // Returns 0 when the end is reached. 

void SetValue(const char* key, const char* value)
// Sets the string value for a particular key.  If
the key 
// has more than one value, it sets the first (0th
) value.

void SetValueN(const char* key, const char* value,
short valueNum)
// Sets the valueNum'th string value for a particular
key.

void RemoveKey(const char* key)
// Removes the key, + all associated values, from the

// dictionary

void Reset();
// Resets the iterator to the beginning.
}

class CWebBotString
{
CWebBotString(WebBotString *string, WebBotFuncs *funcs);
// Constructs a new CWebBotString from a WebBotString.

void Clear();
// Resets the string so it is empty.

void Append(const char* stringToAppend);
// Appends a C string to the string.

const char* GetContents(WebBotString* string);
// Gets the contents of the string as a C string
}

There can be more than one value for a given key. Use
the DictGetValueN and DictSetValueN methods to take
advantage of this. Note, however, that there is no
guarantee that the order of the entries for a given
key will remain the same between calls to the Edit
or Expand methods of a FrontPage component DLL. That
is, what used to be the first value of a key could
get swapped with the second value for the key between
calls to the FrontPage component DLL.

The file "webbot.h" defines a pair of macros, BeginWebBotExpand
and EndWebBotExpand, that simplify the process of defining
an Expand method. BeginWebBotExpand takes five names
as arguments:

the shortname of the component (as in botname_Expand)
the name of a CWebBotString variable where you will
append your HTML
the name of a CWebBotDict variable holding the component's
attributes
the name of a CWebBotDict variable holding the CGI
environment
the name of a CWebBotDict variable holding the form
variables (if any)

A very simple "hello" WebBot component can be implemented
in C++ as follows:

#include "stdio.h"
#include "../webbot.h"

BeginWebBotExpand(hello,ret,bot,cgi,form)
{
  ret.Append("<H1>Hello, WebBot World!</H1>");
}
EndWebBotExpand

For a C language component implementation, you can
manipulate the strings and dictionaries using syntax
like funcs->MethodName.

The methods provided by the WebBotFuncs structure are
as follows:

long DictNumValues(WebBotDict* dict, const char* key);
const char* DictGetValue(WebBotDict* dict, const char*
key);
const char* DictGetValueN(WebBotDict* dict, const char*
key, short valueNum);
void DictReset(WebBotDict* dict);
const char* DictNextKey(WebBotDict* dict);

void StringClear(WebBotString* string);
void StringAppendTo(WebBotString* string, const char*
stringToAppend);
const char* StringGetContents(WebBotString* string);
void DictSetValue(WebBotDict* dict, const char* key,
const char* value);
void DictSetValueN(WebBotDict* dict, const char* key,
const char* value, short valueNum);
void DictRemoveKey(WebBotDict* dict, const char* key);

The FrontPage component API also supports components
which can execute on the client side. If the .inf file
describes the component as having clientbinding=DLL,
then the clientmodule is a DLL which will be downloaded
to the client and executed. The FrontPage Editor displays
a dialog warning that a download is about to occur
and giving the user an opportunity to cancel. If the
user tries to edit a component that is not defined
for the current web, or if the FrontPage Explorer is
not running or has no current web open, then the FrontPage
Editor will use the generic FrontPage Component Properties
dialog instead of the custom dialog.

The client-side interface is similar to the server
side interface. A set of opaque pointers is used to
pass information from the FrontPage Editor to the FrontPage
component. You must include the file "webbot.h" to
obtain definitions for these types.

The Edit method's interface is as follows:

int Xxx_Edit(
    WebBotDict*    botAttributes,
    WebBotFuncs*  funcs
     )

The botAttributes argument is a dictionary of all of
the component attributes. This will be empty if the
user is inserting a component, but will contain the
attributes which were previously added to the dictionary
by the component if the user is editing a component
which was already inserted. The Edit function should
return zero if the user hits cancel, and non-zero otherwise.

The CWebBotDict class, defined in webbot.h and described
earlier in this section, may be used in the Edit method
as well as the Expand method. The file "webbot.h" defines
another pair of macros, BeginWebBotEdit and EndWebBotEdit,
that simplify the process of defining the Edit method.
BeginWebBotEdit takes two names as arguments:

1. the shortname of the component (as in botname_Edit)
2. the name of a CWebBotDict variable holding the component's
attributes

For a C language implementation, you can manipulate
the strings and dictionaries using syntax like funcs
>MethodName. The same functions are available through
the WebBotFuncs structure as described in the Expand
method.

When a FrontPage component is first instantiated, either
from the Insert: FrontPage Component dialog or the
Form Properties dialog, its attribute dictionary is
empty. 
Since there is no BTL file for client-side DLL components,
the component must add any required attributes, including
PREVIEW and TAG keys, to the botAttributes dictionary
when the Edit method is called for the first time.
The purpose of these keys is described earlier, in
the documentation for the BTL file format. The only
difference is that the PREVIEW string does not need
to have <, >, and & characters escaped in the Edit
method. An easy test to find out if the component is
being created for the first time, rather than modified,
is to see if botAttributes.NextKey returns NULL at
the start of the Edit method. This test will fail once
you have added some attributes to the component.

A very simple "hello" component can be implemented
in C++ as follows:

#include "../webbot.h"

BeginWebBotEdit(hello, botAttributes)
{
  botAttributes.SetValue("PREVIEW", "<H2>Hello World!</H2>");
  botAttributes.SetValue("TAG", "H2");
  return 1;
}
EndWebBotEdit

The major advantage to using client-side DLLs for FrontPage
components is that the component can implement any
kind of property-editing dialog box it requires. This
means you're not just limited to the generic FrontPage
Component Properties dialog. You get much greater flexibility
on the client side to perform selection actions, such
as browsing the local hard drive for files, or displaying
a custom color selection dialog box. Another advantage
is that the PREVIEW key is generated at run-time, allowing
a component to create a much better approximation of
the final output. Note that the same DLL file may be
used for the client and server side routines.
Example: Creating a client-side DLL

Here is an example to show you how to create a simple
client-side DLL which displays a simple dialog box.
This example uses Microsoft Visual C++ and MFC.

Start Microsoft Visual C++. From the File menu, choose
the New option, and select Project Workspace. From
the New Project Workspace dialog, choose the MFC AppWizard
(dll) option. Name the project "simple". 
Click the "create" button. Choose either an MFC shared
DLL or an extension DLL.
Create a new dialog box resource for the component.
Add controls to the resource as desired. For instance,
Ok and Cancel buttons and an edit field
Derive a class from the dialog resource using ClassWizard.
Name the class "CSimpleDialog". Attach a value member
variable called "m_edit" to the edit field using the
classwizard.
Copy the file webbot.h from the SDK into the project
directory
Add the following lines to the top of simple.cpp:

#include "simpledialog.h"
#include "webbot.h"

Add the following function to simple.cpp:

BeginWebBotEdit(simple, botAttribs)
{
  CSimpleDialog dlg;
  dlg.m_edit = botAttribs.GetValue("PREVIEW");
  int nResponse = dlg.DoModal();
  botAttribs.SetValue("ExpandTo", dlg.m_edit);
  botAttribs.SetValue("PREVIEW", dlg.m_edit);
  return (nResponse == IDOK);
}
EndWebBotEdit

Add the following function to make the DLL also be
a server-side custom FrontPage component DLL. If you
don't add this function, you will need to make a BTL
file which expands the "ExpandTo" key to be the resulting
HTML text for the component, and set the serverbinding
in the .inf file to be BTL.

BeginWebBotExpand(simple,ret,botAttribs,cgi,form)
{
  ret.Append(botAttribs.GetValue("ExpandTo"));
}
EndWebBotExpand

Select the Win32 Release target from the drop-down
menu on the toolbar and compile the DLL.
To do local testing, create c:\Program Files\Microsoft
FrontPage\bots\simple (that is, create a bots\simple
directory under wherever the FrontPage root directory
is on the local machine) and copy the newly created
DLL into that directory. Later, when the component
is ready for release, it should be made platform independent
and placed on the server in the root web/_vti_bot/botname
directory
Create a simple.inf file in the same directory, using
the examples as a guide. Be sure to set the clientbinding
and serverbinding keys to DLL. Set the "type" to "insert".
Run the FrontPage Explorer. From the FrontPage Explorer's
Tool's menu, choose Recalculate Links. Your component
should now show up in the Insert : FrontPage Components
listbox in the FrontPage Editor.
Select the Simple Bot. It will prompt you to download
the component into the botcache directory. After downloading,
the simple component will display its dialog. Enter
some text into the edit box and click okay. The preview
string contains the text that was entered.

This sample component (including a simple.inf file)
can be found in the SDK's WebBot\simple folder.

IMPORTANT: If your component requires any DLLs, be
sure to include them with the component setup so that
they can be installed on the system. FrontPage 98 ships
with MFC 4.2 DLLs, but in general, you need to make
sure that you provide any necessary DLLs that might
not be included with FrontPage itself. For this reason,
you should make sure that you only install Win32 Release
builds of your component, particularly if you use the
Microsoft Foundation Classes (MFC). If you use the
same module on both the client and server, and you
require additional libraries, you are responsible for
installing them on both the client and server machines.

Standard I/O Implementation

The Standard I/O component implementation is designed
for creating server-side expand methods in any of several
scripting languages on UNIX-based servers. You could
implement a Standard I/O component using a compiled
program, but a dynamically linked library will be much
more efficient. The Standard I/O implementation option
is not available for servers running under Windows
95 or Windows NT, and it can only be used to implement
the server-side expand method, and not the client-side
edit method.

The Standard I/O implementation is designed to be as
similar to traditional CGI programs as possible. Data
is passed to a Standard I/O component in two ways.
The CGI environment variables are passed via the process'
environment. The other two dictionaries (the component
attributes and the form variables) are merged into
a single dictionary, and passed to the component implementation
via the process' standard input file in WWW-FORM-URLENCODED
format. This is the same format expected by any standard
CGI script that expects to handle form submissions.
The standard output file is used to return the generated
HTML.

If you want to create a component in a scripting language
besides Perl and Tcl (the languages used in the FrontPage
SDK examples), you need to make sure that it supports
standard I/O, and you need to create a procedure that
parses form data from the standard input file into
internal data structures. There are many examples of
such routines for other languages available on the
Internet.

In order to allow the component implementation program
to separate the merged name-value pairs into separate
dictionaries, all component attribute names are prefixed
with the string "_BOT_". Form variable names are not
modified. The _BOT_ prefix is a feature of the Standard
I/O binding, and is never used with the DLL binding.


To implement multiple components in a single script
or program, your main procedure should examine the
custom component variable _BOT_bot, which contains
the component's shortname. You can then switch processing
to a component -specific expand procedure based on
this value.

Creating Custom FrontPage Component Libraries

Windows Systems

On Windows NT and Windows 95 systems, you can create
a custom FrontPage component DLL using C or C++ with
Microsoft Visual C++ (32-bit). Perform the following
steps:

Create a directory called bots to the main directory
for FrontPage. By default this should be "C:\Program
Files\Microsoft FrontPage". This will make the new
component available to all FrontPage webs hosted on
your machine.
Copy the contents of the WebBots directory from the
FrontPage SDK distribution into bots directory for
FrontPage. All of your custom component project directories
should be inside the bots directory.
Start Microsoft Visual C++. From the File menu, choose
the New option, and select Project Workspace. From
the New Project Workspace dialog, choose the Dynamic
Link Library option. Press the Browse button next to
the Location field, and select the bots directory under
the main FrontPage directory. Put your new component's
shortname (botname) in the Project Name field and press
Create.
Open a C++ source file from one of the component examples,
such as wbtest2.cpp, and save it into your project
as botname.cpp. You may need to use the Insert: Files
into Project option. Modify the source so it uses the
shortname for your component. 
Select the Win32 Release target from the drop-down
menu on the toolbar. Open the Build Settings property
sheet. Go to the Link tab. Change the Output file name
from Release/botname.dll to botname.dll. Now use the
menu option Build botname.dll.
Create the component description file (botname.inf)
and the component template file (botname.htm), using
the earlier SDK examples as a guide.
From the FrontPage Explorer's Tools menu, choose Recalculate
Hyperlinks. Your component should now show up in the
FrontPage Editor's Insert : FrontPage Component dialog.
UNIX Systems

On most UNIX systems, you can build a shared dynamically
loadable library using C or C++ with the vendor's compiler
or with the GNU C Compiler (gcc). Often the most difficult
problem is figuring out the correct flags to pass to
the compiler and linker. For example, on Solaris, your
Makefile should add the flag "-PIC" to the CFLAGS variable
and the flags "-nostdlib -shared" to the LDFLAGS variable.
Some compilers may require you to translate the newline
characters in webbot.h to the UNIX convention of "\n"
(LF) instead of "\r\n" (CR-LF).

Common Problems 

Incorrect Name Linkages

You must follow these rules with regard to name linkages
inside a component directory:

The name of the info file must match the directory
it is in (foo.inf in component directory foo).
The components implemented in the directory are identified
by the list keyword in the info file.
The component's implementation file is identified by
the servermodule keyword in the info file.
The component's template file containing BTL is identified
by the clientmodule keyword in the info file.
A particular component's template is identified by
its BOT attribute inside the template file.

For example, a typical component directory called mybots
with two custom components might contain:

mybots.inf - component description file (one file for
all components in this directory)
mybots.btl -- contains BTL templates for both components
bot1.dll -- implementation for a component called bot1
written in C or C++
bot2.pl -- implementation for a component called bot2
written in Perl

Incorrect File Access Permissions

All the directories and file must be accessible by
the FrontPage user account (the user account used to
run CGI scripts).

Cached FrontPage Component Information Out of Date

If you add new components during a FrontPage editing
session, you must perform a Recalculate Links operation
to update the client-side cache. Normally this is done
from the FrontPage Explorer's Tools menu. However,
the FrontPage Server Administrator also supports the
Recalculate Links request from the command line interface.
The extensions build a private registry of custom components
containing an aggregation of the important facts from
the bots and/or _vti_bot directories. This registry
is stored in a string in a file named _vti_pvt/bots.cnf
in the Root Web's content directory. 

Every time you update a FrontPage component's implementation
on the server, you must increment the version number
in the corresponding .inf file and Recalculate Links
in the web. Otherwise clients will keep using earlier
versions of the component in their local cache (in
the 'botcache' directory under the FrontPage installation
directory). 

Errors Detected by FrontPage Explorer or Server Extensions

If a page references an unrecognized component on a
page in the web, a red triangle ("page contains errors")
will display in the Outline View of the FrontPage Explorer
next to the page entry. Select the page, perform an
Edit : Properties operation, and see the Error tab
for more information.

Run-time errors on Windows 95 are written to C:\FrontPg.log.
Run-time errors on Windows NT can be viewed in the
Event Viewer. On UNIX, run-time errors are logged with
the syslog facility. On Solaris, for instance, these
messages are typically saved to the file /var/adm/messages.
Common run-time errors include the name linkage problems
discussed above.
Sharing Conflict While Installing New FrontPage Component
DLL

FrontPage components with server-side DLL implementations
on Windows-based Web servers may not be able to overwrite
the DLL since the file can be in use and locked by
the web server. For efficiency reasons, the Microsoft
Internet Information Server (IIS) and the Microsoft
Personal Web Server (MSPWS) do not free extension libraries
that they load. This is very important for high-volume
services that want to avoid reading libraries from
disk every time a page is fetched or a form submitted.
However, if you are in the process of developing FrontPage
component libraries, it means you must keep stopping
and restarting the web server every time you need to
install a new version so you can test it. 

On IIS, this is accomplished from the Internet Service
Manager control application on the Microsoft Internet
Server group located on your Start menu. Note that
all services, included WWW, FTP, and Gopher, must be
stopped in order for the libraries to be freed. 
On MSPWS, this is accomplished from the Control Panel
item Personal Web Server. On the Services tab, select
the HTTP service and push the Stop button to halt the
server. To restart it, select the HTTP service and
push the Start button.

There is an alternative for development machines to
avoid stopping and restarting these servers all the
time. You can set a Windows Registry value that tells
these servers to load and unload extension libraries
with each request. Under the HKEY_LOCAL_MACHINE tree,
the key is:

\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\CacheExtensi
ons

If you set the value of this key to 0, and then stop
and restart the server, extension libraries will no
longer be cached. To set the server back to normal
behavior, set the key to 1 (or simply remove it), and
then stop and restart the server.

      

  -  -

Copyright c 1997 Microsoft Corporation

Table of Contents      

Introduction

Example Files

Menu Customization

Designer HTML

Templates

Wizards      

OLE Automation Overview

FrontPage( Explorer Automation    FrontPage.Explorer

FrontPage Editor Automation    FrontPage.Editor

FrontPage( To Do List Automation    FrontPage.ToDoList

Custom WebBot( Components



































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































