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.
MENU CUSTOMIZATION.......................................................................................Customizing the FrontPage Explorer...............................................................................
Adding New Menus.....................................................................................................Adding New Commands..............................................................................................
Customizing the FrontPage Editor..................................................................................
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 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 TO DO LIST AUTOMATION...........................................................vtiShow...........................................................................................................................vtiHide............................................................................................................................vtiAddTask.....................................................................................................................vtiGetActiveCount..........................................................................................................vtiCompletedTaskByUrl.................................................................................................vtiWorkedOnTaskByUrl.................................................................................................vtiAddTaskAskUser........................................................................................................
HTML Representation of FrontPage Components........................................................Activating a Custom FrontPage Component................................................................Editing Custom FrontPage Component Attributes.......................................................Custom FrontPage Components...................................................................................
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.......................................................................................
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............................
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 ChangesThe 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.”
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
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:
1. directly in the registry entry2. 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:
Argument Descriptionfirst_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.
Argument Descriptionfirst_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 HTMLDesigner 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:
1. The ability to specify an alternate display in the Editor for a piece of unknown HTML
2. 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 ExamplesTo 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.
[## 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
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!
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]\pagesWeb several interconnected pages [FrontPageRoot]\websFrameset 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:1. Launch the Web Template Maker (webtmpl.exe in the utility\webtmpl folder)2. Select from the Available Webs list3. Enter the New Web Template information4. 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 dialogdescription=long description of the purpose of the framesetlayout=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:
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:
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 Pagedescription=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 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.
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=MicrosoftCompanyAddress=One Microsoft Way, Redmond Washington
The TaskList Section
You can upload some tasks for the FrontPage To Do List using items in the optional [TaskList] section. A task consists of six attributes:
1. TaskName2. Priority (1 to 3)3. CreatedBy4. URL5. Cookie6. Comment
These attributes are encoded in each line of the [TaskInfo] section as follows:
TaskNum is a unique key, such as ‘t01’, ‘t02’, etc. Task attributes are separated by vertical bar characters (‘|’).
TASK ATTRIBUTE DESCRIPTIONTaskName a short phrase, typically 3 or 4 words, telling the user what to doPriority an integer, where 1=High, 2=Medium, and 3=LowCreatedBy the name of the template creating the taskURL the page or image the task refers to, such as news.htm or logo.gifCookie an additional identifier for a point within the target URL;
currently limited to HTML bookmarks, specified as #bookmarkComment a few words describing in detail what needs to be done; cannot
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.
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:
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”.
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 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.
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:
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:
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 ColorsWhen 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 GraphicsWhen 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 ImageAdding 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
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.
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.
FontsUnlike 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 size1 8pt Text Heading 62 10pt Text Heading 53 12pt Text Heading 44 14pt Text Heading 35 18pt Text Heading 2
6 24pt Text Heading 1
7 36pt
TextWhen 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.
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, HelveticaArial Black Arial Black, Arial, HelveticaArial Rounded MT Bold Arial Rounded MT Bold, Arial, HelveticaBook Antiqua Book Antiqua, Times New Roman, TimesBookman Old Style Bookman Old Style, Times New Roman, TimesBrush Script MT Brush Script MT, Arial, HelveticaCentury Gothic Century Gothic, Arial, HelveticaCentury Schoolbook Century Schoolbook, Times New Roman, TimesComic Sans MS Comic Sans MS, Arial, HelveticaGaramond Garamond, Times New Roman, TimesHaettenschweiler Haettenschweiler, Arial, HelveticaImpact Impact, Arial, HelveticaTimes New Roman Times New Roman, TimesTrebuchet MS Trebuchet MS, Arial, HelveticaVerdana 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 OverlaysNone 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.
TransparencyThe 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-aliasingIf 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 PaletteAll 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 FilesThere 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 FileThe 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:
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 DescriptionDecorative 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.
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.
SetupTo 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 ThemeThe 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 OptionsUsing 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 PropertiesWhile 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 ThemeWhen 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 ThemesThe 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 UsersYou 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.
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.
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++:
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.vtiRefreshWebFromServerSet 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.
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”.
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.
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 vtiPutDocuments to upload several files at once.
This can be a blocking or non-blocking call depending on the BlockingRequest parameter. Currently there is no way to determine when a non-blocking request has completed.
Return Value
The return value is currently 1 for success and 0 for failure, but this may change to include other status codes in the future.
Parameters
FileName is the absolute path to a file on the local file system. It can be an ASCII or binary file. In Visual Basic, you typically place “App.Path” and “\” into a string before adding the name of a file in the current directory. Example: “C:\test\index.htm”.
URL is what you want the file to be named in your web. You can use “8.3” filenames to be safe; otherwise, you’ll need to use vtiGetWebMetaInfo to examine the filename conventions on the web server. The parameter can contain “/”characters to refer to web subdirectories, as long as they exist in the web. Valid subdirectories are “images” and “_private” or other user-created folders. Examples: “index.htm”, “images/logo.gif”.
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\nfax:555-1212”.
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 vtiSetWebRecalcDependencies with vtiPutDocument. The vtiPutDocuments method will automatically turn off dependency updating when it begins uploading documents and on again when it finishes.
Using vtiSetWebRecalcDependencies is discouraged, since if you accidentally leave recalculation turned off, authors will perceive the web as being broken. Selecting the Recalculate 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.
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:
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 foundF referenced URL is a fileS referenced URL is an executable scriptW 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 HREFB link is a FrontPage component-generated HREFC link is a FrontPage Table of Contents generated HREFA 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 pageF link is a frame SRC attribute (in <FRAME> construct)D link is a data source, such as for script codeK link is a bookmarkU link is of an unknown type
2: link security U unknown; always set to ‘U’ in FrontPage 1.1H HTTP protocolS SSL protocolT SHTTP protocol
3: link method S static; always set to ‘S’ in FrontPage 1.1D dynamic; link to page through SHTML program or library
As an example, the link information for a page might be as follows:- 60 -
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”.
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.
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 (“/”).
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.
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”.
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:
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”)
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 TYPE0 All pages1 HTML pages2 Images (currently, those with the extensions .GIF, .JPG, or .JPEG)3 Video files4 Executable files5 Sound files6 Database files7 HTX files 8 PowerPoint animation files9 CDF files
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”.
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.
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.
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.com/”, “logo.gif”.
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”.
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”.
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.
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 TYPE0 All pages1 HTML pages2 Images (currently, those with the extensions .GIF, .JPG, or .JPEG)3 Video files4 Executable files5 Sound files6 Database files7 HTX files 8 PowerPoint animation files9 CDF files
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.
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.
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.
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.
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.
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 failure1 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://microsoft: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 MEANING1 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 = 1000App.OleRequestPendingMsgTxt = “PublishWeb in progress. Please be patient.”
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.
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 failure1 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.
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 supported1 if supported
Parameters
Feature is a string describing the feature being tested. Possible values are:
KEY MEANINGvti_ServerEmailTransport Web server is configured to send e-mailvti_ServiceStructureStore Web supports reading and storing navigational
structure informationvti_ServiceThemes Web supports themesvti_ServiceMarkUrlDirExec Web supports making a directory executablevti_ServiceMarkUrlDirBrowse Web supports making a directory browsablevti_ServiceMarkUrlDirScript Web supports making a directory scriptable
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”
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 failure1 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.
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 failure1 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”.
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 failure1 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:
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 RELATIONSHIP0 Nodes on level above given page (all siblings of its Parent node)1 Child nodes for given page2 Sibling nodes of given page (includes given page at appropriate
position in list)3 Next sibling node of given page4 Previous sibling node of given page5 Top-level pages for current web (includes home node at appropriate
position in list)6 Home node for current web7 Parent node for given node8 Self (returns info for given node)9 Home, Up, Previous, and Next nodes (in that order) for given node;
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.
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 failure1 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.
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.
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 – successFalse – 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”.
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:
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”.
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”.
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”.
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.
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.
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 to0 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.
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:
1. Addin is invoked from a custom menu command2. A dialog is presented to get user input3. 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 exist1 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)
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 exist1 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)
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.
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 failed1 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.
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.
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.
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 - success0 - 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:
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.
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 - success0 - 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.
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.
FrontPage To Do List Automation FrontPage.ToDoList
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.
FrontPage To Do List Automation FrontPage.ToDoList
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.
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”.
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”.
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:
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.
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.
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.
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:
[ComponentTwo]name=New Component Twodescription=something or othertype=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.
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.
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:
[HitCounter]name=Hit Counterdescription=Adds a hit counter to your pagetype=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 " & and > 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:
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 MEANINGNAME 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="<H2>Test Bot</H2>".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:
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 INTERPRETATIONContent-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:
1. 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.
2. 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.
3. 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.
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
CLIENTSIDEThis 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-HTMLThe value of this attribute specifies the HTML to be used when the component is written to a page.
LOCAL_PREVIEWThe 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.
PREVIEWThe 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
PageAspPrefixWhenever 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 %>.
SuggestedExtWhen 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 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:
1. the shortname of the component (as in botname_Expand)2. the name of a CWebBotString variable where you will append your HTML3. the name of a CWebBotDict variable holding the component’s attributes4. the name of a CWebBotDict variable holding the CGI environment5. 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:
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:
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.
1. 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”.
2. Click the “create” button. Choose either an MFC shared DLL or an extension DLL.3. 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 field4. 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.
5. Copy the file webbot.h from the SDK into the project directory6. Add the following lines to the top of simple.cpp:
8. 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.
9. Select the Win32 Release target from the drop-down menu on the toolbar and compile the DLL.
10. 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
11. 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”.
12. 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.
13. 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.
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:
1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. Create the component description file (botname.inf) and the component template file (botname.htm), using the earlier SDK examples as a guide.
7. 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).
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:
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.
