Previous Page TOC Next Page



26


Creating Your Own Wizards


by William Robert Stanek

Wizards aid the content development process for pages and Webs. Unlike templates, which are based on HTML documents and parameter files, wizards are programs that run on your system and use OLE to interface with FrontPage.

Before you create wizards, you should learn the basics of programming and OLE automation. This chapter does not examine these basics. Instead, the chapter focuses on the specific concepts you use to create wizards.

The Basics of Creating Wizards


Most wizards basics you already know. Using a series of setup pages, wizards help you design pages and Webs. Although a distinction exists between page wizards and Web wizards, the only real restriction on a wizard is what FrontPage tool it works with.

Generally, you use the FrontPage Editor to access page wizards and the FrontPage Explorer to access Web wizards. To design a new page with a page wizard, you select File | New in the FrontPage Editor, and then select the wizard you want to use. To design a new Web with a Web wizard, you select File | New Web menu in the FrontPage Explorer, and then select the wizard you want to use.

All wizards are written in a programming language, such as Visual Basic or Visual C++. The way wizards communicate with FrontPage is through OLE automation. Just as you put templates in specific directories, you put wizards in specific directories as well.

Wizard Directories


All wizards are stored in special directories under the FrontPage base installation directory. The default path to the FrontPage base installation is Program Files\Microsoft FrontPage.

If you change to the FrontPage base installation directory or examine this directory with the Windows Explorer, you will find a directory called pages. This directory stores the page templates and wizards used by the FrontPage Editor. The FrontPage base installation directory also contains a directory called webs. This directory is used to store the Web templates and wizards used by the FrontPage Explorer.

As with templates, all wizards must have unique names within the pages or webs directory. All wizard directories are named with a .wiz extension, such as framewiz.wiz and vtipres.wiz. If you examine the wizard directories, you will find that all wizards have a binary executable file with an .exe extension and a parameter file named with an .inf extension. By default, the base name of the executable file and the parameter file must match the base name of the directory that the wizard is in.

Most wizards have other files in their directories as well. For example, the directory for the Frames Wizard contains frameset files with the .frm extension, and the directory for the Corporate Presence Wizard contains all the fancy GIF and JPEG images used with the wizard.

Creating the Parameter File for Wizards


All wizards must have a parameter file. This file is a plain ASCII text file that ends with the .inf extension and is formatted similarly to a Windows INI file. Because of the way FrontPage looks for parameter files, the parameter file must use the base name of the wizard directory. If your template is stored in a directory named mywizard.wiz, for example, the parameter file for this wizard must be in a file named mywizard.inf.

Unlike template parameter files which have several sections, wizard parameter files have only one section, an information section with the identifier [info]. This section is used to specify general information about the wizard including the title, a description, the name of the executable file, and whether the wizard has editing capabilities.

Whenever you open the New Page dialog box in the FrontPage Editor, FrontPage reads the information section for all page wizards in order to provide a title and description in the dialog box. Similarly, when you open the New Web dialog box in the FrontPage Explorer, FrontPage reads the information section for all Web wizards in order to provide a title and description in the dialog box. If, for some reason, FrontPage can not find the parameter file, FrontPage displays the base name of the directory in which the wizard is stored.

Valid parameters for wizards are designated by the following names:

title This parameter is the title of the wizard, such as Corporate Presence Wizard.
description This parameter is the description of the wizard, such as Design a new Web to help you establish a corporate presence on the Web.
editor This parameter is used to specify that the wizard can function as an editor in addition to a content generator. An example of a wizard that is both an editor and a generator is the Frames Wizard. If you do not specify a value of 1 for this parameter, FrontPage assumes that the wizard can not function as an editor.
exename This parameter is the name of the binary executable file for the wizard. You can use this parameter to override the default value that specifies that the name of the executable file must match the base name of the wizard's directory.

The following is a basic parameter file that does not use the editor or exename parameters:




[info]



title=My Wizard



description=Design a new page.

The following parameter file uses all available parameters:




[info]



title=Internet Resource Wizard



description=Design a new resource page.



editor=1



exename=resources.exe

Creating Your Wizard's Interface


With wizards, Microsoft tried to create programs that let you design advanced content using a self-explanatory interface. As you've seen in this book, the interface is not always self-explanatory, especially when you deal with very advanced wizards. However, the interface Microsoft developed goes a long way toward easing the content creation process, and you should consider the general design concepts that went into creating the existing wizards.

The interface used for wizards is fairly standardized; it includes a set of buttons that are displayed throughout the page or Web creation process. These buttons are generally labeled Back, Next, Cancel, Help, and Finish. The Back and Next buttons enable users to move to the previous or next phase of the creation process. The Cancel button enables users to quit the wizard without creating the page or Web. The Help button opens a Windows Help file. The Finish button enables users to create what they've designed. When a button is not a valid option, the button is usually grayed out to indicate that it can not be pressed. Other buttons, such as the Finish button, are visible only at certain stages of the creation process.

Beyond buttons, your wizard should allow users to design pages and Webs using a series of setup pages. Generally, each setup page lets users select from a set of related design options or enter related information. Each setup page in your wizard should have explanatory text. The most detailed explanatory text is usually found on the wizard's initial setup page.

Another wizard design concept you should study is the use of graphics. Most of the images you find on the existing wizards are positioned on the left side of setup pages and are always above the buttons, which are positioned on the bottom of the setup pages.

Tracking Wizard Parameters Using Temporary Files


An important aspect of any wizard you create is its ability to communicate with FrontPage. Part of this communication process means that your wizard should be able to track key parameters and their values.

When you start a wizard in the FrontPage Editor or Explorer, the wizard is passed a single parameter that specifies the path to a temporary parameter file. As with other parameter files, the file is in Windows INI format with section identifiers. Unlike the parameter file discussed in the previous section, this temporary file exists only when the wizard is running and is updated as necessary to track changes made by the user and other essential system information. The file has three sections related to input, environment, and output settings, which have the identifiers of [input], [environment], and [output] respectively.

Input Parameters


The input section is used to track built-in parameters, such as the directory path to the wizard's executable file and the full path to its INF file. When a wizard is started, input parameters are passed to it automatically.

The input parameters for page and Web wizards are identified as follows:

Dir This parameter is the full path to the wizard directory.
Inf This parameter is the full path to the wizard's parameter file, which has an .inf extension.
Blocking This parameter determines whether the temporary file is deleted before the wizard exits. If the parameter is set with a value of 0, the file is deleted before the wizard exits. If the parameter is set with a value of 1, the file is not deleted before the wizard exits. Generally, you will use a value of 1 when you want to pass output back to the program that started the wizard, in which case the launching program will delete the temporary file after it reads the parameters it needs.
Editing This parameter determines whether the wizard can be used as an editor. This parameter relates directly to the editor parameter in the wizard's INF file. If the Editing parameter is set with a value of 0, the wizard cannot be used as an editor. If the parameter is set with a value of 1, the wizard can be used as an editor.

Some input parameters can be used only with the page wizard:

PageURL The URL the page should be saved with, which is a relative URL in the current Web
PageTitle The title for the new page
PageFile The full path to the file being edited, which is set only if the value of the Editing parameter is 1

Another useful parameter that you can use only with page wizards is the destination parameter. In general, when a page wizard finishes, the page it creates is loaded into the FrontPage Editor. However, if the wizard generates content that can not be edited by the FrontPage Editor, the wizard should load the page to the current Web or to a file on the user's file system instead. You use the destination parameter to specify where the file should be loaded or stored.

By default, the destination parameter is set to editor, which means the page generated by the wizard should be loaded into the FrontPage Editor using OLE automation. You can change the default destination by setting a value of either web or disk. If the destination parameter is set to web, the page is saved to the current Web. If the destination parameter is set to disk, the page is saved to a file on the user's file system.

The following input parameters can be used only by Web wizards:

WebName The name of the current Web
ServerName The name of the host server or its IP address
Proxy The proxy server currently being used
User The name of the user who is accessing the FrontPage Explorer

The following is a sample input section for the temporary parameter file:




[input]



PageURL=index.htm



PageTitle=My Home Page



Dir=D:\Program Files\Microsoft FrontPage\Pages\FramesWiz.wiz



Inf=D:\Program Files\Microsoft FrontPage\Pages\FramesWiz.wiz\frameswiz.inf



Blocking=0



Editing=0

Environment Parameters


The environment section is used to track standard environment variables such as the name of the computer or path settings. As with input parameters, environment parameters are set automatically. Additionally, environment parameters are unique to the computer you are using. To check environment variable settings on your Windows 95/NT system, type the keyword set at the MS-DOS prompt.

When I enter the set command on my system, I see that these environment variables are set as follows:




TMP=C:\WINDOWS\TEMP



TEMP=C:\WINDOWS\TEMP



PROMPT=$p$g



winbootdir=C:\WINDOWS



COMSPEC=C:\WINDOWS\COMMAND.COM



NBACKUP=C:\NBACKUP



CLASSPATH=.;C:\JAVA\LIB\;C:\JAVA\LIB\CLASSES.ZIP;



PATH=C:\MSBOB;C:\WINDOWS;C:\WINDOWS\COMMAND;C:\NBACKUP;C:\JAVA\BIN;



windir=C:\WINDOWS



BLASTER=A220 I5 D1 H5 P330 T6

Output Parameters


Unlike the input and environment sections of the temporary file, the output section is empty when the wizard is started and is written to only if the input blocking parameter is set to 1 or the destination parameter is set to disk.

The primary output parameter recognized by FrontPage is ExitStatus, which is used to set the status of the wizard. A value of error indicates that an error has occurred. A value of cancel indicates that the user canceled the creation of the page or Web—usually by pressing a button labeled Cancel. A value of ok indicates that the wizard completed successfully. If you do not set the ExitStatus parameter, FrontPage assumes that an error has occurred. For this reason, you should always set this parameter.

Other output parameters are used only if the destination parameter is set to the value of disk. These parameters include the number of files created by the wizard, which is set with the FileCount parameter, as well as a File and Url parameter for each file the wizard creates. The File and Url parameters are used as keys and end with a suffix which indicates the position of the key, such as File1, Url1, File2, or Url2. The File parameter indicates the full path to the file, and the Url parameter sets the page URL.

A wizard that generated three files might create the following output section:




[output]



ExitStatus=ok



FileCount=3



File1=c:\temp\wiz01.tmp



Url1=index.htm



File2=c:\temp\wiz02.tmp



Url2 = banner.htm



File3=c:\temp\wiz03.tmp



Url3=footer.htm

Putting Temporary Parameter Files in Perspective


All files generated by your wizard should be written to the temp directory under the FrontPage base installation directory. The default path to this directory is Program Files\Microsoft FrontPage\temp. To ensure a consistent naming structure, all temporary files your wizard creates should end with the .tmp extension.

For the temporary parameter file, you might want to follow the naming scheme used by Microsoft, which consists of the following:

An sample filename using this structure is wiz5190.tmp.

If you have used wizards, you will find a number of temporary files in the temp directory. Examining these files can tell you a lot about how temporary parameter files are used. The following is a sample file from my file system:




[Input]



Dir=C:\Program Files\Microsoft FrontPage\pages\framewiz.wiz



Inf=C:\Program Files\Microsoft FrontPage\pages\framewiz.wiz\framewiz.inf



Blocking=0



Editing=0



[Environment]



TMP=C:\WINDOWS\TEMP



TEMP=C:\WINDOWS\TEMP



PROMPT=$p$g



winbootdir=C:\WINDOWS



COMSPEC=C:\WINDOWS\COMMAND.COM



NBACKUP=C:\NBACKUP



CLASSPATH=.;C:\JAVA\LIB\;C:\JAVA\LIB\CLASSES.ZIP;



PATH=C:\MSBOB;C:\WINDOWS;C:\WINDOWS\COMMAND;C:\NBACKUP;C:\JAVA\BIN;



CMDLINE=WIN



windir=C:\WINDOWS



BLASTER=A220 I5 D1 H5 P330 T6



[Output]



ExitStatus=cancel

A final note on parameter files is that you should not use a temporary parameter file when you want to retain option settings selected by the user. If you've used the wizards in FrontPage, you probably noticed that the first time you use a wizard you see default settings, but thereafter, you see the last settings you made in the wizard.

To preserve option settings, store the settings in a wizard initialization file. Name this file with the .ini extension so you can identify it as an initialization file and put it in the data directory under the FrontPage base installation directory. The default path to this directory is Program Files\Microsoft FrontPage\data.

To get an idea of how you can save option settings, examine the following option settings based on the selections I made using the Corporate Presence Wizard:




[Settings]



DoFeedbackPage=True



DoWhatsNewsPage=True



DoProductsPage=True



DoSearchPage=True



DoTOCPage=True



DoHomePage=True



DoHomeContactInfo=True



DoHomeIntro=False



DoHomeMission=True



DoHomeProfile=False



DoNewsArticles=False



DoNewsPressReleases=False



DoNewsWhatsNew=True



ProductOption=0



NumProducts=3



NumServices=3



DoFeedbackAddress=False



DoFeedbackCompany=True



DoFeedbackEmail=True



DoFeedbackFAX=True



DoFeedbackName=True



DoFeedbackTelephone=True



DoFeedbackTitle=False



FeedbackFileFormat=0



TOCAutoRecalc=False



TOCBullets=True



TOCOrphans=False



DoBottomLinks=False



DoBottomCopyright=False



DoTopLogo=True



DoTopTitle=True



DoTopLinks=True



DoBottomWebmasterAddress=True



DoBottomDateModified=True



DoProductImage=False



DoProductInfoRequest=True



DoProductPricing=True



DoServiceCapabilities=False



DoServiceInfoRequest=True



DoServiceReferences=False



StyleOption=1



UnderConstructionOption=0



CompanyLongName=ACME Industries Inc.



CompanyShortName=ACME



CompanyAddress=123 Web Way, Cambridge MA 02138



CompanyPhone=617-555-1212



CompanyFAX=617-555-1212



CompanyWebMaster=webmaster@yourcompany.com



CompanyEmail=info@yourcompany.com



ShowToDoList=True



LinkColor=0xff0000



VisitedLinkColor=0x800080



TextColor=0x0



BackgroundColor=0xc0c0c0



ActiveLinkColor=0xff



BackgroundImage=0



ColorSettingsOption=0

Determining Where Your Wizard Should Look for Key Files


Any wizard you create should be able to run on someone else's computer. Yet, if your wizard references hard file paths, the wizard will work properly only on systems where FrontPage is installed exactly as you've installed it. The key to ensuring the portability of your wizard is not to use hard file paths.

Instead, you should look up the file paths in the initialization file for FrontPage, which will always be stored in the Windows directory. The FrontPage initialization file is called frontpg.ini. Using this file, you can determine the location of the FrontPage base installation directory and the base installation directory for FrontPage Webs. The FrontPageRoot variable tells you the location of the FrontPage base installation directory. The PWSRoot variable tells you the location of FrontPage Webs. These variables are in the FrontPage 2.0 section of the INI file.


NOTE

You can change the location of the FrontPage Webs and pages directories by changing the WebWizardsDir and PageWizardsDir parameters in the FrontPage 2.0 section of the initialization file.


The following is an example of what the INI file looks like:




[FrontPage 2.0]



FrontPageRoot=C:\Program Files\Microsoft FrontPage



PWSRoot=C:\FrontPage Webs



FrontPageLangID=0x0410



FrontPageLexicon=C:\Program Files\Microsoft FrontPage\bin\mssp2_en.lex



FrontPageSpellEngine=C:\Program Files\Microsoft FrontPage\bin\mssp232.dll



CheckedHostName=tvp.com



[Ports]



Port 80=



[Port 80]



servertype=frontpage



serverconfig=C:\FrontPage Webs\Server\conf\httpd.cnf



authoring=enabled



frontpageroot=C:\Program Files\Microsoft FrontPage

Using OLE Automation in Your Wizards


The key to communication between your wizard and FrontPage is OLE automation. If you are familiar with Windows programming, you probably already know how OLE automation works. Basically, with OLE automation your wizard can make procedure calls to the FrontPage Explorer, the FrontPage Editor, and the FrontPage To Do List. These procedure calls can cause the program they call to perform specific actions. For example, a procedure call can cause the FrontPage Editor to start and load a page for editing. Likewise, a procedure call can cause the FrontPage Explorer to launch.

Each of the FrontPage tools you can access with OLE has a specific set of procedures. The set of OLE procedures that a program can use is collectively referred to as its OLE interface.

Because the automation interface used in FrontPage is still evolving, your OLE automation code should use macros of function wrappers to localize calls to OLE procedures. In this way, you can easily update your code for compatibility with the next major release of FrontPage.

All applications capable of being accessed with OLE automation must be registered in the Windows Registry. The FrontPage interfaces for version 2.0 have the following identifiers in the Windows Registry:

You will use these identifiers to specify which tool you want to connect to. You also can use the FrontPage tools with a generic identifier that resolves to the current release of FrontPage installed on the user's system:


NOTE

You probably will have to update your wizard programs for compatibility with future releases of FrontPage. When you use the specific identifier, you will always have to update your wizard for the new versions of FrontPage. When you use the generic identifier, you might run into compatibility problems if the interface changes in future versions of FrontPage. If you use the generic identifier, however, you might not recognize that the problem is with version compatibility.



Programming the Wizard


Now that you know wizard basics, what parameters the wizard can use and what files the wizard should create, you are almost ready to program the wizard. Before you begin, consider carefully what programming language you will use. The language you select must support OLE automation. As stated earlier, both Visual Basic and Visual C++ are good choices for programming languages. Not only is it easy to create graphical interfaces with Visual Basic and Visual C++ languages, the OLE programming examples in the next chapter also use these languages.

After you read about the OLE automation procedures supported by FrontPage and how they are used, you might want to spend a few hours examining the sample wizards included in the FrontPage Developer's Kit. You will be amazed at how much code you can reuse.

Most of the wizards you create will use three common types of routines:


NOTE

For detailed information on the OLE procedures used in the examples you will find in this section, see Appendix B "ActiveX Control Automation Command Reference."



Establishing a Connection to the OLE Server


One very important step you should perform before calling an OLE procedure is to establish a connection to the automation server's exported object interfaces. Typically, you do this by creating an object with an object type of the application you want to connect to. After the connection is established, you have access to the object's OLE interface and can make procedure calls. When you're finished making procedure calls, release the connection with the OLE automation server.

A key concept when using OLE automation is to minimize the amount of time when an open OLE connection exists. Otherwise, you might run into serious problems when users close the application they are using or change the application's state in a way that will cause your OLE procedures to fail. Most programmers open and close the OLE connection inside a single procedure.

To put these OLE concepts in perspective, Listing 26.1 shows a sample procedure written in Visual C++ that demonstrates these concepts and uses a generalized OLE identifier.

Listing 26.1. An OLE procedure in Visual C++.




#include "target.h"



// Initiate the procedure



void IncludeEvent()



{



// Establish connection to the automation server and handle possible error



IWebber explorer;



COleException error;



if(!explorer.CreateDispatch("FrontPage.Explorer",&error))



{



AfxMessageBox("Error connecting to FrontPage Explorer. Check server status.");



return;



}



// Make procedure call to the FrontPageExplorer



explorer.vtiBringToTop();



// Release the connection with the OLE automation server



explorer.ReleaseDispatch();



}

Listing 26.2 shows the same procedure written in Visual Basic.

Listing 26.2. An OLE procedure in Visual Basic.




' Initiate the procedure



Function IncludeEvent()



{



Dim explorer as Object



' Establish connection to the automation server and handle possible error



Set explorer = CreateObject("FrontPage.Explorer")



' Make procedure call to the FrontPageExplorer



explorer.vtiBringToTop



' Release the connection with the OLE automation server



Set explorer = Nothing



}

Checking the Status of the Explorer When Necessary


The main OLE interface in FrontPage is for the FrontPage Explorer. Whenever your wizards use OLE hooks that access or alter the current Web, you will need to write a procedure that ensures a Web is open in the FrontPage Explorer. The routine shown in Listing 26.3 checks the URL of the current Web in the FrontPage Explorer before adding a task to the To Do List. This routine is written in Visual Basic.

Listing 26.3. Checking the Explorer before calling a To Do List procedure.




Private Sub AddTask()



' Initialize variables



    Dim todolist As Object



    Dim webber As Object



    Dim webURL As String



    Dim ret As Boolean



    Dim url As String



    Dim priority As Integer



    MousePointer = 11



' Ensure a Web is open in the FrontPage Explorer



Set webber = CreateObject("FrontPage.Explorer.2.0")



    webURL = webber.vtiGetWebURL



' Close the connection to the Explorer



    Set webber = Nothing



' If the length of the webURL variable is 0, no Web is currently open



' in the FrontPage Explorer. Handle the error by exiting.



    If Len(webURL) = 0 Then



        MsgBox "No Web is currently open in the Explorer."



Exit Sub



    End If



' Set the task priority based in user selection



    If optionHigh Then priority = 1



    If optionMedium Then priority = 2



    If optionLow Then priority = 3



' Add task to the current Web's To Do List



Set todolist = CreateObject("FrontPage.ToDoList.2.0")



    ret = todolist.vtiAddTask(txtTask, priority, txtCreator, txtURL,



    txtCookie, txtComment)



' Display error message if could not add the task



    If Not ret Then



        MsgBox "Failed to add task for To Do List."



    End If



' Close the connection to the To Do List



    Set todolist = Nothing



    frmGetURL.Tag = ""



    MousePointer = 0



End Sub

Writing HTML Pages to Files


Your wizards must also generate HTML documents based on the user's selections. Generally, the wizard will write HTML documents to files, with each file containing the HTML markup for one page. Listing 26.4 shows a sample routine written in Visual Basic that writes an HTML page to a file.

Listing 26.4. Writing an HTML page to a file.




Public Sub CreatePage(pagepage As String)



' Initialize variable for file



    Dim ff As Integer



' Initialize variable for new line



    Dim nl As String



' Initialize variable for standard string



    Dim str As String



' set new line variable to ASCII new line line value



    nl = Chr$(10)



' set file variable to FreeFile



    ff = FreeFile



' set up error handling



    On Error GoTo BadFile



' open file on file system for output



    Open pagefile For Output As #ff



' Build and write the HTML page



    Print #ff, "<HTML>"



    Print #ff, "<HEAD>"



    Print #ff, "<TITLE>" & TitleTag & "</TITLE>"



    Print #ff, "</HEAD>"



    Print #ff, "<BODY BGCOLOR=" & BGColorTag & " TEXT=" & TXColorTag & ">"



    str = "H" & (cmbStyle.ListIndex + 1)  ' H1, H2, or H3



    Print #ff, "<" & str & ">" & ResourceTitle & "</" & str & ">"



    Print #ff, "<P>" & ParaText1 & "</P>"



    Print #ff, "<UL>"



    Print #ff, "<LI>" & P1ListItem1



    Print #ff, "<LI>" & P1ListItem2



    Print #ff, "<LI>" & P1ListItem3



    Print #ff, "<LI>" & P1ListItem4



    Print #ff, "</UL>"



    Print #ff, "<P>" & ParaText2 & "</P>"



    Print #ff, "<OL>"



    Print #ff, "<LI>" & P2ListItem1



    Print #ff, "<LI>" & P2ListItem2



    Print #ff, "<LI>" & P2ListItem3



    Print #ff, "<LI>" & P2ListItem4



    Print #ff, "</OL>"



    If chkCredit Then



        Print #ff, "<HR SIZE=5>"



        Print #ff, "<P><EM>This page was generated by the Internet



        ¬Resource Wizard.</EM></P>"



    End If



    Print #ff, "</BODY>"



    Print #ff, "</HTML>"



' close the page file



    Close #ff



' on error exit the subroutine



BadFile:



    Exit Sub



End Sub

More OLE Automation with FrontPage


The previous section introduced basic OLE concepts. Wizards use OLE automation to communicate with three FrontPage components: the FrontPage Explorer, the FrontPage Editor, and the FrontPage To Do List. Each component has a specific set of OLE procedures that it recognizes.

Using OLE Automation with the FrontPage Explorer


Most procedures your wizards use will need to interface with the FrontPage Explorer. Using the FrontPage Explorer OLE interface, you can do the following:

The procedures you use to perform these tasks are restricted by the FrontPage Explorer's OLE interface. For FrontPage version 2.0, the only OLE procedures you can use are the following:

The FrontPage Explorer has the most extensive OLE interface. One of the most common reasons your wizards will access this interface is to open a Web. Listing 26.5 shows a sample procedure for opening a Web that is written in Visual Basic. As you study the example, pay particular attention to the way OLE procedure calls are made.

Listing 26.5. Opening a Web using OLE.




Private Sub OpenWeb()



MousePointer = 11



' Initialize variables



Dim webber As Object



Dim ret As Integer



' Open a Web on the specified server



Set webber = CreateObject("FrontPage.Explorer.2.0")



ret = webber.vtiOpenWeb(Server, Web, User)



' Close the connection to the Explorer



Set webber = Nothing



MousePointer = 0



End Sub

Another common task your wizards might need to do is to create a Web. Listing 26.6 provides a sample procedure for creating a Web.

Listing 26.6. Creating a new Web.




Private Sub CreateWeb()



MousePointer = 11



' Initialize variables



Dim webber As Object



Dim ret As Long



' Create the new Web on the server



Set webber = CreateObject("FrontPage.Explorer.2.0")



ret = webber.vtiCreateWeb(Server, Web)



' Close the connection to the Explorer



Set webber = Nothing



MousePointer = 0



End Sub

Listing 26.7 shows a sample procedure for removing a Web. Removing a Web is trickier than creating a new Web or opening an existing Web. Before you remove a Web, you must ensure that there is an open Web in the FrontPage Explorer. You must also ensure that you do not accidentally delete the RootWeb. To handle these tasks, check the value returned by the vtiGetWebURL procedure before removing the Web.

Listing 26.7. Removing Webs.




Private Sub RemoveWeb()



MousePointer = 11



' Initialize variables



Dim webber As Object



Dim ret As Long



Dim webURL As String



' vtiGetWebURL returns an empty string if there is no current web



' AND if the current Web is the RootWeb



Set webber = CreateObject("FrontPage.Explorer.2.0")



webURL = webber.vtiGetWebURL



' Remove the Web if there is a current Web AND it is not the RootWeb



If Len(webURL) > 0 Then



     ret = webber.vtiRemoveWeb("/" & Web)



     If ret <> 1 Then



     MsgBox "An error occurred while trying to remove the web '" & Web &



      ¬". The Web may not exist on the server."



End If



Else



     MsgBox "A Web must be open in the FrontPage Explorer."



End If



' Close the connection to the Explorer



Set webber = Nothing



MousePointer = 0



End Sub

Using OLE Automation with the FrontPage Editor


The FrontPage Editor is used primarily for creating and editing pages. Because pages are not as complex as Webs, there is no need for an extended interface between wizards and the FrontPage Editor. You will use the FrontPage Editor OLE interface to perform basic editor tasks including the following:

Although most of the OLE automation hooks to the FrontPage Editor are designed to be used by other FrontPage components, your wizards can use any of the available OLE procedures. These procedures are as follows:

A complete reference guide for these commands is in Appendix D, "OLE Automation with FrontPage Command Reference."

Although the FrontPage Editor OLE interface is not as extended as the FrontPage Explorer interface, you will find many uses for Editor procedures in your wizards. One of the tasks your wizards might need to do is to create a new page. Listing 26.8 shows a sample procedure written in Visual Basic for creating new pages.

Listing 26.8. Creating new pages.




Private Sub CreateNewPage()



' Initialize variables



Dim editor As Object



Dim page As Object



'Create new HTML page



Set editor = CreateObject("FrontPage.Editor.2.0")



Set page = editor.vtiNewWebPage("homepage.htm", "", "")



' Close the connection to the Editor



Set editor = Nothing



End Sub

Another task you might want to perform is to bring the FrontPage Editor to the front of the display. Listing 26.9 shows a sample procedure to do this task.

Listing 26.9. Bringing the FrontPage Editor to the front.




Private Sub BringFront()



' Initialize variable



Dim editor As Object



MousePointer = 11



' Bring editor to front



Set editor = CreateObject("FrontPage.Editor.2.0")



editor.vtiBringToTop



' Close the connection to the Editor



Set editor = Nothing



MousePointer = 0



End Sub

A more advanced task you might want your wizard to perform involves checking to see whether a page is currently loaded in the FrontPage Editor. Using the vtiQueryWebPage procedure, you query the editor to see whether a page is loaded. Because this procedure can check the URL of the Web the page came from, you should ensure that a Web is open in the FrontPage Explorer before making the procedure call to the FrontPage Editor.

Listing 26.10 shows a sample procedure for querying the FrontPage Editor.

Listing 26.10. Querying the Editor.




Private Sub QueryEditor()



' Initialize variables



Dim editor As Object



Dim webber As Object



Dim webURL As String



Dim ret As Long



Dim url As String



' Ensure a Web is open in the FrontPage Explorer



Set webber = CreateObject("FrontPage.Explorer.2.0")



webURL = webber.vtiGetWebURL



' Close the connection to the Explorer



Set webber = Nothing



' Display error message and exit if no current web



If Len(webURL) = 0 Then



     MsgBox "Cannot continue. No Web is open in the FrontPage Explorer."



Exit Sub



End If



MousePointer = 11



' Routine for Querying the Editor and displaying a message.



Set editor = CreateObject("FrontPage.Editor.2.0")



ret = editor.vtiQueryWebPage(url, webURL)



If ret = 1 Then



     MsgBox "Document is open in the FrontPage Editor."



Else



     MsgBox "Document is not open in the FrontPage Editor."



End If



' Close the connection to the Editor



Set editor = Nothing



MousePointer = 0



End Sub

Using OLE Automation with the FrontPage To Do List


The FrontPage To Do List helps you manage tasks related to creating and editing Webs. All tasks have a set of attributes that describe the purpose of the task. When tasks are completed, they are removed from the To Do List.

As with the FrontPage Editor, there is no need for an extended interface between wizards and the FrontPage To Do List. Usually, you will use the interface to perform the following tasks:

As with the FrontPage Editor OLE interface, the FrontPage To Do List OLE interface is designed primarily to be used by other FrontPage components. Still, your wizards can use any of the available OLE procedures. These procedures include the following:

A complete reference guide for these commands is in Appendix D.

The most common reason you will use the OLE interface to the To Do List is to add tasks. Listing 26.11 shows a sample procedure written in Visual Basic for adding tasks. As with other code examples in this chapter, you should follow the logic of the code, paying particular attention to the way OLE procedure calls are made.

Listing 26.11. Adding tasks.




Private Sub AddTask()



' Initialize variables



Dim todolist As Object



Dim webber As Object



Dim webURL As String



Dim ret As Boolean



Dim url As String



MousePointer = 11



' Ensure a Web is open in the FrontPage Explorer



Set webber = CreateObject("FrontPage.Explorer.2.0")



webURL = webber.vtiGetWebURL



' Close the connection to the Explorer



Set webber = Nothing



' If the length of the webURL variable is 0, no web is currently open



' in the FrontPage Explorer. Handle the error by exiting.



If Len(webURL) = 0 Then



     MsgBox "A Web must be open in the Explorer."



Exit Sub



End If



' Add task to the current Web's To Do List



Set todolist = CreateObject("FrontPage.ToDoList.2.0")



ret = todolist.vtiAddTask(Task, priority, Creator, URL, Cookie, Comment)



' Display error message if could not add the task



If Not ret Then



     MsgBox "Could not add task for To Do List."



End If



' Close the connection to the To Do List



Set todolist = Nothing



frmGetURL.Tag = ""



MousePointer = 0



End Sub

Other important procedures you might use with the To Do List interface are those that mark tasks as completed. Note the use of the URL and Cookie parameters to find a particular task. Listing 26.12 shows how you could use Visual Basic to write a procedure that marks tasks as completed.

Listing 26.12. Procedure for marking tasks as completed.




Private Sub TaskCompleted()



' Initialize variables



Dim todolist As Object



Dim webber As Object



Dim webURL As String



Dim ret As Boolean



Dim url As String



Dim priority As Integer



MousePointer = 11



' Mark specific task as completed



Set todolist = CreateObject("FrontPage.ToDoList.2.0")



ret = todolist.vtiCompletedTaskByUrl(URL, Cookie)



' Display error message if could not mark the task



If Not ret Then



     MsgBox "Could not mark task as completed."



End If



' Close the connection to the To Do List



Set todolist = Nothing



MousePointer = 0



End Sub

Summary


Use the concepts discussed in this chapter to help you create customized wizards. Your wizards can use OLE automation to communicate with the FrontPage Explorer, FrontPage Editor, and the FrontPage To Do List.

The FrontPage Explorer, the FrontPage Editor, and the FrontPage To Do List each use a specific set of OLE procedures. You can use these procedures to create wizards that communicate with FrontPage. After you create a wizard, be sure to move it to the appropriate directory.

Previous Page Page Top TOC Next Page