Lesson 2: Creating ActiveX Documents

ActiveX documents, also known as Active documents, are document files created by ActiveX document server applications. ActiveX documents can be viewed and edited not only by the server application that created them, but also by any ActiveX document container application.

Microsoft Word documents are an example of ActiveX documents. Users of Internet Explorer (an ActiveX document container application) can view and edit Word documents using the full functionality of Word (an ActiveX document server application) from within the Internet Explorer browser window.

ActiveX documents have come to be a powerful feature of Web sites for users of Microsoft applications, extending the functionality of the Internet Explorer browser to provide a versatile, feature-rich alternative to simple HTML Web pages.

After this lesson, you will be able to:

• Describe how to use ActiveX documents.
• Describe some of the advantages of using ActiveX documents on your Web site.
• Describe how to use the MFC AppWizard to create an ActiveX document server.
• Describe how to deploy an ActiveX document on a Web site, and how to view the ActiveX document using Internet Explorer.

Estimated lesson time: 30 minutes

Using ActiveX Documents

In Chapter 6, you learned how a document/view application can save its data to disk as a document file. Generally speaking, you can view or edit a document file only by launching the application that created it. However, with very little extra work, you can make your application into an ActiveX document server so that any ActiveX document container application can be used to view or edit your documents using the functionality of the server application.

When a container application loads an ActiveX document, it also loads menu, toolbar, and status bar resources from the associated server application. The menus and toolbars are merged with those of the container frame window to make the functionality of the server application available from within the container application. In effect, the server temporarily "takes over" the container when an ActiveX document is displayed.

If you have Internet Explorer and Word installed, you can easily try out ActiveX document technology.

To view an ActiveX document located on your local hard drive

1. Start Internet Explorer.
2. Start Windows Explorer and use it to locate a Word .doc file.
3. Move the Word document file from Windows Explorer to the Internet Explorer window using a drag-and-drop operation. Your Word document should open in Internet Explorer as an ActiveX document, as shown in Figure 12.13.



Figure 12.13 Viewing an ActiveX document using Internet Explorer 5

Notice that Internet Explorer displays the Word menus and toolbars in addition to its own. Try editing the Word document from within Internet Explorer, and try using some of the features provided by the Word menus. Click the Back button to return to the previously displayed page. Note that Internet Explorer asks whether you want to save the edited ActiveX document before proceeding.

NOTE

---

There are some differences between the way that versions 4.0 and 5 of Internet Explorer handle ActiveX documents. In Internet Explorer 4.0, you can load an ActiveX document by specifying it as a file:// URL in the address bar. Internet Explorer 5, however, will load a separate instance of the Word application to view the document rather than loading it as an ActiveX document.

Using ActiveX Documents on a Web Site

Internet Explorer is not the only ActiveX document container application (the Microsoft Office Binder is another), but it is the container that is of interest to us in this chapter because we are demonstrating Internet programming. The example just given portrays a somewhat artificial situation. Internet Explorer is not generally used to view an ActiveX document on your local computer—it is much more efficient to use the document's parent application to do this.

Internet Explorer uses its ActiveX container capabilities to view ActiveX documents that are deployed on a Web server. This means that Word documents, Microsoft Excel spreadsheets, and any of your custom-built ActiveX documents can be included on your Web site and made available for viewing and editing by anyone who has the corresponding ActiveX document server applications installed on their computer. An ActiveX document server won't let you save any changes you make to the document back to the Internet host, but it will let you save them in a new version on your own hard disk. In other words, the Save command on the File menu is unavailable, but the Save As command is available.

A common use for ActiveX documents is to create a "forms" center on a company intranet site. An area of the intranet site can contain Word or Excel versions of forms—such as training request forms or expense claim forms—that are regularly submitted by employees. This means that employees, whether they are in the office, at home, or halfway across the world, can browse to the intranet site and load a blank form into their Web browser. Using ActiveX document technology, they can fill out the form online, and then save a local copy that can be faxed or e-mailed to the personnel department.

You can provide a much richer interface to Web site data using ActiveX document technology than you can using standard HTML pages. When you view an Excel spreadsheet over the Web, you have access to all of the powerful features of Excel to organize and display your data. The fact that you need to have the ActiveX document server application installed on your local computer before you can view ActiveX documents on a remote Web site could be perceived as a limitation. To address this issue, you could develop different versions of your server application. You could, for example, create a fully featured version that is used to create and maintain ActiveX documents deployed on your Web site, and a lightweight viewer application that can be downloaded to Internet clients for use in conjunction with the Web browser. Microsoft takes this approach with its Word document viewer application, which allows you to view Word documents deployed on a Web site without having a full version of Word installed on your computer.

One potential drawback of using ActiveX document technology on your Web site is that users of your site are compelled to use a browser that supports ActiveX documents. They must also have a copy of your ActiveX document server application installed on their computer, which assumes that they are running Windows. This means that ActiveX documents are best used in a situation where you are in a position to specify the platform and configuration of the client computers. When you want to create a public Web site that is accessible from many different unknown clients, you should use HTML.

Creating an ActiveX Document Server

Visual C++ 6.0 makes creating ActiveX documents extremely easy. Selecting the appropriate option in the AppWizard will generate all the code and resources necessary to make your application an ActiveX document server.

To create an ActiveX document server application

1. Use AppWizard to create a new .exe project named MyADSApp. In Step 1, click the Single document option.
2. Accept the default options for Step 2. In Step 3, click the Full-server and the Active document server options, as shown in Figure 12.14.



Figure 12.14 MFC AppWizard compound document options

3. In Step 4, click Advanced and enter ads as the file extension. Close the Advanced Options dialog box.
4. Click Finish and then click OK to create the project.

In the following exercises, you will create a simple application that displays a line of text in the application's main window. First you will create a dialog box to allow the user to specify the text to be displayed.

To create the Set Display String dialog box

1. Create a dialog template containing a single edit control, as shown in Figure 12.15. The dialog ID should be IDD_EDITSTRING and the edit control ID should be IDC_NEWSTRING.



Figure 12.15 The Set Display String dialog box

2. Create a dialog class named CEditStringDlg. On the ClassWizard Member Variables page, create a Value category CString member variable named m_newstring.

Next you will create the application data (the string to be displayed) by adding a data member to the document class. You will also implement the Serialize() function to store and retrieve this data member to the ActiveX document file.

To create the CMyADSApp application data

Add a public CString member variable named m_strDisplay to the CMyADSAppDoc class. Modify the CMyADSAppDoc::Serialize() function to serialize the m_strDisplay variable, as shown in the following code:

void CMyADSAppDoc::Serialize(CArchive& ar) {      if (ar.IsStoring())      {           ar << m_strDisplay;      }      else      {           ar >> m_strDisplay;      } }

Now you will modify the application menu and toolbar to create the Edit String command. You will also create a handler function for this command.

To create and implement the Edit String menu command

1. Edit the IDR_MAINFRAME menu resource. On the Edit menu, delete the Undo command. Replace it with a new command with the caption &String. Provide a suitable prompt string. Accept the default command ID ID_EDIT_STRING for the command.
2. Edit the IDR_MAINFRAME toolbar. Create a simple toolbar button to represent text entry. Assign the ID_EDIT_STRING command ID to the new toolbar button.
3. Add the following line to the top of the MyADSAppDoc.cpp file:

#include "EditStringDlg.h"

4. Create a command handler in the CMyADSAppDoc class for the ID_EDIT_STRING command ID. Name the function OnEditString() and implement the function as follows:

void CMyADSAppDoc::OnEditString() {      CEditStringDlg myDialog;      myDialog.m_newstring = m_strDisplay;        if(myDialog.DoModal() == IDOK &&           myDialog.m_newstring != m_strDisplay)      {           m_strDisplay = myDialog.m_newstring;           UpdateAllViews(NULL);           SetModifiedFlag();      } }

This function displays the Set Display String dialog box to allow the user to specify the string displayed by the application. The string is stored in the CMyADSAppDoc::m_strDisplay variable.

To implement the application drawing function

Locate the CMyADSAppView::OnDraw() function. Replace the //TODO comment line with the following code:

CFont HeadingFont; if(HeadingFont. CreateFont(64, 0, 0,       0, FW_NORMAL, 1, 0, 0, 0, 0, 0, 0, FF_DECORATIVE, 0))      pDC->SelectObject(&HeadingFont); pDC->TextOut(10, 10, pDoc->m_strDisplay);

If you build and run the CMyADSApp application at this point, it will function perfectly well as a stand-alone application. You will be able to choose the String command from the Edit menu and add a string to be displayed in the application main window. You will be able to save the string in a document file with an .ads extension.

If you try and load the saved .ads file into an ActiveX document container such as Internet Explorer, you will be able to see the string displayed, but you will not be able to access the String command on the Edit menu. This is because an ActiveX document container does not load menu commands and toolbar buttons from the IDR_MAINFRAME resources.

When you use AppWizard to create an ActiveX document server, additional menu and toolbar resources, both with the ID IDR_SRVR_INPLACE, are created for the project. The commands on the IDR_SRVR_INPLACE menu are merged into the container menu; and the IDR_SRVR_INPLACE toolbar is added to the toolbars displayed by the container application.

You will need to edit the IDR_SRVR_INPLACE menu and toolbar to make the the String command on the Edit menu available from the menu of the ActiveX document container.

To edit the IDR_SRVR_INPLACE menu and toolbar resources

1. In ResourceView, double-click the IDR_SRVR_INPLACE menu item. Edit the menu item properties for the Undo command on the Edit menu. Change the menu item caption to &String and the ID to ID_EDIT_STRING. The prompt string will change automatically when the Menu Item Properties dialog box is closed.
2. Edit the IDR_SRVR_INPLACE toolbar resource. Create a new button identical to the button you created for the IDR_MAINFRAME resource (you can copy and paste from one edit window to another). Assign the button the ID_EDIT_STRING ID.
3. Build and run the CMyADSApp application. Use the String command on the Edit menu to display the string "Hello World!" in the application's main window. Close the application and, when prompted, save the file as Hello.ads.
4. Start Internet Explorer. Use Windows Explorer to locate the Hello.ads file and drag the file onto the Internet Explorer window. If the File Download message box appears, click Open this file from the current location and click OK. The file should appear as shown in Figure 12.16.



Figure 12.16 The Hello.ads document hosted in Internet Explorer 5

5. Check that you can use the String command on the Edit menu to change the string displayed in the document. Click the Internet Explorer Back button to go back to the previous page that was displayed in the browser. In the message box that asks whether you want to save your changes, click No.

Deploying an ActiveX Document on a Web Site

The following exercises show you how to deploy the Hello.ads file on a Web site so that it can be accessed across the Internet using HTTP. Instructions are provided for IIS 4.0 and PWS.

Web Site Organization

A new installation of IIS 4.0 or PWS will create a default Web site for your computer, which is accessible by specifying your computer name as a URL. For example, if you enter the following URL into your Internet Explorer Address box, the browser will display the Web server's default welcome page:

http://[your computer name]/

The trailing slash after the computer name (which will be added by the browser if you do not type it yourself) signifies that you wish to go to your home directory. The Windows NT Option Pack welcome page appears because it is designated as the default document for the home directory.

You can organize your Web site into a hierarchy of virtual directories, which are organizational subdivisions of your Web site that are conceptually similar to the subdirectories, or folders, of your hard disk's file system. All virtual directories are subdirectories of the Web site's home directory. They are known as virtual directories because the structure you define is not directly related to the organization of folders on your hard disk. Each virtual directory points to a folder on a hard disk that stores the Web pages, ActiveX documents, and other files that make up the content of the virtual directory. These content folders do not even need to be on the same computer as the Web server.

When specifying virtual directories in a URL, use the UNIX-style forward slash. For example, entering the following URL into your Web browser's Address box will take you to the visualc virtual directory on Microsoft's Web site:

msdn.microsoft.com/visualc/

If you do not name a specific Web page in the URL, as just shown, the Web server will display the default document specified for the virtual directory.

Deploying Content on a Microsoft IIS 4.0 Web Server

The Microsoft Internet Service Manager is a utility installed with IIS that is used to administrate a Web server, as well as the other Internet services that IIS provides, such as mail and FTP servers. Using the Internet Service Manager, you can configure the content, security and performance of a Web site.

In the following exercise, you will use the Internet Service Manager to create the docs virtual directory on the default Web site. The docs virtual directory will host the Hello.ads ActiveX document.

To deploy the Hello.ads ActiveX document

1. Using Windows Explorer, create a new folder under the \InetPub\WWWRoot folder and name it MyActiveXDocs. Then place a copy of the Hello.ads file in this folder.
2. On the Start menu, point to Programs, point to NT 4.0 Option Pack, point to Microsoft Internet Information Server, and click Internet Service Manager.
3. In the left pane, expand the Internet Information Server item. Expand the item that is labeled with your computer name so that the application looks similar to Figure 12.17.



Figure 12.17 Internet Service Manager

4. Right-click Default Web Site. On the New submenu, click Virtual Directory.
5. In the New Virtual Directory Wizard, type the name docs and then click Next.
6. Click Browse and then locate the \InetPub\WWWRoot\MyActiveXDocs folder. Click OK to specify that this folder will contain the content for the docs virtual directory. Click Next.
7. Accept the default options on the last page of the wizard by clicking Finish. If you click Default Web Site in the left pane, you will see the docs virtual directory displayed in the right pane.
8. Close the Internet Service Manager. Open Internet Explorer and enter the following URL into the address box:

http://[your computer name]/docs/hello.ads

The Hello.ads file should display in the browser as shown in Figure 12.16.

Deploying Content on a Microsoft IIS Personal Web Server

PWS provides the Personal Web Manager utility, which you use to administer a Web site.

In the following exercise, you will use the Personal Web Manager to create the docs virtual directory on the default Web site. The docs virtual directory will host the Hello.ads ActiveX document.

To deploy the Hello.ads ActiveX document

1. Using Windows Explorer, create a new folder under the \InetPub\WWWRoot folder named MyActiveXDocs. Place a copy of the Hello.ads file in this folder.
2. On the Start menu, click Programs and then click Microsoft Personal Web Server to start the Personal Web Manager.
3. Personal Web Manager appears with the Main page displayed. Click Advanced in the left pane so that the application looks similar to Figure 12.18.



Figure 12.18 Personal Web Manager

4. With the home directory item selected, as shown in Figure 12.18, click Add.
5. The Add Directory Wizard appears. In the Alias box, type docs. Click Browse to locate the \InetPub\WWWRoot\MyActiveXDocs folder. Click OK to add this folder to the Directory box. Click OK to create the virtual directory.
6. Check that the docs virtual directory has been added beneath the home directory in the Virtual Directories window. Close the Personal Web Manager.
7. Launch Internet Explorer and enter the following URL into the address box:

http://[your computer name]/docs/hello.ads

The Hello.ads file should display in the browser as shown in Figure 12.16.

Lesson Summary

ActiveX documents are created by an ActiveX document server application. ActiveX documents can be viewed and edited by the server application that created them, and by any ActiveX document container application. When a container application loads an ActiveX document, it loads resources from the associated server application. The menus and toolbars are merged with those of the container frame window to make the functionality of the server application available from within the container application.

Internet Explorer is the most widely used ActiveX document container application. Internet Explorer is frequently used to view and edit ActiveX documents deployed on Web sites. You can use ActiveX documents to provide a much richer interface to Web site data than you can with standard HTML pages.

You are required to have the ActiveX document server application installed on your local computer before you can view ActiveX documents over the Internet. This means that ActiveX documents are best used in a situation where you are in a position to specify the platform and configuration of the client computers, such as on a corporate intranet.

The MFC AppWizard that comes with Visual C++ 6.0 provides options that make it easy to create an ActiveX server application.