In this chapter, you will learn about an exciting new Visual Basic 5 intranet/Internet technology called ActiveX documents. This chapter will show you how to create ActiveX documents and suggest how, when, and where to use ActiveX documents.
ActiveX documents enable you to develop Visual Basic 5 applications that can be used in container applications, such as Microsoft Internet Explorer or Microsoft Outlook. An ActiveX document is not a traditional standard word processing document, such as a Microsoft Word document or a Lotus Word Pro document. Instead, think of an ActiveX document as a Visual Basic Internet application. ActiveX documents are designed and created in the Visual Basic 5 development environment and can use ActiveX controls and forms.
You might be confused by the word document in ActiveX document instead of application. Step back for a moment and think about a Microsoft Excel spreadsheet used to compute a tax return. The spreadsheet contains the formulas and data required to generate a tax return. The spreadsheet offers application-like functionality because it can be used to perform tasks such as computing tax returns. The spreadsheet alone is not an application, however; it requires the application Microsoft Excel to create and use the spreadsheet. You can give your friends a copy of the tax return spreadsheet, and they can do their taxes as long as they have Microsoft Excel. One other point: The Excel spreadsheet also can be viewed in other applications that act as containers--for example, a Visual Basic application using the OLE2 custom control. An ActiveX document created in Visual Basic 5 is similar to the Excel spreadsheet. By itself, the ActiveX document is not an application. With a valid container application and ActiveX component, the ActiveX document performs like an application.
To help you nail down the full concept of an ActiveX document, look at the example
shown in Figure 15.1.
FIGURE
15.1.Visual Basic ActiveX document architecture.
Figure 15.1 shows the Microsoft Internet Explorer acting as a container application for an ActiveX document. The file names.vbd is the ActiveX document. The ActiveX document contains textboxes and buttons that enable users to update a database with personal address information. In order for an ActiveX document to execute, an ActiveX component, in addition to a container application and an ActiveX document, is required (such as an Excel spreadsheet requiring Microsoft Excel). When you create an ActiveX document with Visual Basic 5, a document file (.vbd extension) and an ActiveX component are generated (in-process, such as DLL, or out-of-process, such as EXE).
When using an ActiveX document in a Web application, the ActiveX document is not placed on a Web page; instead, the ActiveX document replaces the Web page. When a user accesses a URL with an ActiveX document, the ActiveX document and any required ActiveX controls are loaded to the client machine along with the ActiveX component required to execute the ActiveX document. The downloaded ActiveX controls and the ActiveX component are registered on the client machine. The HTML page that loads the ActiveX document uses script to invoke the ActiveX document via the OnLoad event. The HTML page is replaced by the ActiveX document, and the ActiveX document executes in the container application on the client machine. ActiveX documents cannot execute without a container application.
ActiveX documents are a really cool Visual Basic 5 feature, but those of you who program for a living and want to try out this new technology will ultimately face the manager afraid of technology or the internal software police who must study every technology to death (until it's old technology) and officially approve it before anyone is allowed to use it. How do you justify using ActiveX documents? I believe that the strength of ActiveX documents will prove to be in an intranet environment as opposed to an Internet environment. In an intranet environment, ActiveX documents enable you to perform these tasks:
If you are thinking that these tasks are identical to the tasks you currently use Visual Basic and other development tools to perform, you are correct. But the advantage that ActiveX documents offer over current development tools is the buzzword of the late 1990s: lower-cost ownership. ActiveX documents are easier to install and maintain than existing client/server applications, which results in a lower cost of ownership. ActiveX documents install themselves from a central code base, for example. No information system personnel must go from PC to PC (or use software such as Microsoft SMS) to perform software installations. When a new employee starts work, instead of ensuring that he has all the proper applications, you can have them access a URL, and the application installs itself. When the ActiveX document requires a revision, you just have to change the software in one location. No need to worry about upgrading a user to a newer version or that a user is working with an older version. When a user accesses the revision via a Web browser, the ActiveX document automatically upgrades itself.
The ease of software distribution via ActiveX documents makes ActiveX documents very attractive in an intranet environment. If your company executes all your applications from a central directory on a LAN instead of installing them on users' PCs, you probably are thinking that ActiveX documents will not cut your cost of ownership because your applications are installed in only one location anyway. In this type of environment, ActiveX documents offer better performance because running applications from a LAN is always slower than executing them from a client PC. Also, you have the added benefit of no software distribution requirements. And even though you might have all your applications installed on a LAN, IS personnel are often required to run minimum setup and installation procedures on client machines when giving them access to new applications.
ActiveX documents are not restricted to the intranet and can be used as well on the Internet. You might want to use an ActiveX document when you find HTML and VBScript lacking in functionality for a complex client form. You might prefer to use ActiveX documents instead of a standard HTML page because of the powerful features of Visual Basic 5's design environment and integrated debugger compared to the current HTML and scripting environment.
ActiveX documents are easy to build and test. This section will give you a detailed walkthrough of the steps required to create an ActiveX document. You will learn about the primary object that makes up an ActiveX document: the UserDocument object.
Before going over the steps required to create an ActiveX document, you should understand the primary object used to create ActiveX documents: the UserDocument. The UserDocument is the equivalent of a Visual Basic form in a standard client/server project. Like a standard Visual Basic form, the UserDocument object has events, properties, methods, and ActiveX controls (except the OLE2 control) that can be placed on the UserDocument object.
To create an ActiveX document, follow these steps:
FIGURE 15.2.The Visual Basic New Project dialog box.
The new project contains a single UserDocument object called UserDocument1.
FIGURE 15.3. The UserDocument object in a Visual Basic project.
FIGURE 15.4. The UserDocument object with ActiveX controls.
You now have constructed an ActiveX document.
You now are ready to test the ActiveX document you created. To test the ActiveX
document, run the project from Visual Basic by choosing Run | Start. Open Microsoft
Internet Explorer. From Microsoft Internet Explorer, open the User1Document.vbd
file. The file is located in your Visual Basic directory, because the project was
not saved. The ActiveX document loads into Internet Explorer, as shown in Figure
15.5.
FIGURE
15.5. Microsoft Internet Explorer displaying
an ActiveX document for database manipulation.
Click the data control. Notice the way in which you move through each record. Try to update a record. Your ActiveX document is manipulating the Authors table as if you had generated a standard Visual Basic project, except that you are doing it from within a browser.
You can debug ActiveX documents by using the same techniques you normally use when debugging Visual Basic projects, such as setting breakpoints and stepping through code. Remember that your ActiveX document uses a container application such as Microsoft Internet Explorer, however, and stopping the ActiveX document could cause errors to occur in the container application. Breaking into a running ActiveX document project by using a breakpoint or pressing Ctrl+Break does not cause errors in Internet Explorer. Also, single-stepping through code does not cause errors to occur in Internet Explorer. Stopping the application or changing code that requires resetting the project and starting a new session without shutting down Internet Explorer first causes errors in Internet Explorer. So before stopping your ActiveX document when debugging, it's a good practice to first quit the container application (Internet Explorer) and then stop your ActiveX document.
When you create an executable for an ActiveX document using Visual Basic 5, two files are generated: the ActiveX document that has the file extension .vbd and the ActiveX component required by the ActiveX component (a DLL or EXE). To access your ActiveX document from the Web, you first need to reference the document in HTML. Because the ActiveX document will replace the existing HTML page, you should create a special HTML page that references your ActiveX document by using the <OBJECT> tag, as well as invoking the ActiveX document event Window_OnLoad. You then can jump to the ActiveX document HTML page from another HTML page by using an anchor link or a redirect. Listing 15.1 shows an example of an HTML page used to load an ActiveX document called UserDocument1.
Listing 15.1. An HTML page to load an ActiveX document.
<HTML>
<OBJECT ID="UserDocument1"
CLASSID="CLSID:9D456E21-883D-11D0-9CE8-444553540000"
CODEBASE="Project1.CAB#version=1,0,0,0">
</OBJECT>
<SCRIPT LANGUAGE="VBScript">
Sub Window_OnLoad
Document.Open
Document.Write "<FRAMESET>"
Document.Write "<FRAME SRC=""UserDocument1.VBD"">"
Document.Write "</FRAMESET>"
Document.Close
End Sub
</SCRIPT>
</HTML>
The HTML and script in Listing 15.1 will load the UserDocument object and the ActiveX component from a Website, install and register them on a client machine, and activate the ActiveX document. The ActiveX document and ActiveX component are compressed together in a special download file called a cabinet file. Cabinet files and Internet/intranet distribution are covered in detail in Chapter 17, "Distributing ActiveX Documents and Controls via the Web Using VB 5."
Earlier in this chapter, I told you to think of an ActiveX document as an Internet
version of a Visual Basic application, and the UserDocument object as a
Visual Basic form. And these are good analogies. However, when creating an ActiveX
document project, you can add standard Visual Basic forms to your project. The forms
are Visual Basic forms rather than ActiveX documents. A form must be called initially
by an ActiveX document, which means that a user cannot access that form without first
accessing an ActiveX document. After a form is loaded, it can load other forms. The
one restriction when using forms is that if your ActiveX component is a DLL (in-process),
forms can be loaded only as modal. Figure 15.6 shows a database application that
uses a form to display a secondary table in a grid.
FIGURE
15.6 An ActiveX document and form displaying
database information.
Notice how the form in Figure 15.6 looks exactly like a standard Visual Basic form (after all, it is a standard Visual Basic form). The form was created by selecting Database Grid Form from the Form Wizard. Both the form and the ActiveX document in this figure use ActiveX data controls and DAO. The database used is the Microsoft Access database Biblio.mdb.
In addition to adding forms to an ActiveX document project, you can add additional UserDocuments in much the same way that you add an additional form. You can add additional forms and UserDocuments to a project by choosing Project | Add Form or Add UserDocument. Each UserDocument object you add to a project generates an ActiveX document (a file with a vbd extension). A single ActiveX component is generated and shared by all the ActiveX documents in the project.
So what are the guidelines for using forms or UserDocuments when building screens in an ActiveX document application? If you want the user screen to be contained within the browser, you should use ActiveX documents. If you want to navigate directly to the user screen, you should use a UserDocument because forms can be called only from ActiveX documents. Use forms when the screen you are displaying to the user is a secondary screen that requires a user to start from the ActiveX document.
The same syntax is used to display a form from an ActiveX document as a standard Visual Basic application. The following line of code called from an ActiveX document, for example, displays a modeless form named frmTest:
frmTest.Show
This line of code called from an ActiveX document shows a modal form:
frmTest.Show vbModal
Remember that when you use Internet Explorer as a container application, ActiveX documents that use in-process components (DLLs) can show only modal forms. To help determine whether a container can display a modal form, you can use an App object property new to Visual Basic 5: NonModalAllowed. If NonModalAllowed is True, the container can show modal forms. The following code checks the App object property NonModalAllowed and displays a modal or non-modal form based on the property value.
If App.NonModalAllowed Then
frmTest.Show
Else
frmTest.Show vbModal
End If
Navigating between ActiveX documents requires a different technique. To navigate from one user document to another requires using the Visual Basic 5 Hyperlink object and the UserDocument object. The Hyperlink object enables you to jump to a URL in a Web environment. The Hyperlink object has the following methods:
Use the base ActiveX document object, UserDocument, to navigate between ActiveX documents. To navigate to another ActiveX document, for example, use the UserDocument property Hyperlink, which obtains a reference to the Hyperlink object. The following code is in the click event of an ActiveX document called UserDocument1 and navigates the Web browser to a second ActiveX document located in the same directory called UserDocument2:
Private Sub Command1_Click()
UserDocument.Hyperlink.NavigateTo _
App.Path & "\" & "UserDocument2.vbd"
End Sub
When creating a standard Visual Basic application, you can control the order in which clients view your forms. For example, Form2 is loaded from a button on the startup form (for example, Form1). The user can't get to Form2 without first starting at Form1. ActiveX documents don't offer you the same luxury and control over your user; because ActiveX documents are standalone objects, users can access them directly by entering the URL. You also may have ActiveX documents that need to share information. Sharing information or tracking document order requires the use of global variables. To add global variables to an ActiveX document application, add a standard Visual Basic module to the project. Declare the global variables shared by the ActiveX documents in the module. This example declares a global string variable called strDoc:
Public strDoc as String
To share information, set the variables in one ActiveX document and read them from another or modify them. You also can declare global references to objects such as a UserDocument object. You can use global variables of object references or other data types to track document order. When using an object, use the function Is Nothing to determine whether the object is set. If the object or global variable has been set properly, you know the correct document order has been followed. If the variable is not set properly, you can use the Hyperlink object to force the user to the proper starting ActiveX document. If you use global object variables, make sure that you set them to Nothing when you are finished to properly release the object reference.
ActiveX documents have some very unique features that make them very easy to use in an intranet/Internet environment, such as the capability to persist data and asynchronous downloading capabilities. This section takes a closer look at some additional ActiveX document features.
If an ActiveX document has a menu, the menu is merged with the menu of the container
application. You add menus to ActiveX documents in the same way that you add menus
to a Visual Basic form, by using the Visual Basic Menu Editor. Figure 15.7 shows
an example of an ActiveX document's menu merged with Microsoft Internet Explorer's
menu.
FIGURE 15.7. An ActiveX document menu merged with Microsoft Internet
Explorer.
When using Microsoft Internet Explorer as a container application for an ActiveX document, you can use an object called PropertyBag to save and store data for the ActiveX document. After data is saved, the next time the ActiveX document is loaded, the saved properties can be retrieved and placed in the ActiveX document. When using Microsoft Internet Explorer, the values you save are written to the ActiveX document vbd file. The PropertyBag object has two methods: ReadProperty and WriteProperty. ReadProperty is used to read property values from the property bag, and WriteProperty is used to write values to the property bag. To write properties to the property bag when a value on the ActiveX form has changed, execute the PropertyChanged method, which notifies Internet Explorer that a property has changed. When Internet Explorer is terminated or moves to another page, the UserDocument WriteProperties event is fired. When the event fires, save any UserDocument variables by using the PropertyBag object's WriteProperty method. The variable name used to save the value does not have to match the name of the ActiveX control (label and textbox, for example) on the ActiveX document. The following example saves an ActiveX textbox named MyText to a file by using the PropertyBag object:
Private Sub UserDocument_WriteProperties(PropBag As PropertyBag)
PropBag.WriteProperty "MyText", MyText.Text
End Sub
The syntax for the PropertyBag object's WriteProperty method follows:
PropBag.WriteProperty Variable, Value_to_Store, Default_Value
(Note: The Default_Value is optional.) When the ActiveX document is read, the ReadProperties event of the UserDocument object fires. When the event fires, use the PropertyBag object's ReadProperty method to retrieve values and place them in the ActiveX document. The following example reads the variable MyText stored in the WriteProperties event and sets the value of the ActiveX control MyText on the ActiveX document:
Private Sub UserDocument_ReadProperties(PropBag As PropertyBag)
MyText.Text = PropBag.ReadProperty("MyText")
End Sub
The syntax for the PropertyBag object's ReadProperty method follows:
PropBag.ReadProperty(Value_to_Retrieve,Default)
(Note: The Default_Value is optional.) You also can save and read binary data types, such as pictures, by using the PropertyBag object's methods.
ActiveX documents can be displayed only in a container application such as Microsoft
Internet Explorer. The viewing area of the container application in which the ActiveX
document is displayed is called the ViewPort. Because an ActiveX document is designed
to run in a container application, you can never be sure of the viewing area provided
by the container application. If the container application viewing area is not large
enough to display your ActiveX document, scrollbars appear so that the ActiveX document
can be viewed. The UserDocument properties MinHeight and MinWidth
set the minimum amount of viewing area required before scrollbars appear. Figure
15.8 shows an ActiveX document with scrollbars as a result of using a ViewPort that
is too small.
FIGURE
15.8. An ActiveX document with
scrollbars.
ActiveX documents support asynchronous downloads. Using asynchronous downloading, an ActiveX document can load large objects such as pictures or bitmaps in the background, which enables the ActiveX document to display before all the graphics arrive. To use asynchronous downloading, use the AsyncRead method of the UserDocument object. AsyncRead initiates the downloading process. When the download completes, the AsynchReadComplete event is fired.
ActiveX documents sound great, but it sure would be nice to try them out with
existing applications to check out the benefits of an ActiveX document database application
in an intranet environment. No problem! Visual Basic 5 comes with an ActiveX Document
Migration Wizard that migrates existing applications to ActiveX documents. This section
walks you through the conversion of an existing Visual Basic database application
into an ActiveX document database application. Figure 15.9 shows the Visual Basic
application you'll migrate in this section.
FIGURE 15.9. A Visual
Basic database application.
The database application in Figure 15.9 uses a Microsoft Access database that is located on a shared drive on a LAN. The database is used by 15 to 20 users. The application uses DAO to access the database. Whenever the application is modified, the new executable must be installed on all the user machines that use the application. Now take a look at the steps required to upgrade the application to ActiveX documents. The ActiveX Document Migration Wizard is a Visual Basic add-in.
To modify an existing Visual Basic project to an ActiveX document, follow these steps:
FIGURE 15.10.The ActiveX Document Migration Wizard-Form Selection dialog box.
FIGURE 15.11. The ActiveX Document Migration Wizard-Options dialog box.
FIGURE 15.12. The ActiveX Document Migration Wizard-Finished dialog box.
Keep in mind that when you migrate database applications to an intranet environment
using ActiveX documents, the client PCs still must have the proper ODBC drivers installed
on their machines when accessing an ODBC database. When using file databases, such
as Microsoft Access, it is a good idea to use the full network UNC name for the location
of the database file (for example, \\SERVER\SHARE\Directory path\FILE) instead
of just using a shared drive letter. Using the full network name removes the possibility
of your application not finding the database because of different drive mappings
on a client PC.
FIGURE
15.13. Migrating Visual Basic applications
to ActiveX documents.
ActiveX documents enable you to bring your current Visual Basic database skills to the intranet. You can easily create new Web-based database applications that use current Visual Basic database object models, such as DAO and RDO. You also can use the Migration Wizard to transform existing Visual Basic applications into ActiveX documents. The major benefit of ActiveX document database applications is the capability to automatically distribute the software and any modifications via the Web. ActiveX documents are not restricted to the intranet. You can use ActiveX documents to replace existing HTML pages or in cases when performing a client-side task is too difficult to perform with HTML and script on the Internet.
