Microsoft KB Archive/178057

= How To Share State Between UserDocuments in Internet Explorer =

Article ID: 178057

Article Last Modified on 7/13/2004

-

APPLIES TO


 * Microsoft Internet Explorer 3.0
 * Microsoft Internet Explorer 3.01
 * Microsoft Internet Explorer 3.02
 * Microsoft Internet Explorer 4.0 128-Bit Edition
 * Microsoft Internet Explorer 5.0
 * Microsoft Internet Explorer 5.5
 * Microsoft Visual Basic 5.0 Professional Edition
 * Microsoft Visual Basic 5.0 Enterprise Edition

-



This article was previously published under Q178057



SUMMARY
When you have multiple UserDocuments in your application, you may want to share information between them. If a single ActiveX document server supports all the documents, then you can use global variables in your server to share state information. However, if they are on separate servers, you cannot use the global variables to share state information. This article shows you how to share state information between multiple UserDocuments. Internet Explorer 3.x and higher have a built-in facility for storing and retrieving property values through a global property bag. Since version 4.0, Internet Explorer has a feature that allows users to automatically expire data stored in the property bag.



MORE INFORMATION
To access the global property bag from your Visual Basic UserDocument code use the PutProperty and GetProperty methods of your document's host (for example, the IWebBrowserApp interface in Internet Explorer). You can access these methods through a UserDocument.Parent reference. A unique tag, which can be any string, identifies the data. The stored value is a Variant. This means that you can store any kind of data including references to objects.

Use the following statement to store data:

UserDocument.Parent.PutProperty "Tag", Value

Use the following statement to retrieve a previously stored value:

v = UserDocument.Parent.GetProperty("Tag")

If the value that is being stored is an object reference, then use the following statement:

Set v = UserDocument.Parent.GetProperty("Tag")

Storing objects is a convenient and flexible approach. The stored data remains there as long as the browser window is open. Internet Explorer 3.x and higher support this feature. In Internet Explorer 4.x and 5.0, you can also automatically expire the data. Internet Explorer can automatically remove a property if it has not been accessed for a set period of time. This procedure is described later in this article.

PutProperty and GetProperty can be called from anywhere except the Initialize event of the UserDocument.

EXAMPLE
Suppose you want to create two documents to collect and verify name and company information (as in some setup programs). The first document requests the user's name and company name. The second document displays these two fields for verification purposes. Follow the instructions below to create two Visual Basic projects that illustrate this technique.

Creating PropBag1.vbp
 In Visual Basic, create an ActiveX Document DLL project. On the File menu, choose New Project and double-click the Active X Document DLL icon. Save the Project. Click Save Project on the File menu. Use Doc1.dob as the document file name and PropBag1.vbp as the project file name. Name the project. Make sure Project1(ProbBag1.vbp) is highlighted in the Project window. In the Properties window, change the project name to PropBag1. Name the user document. Expand the User Documents folder in the Project window and double-click on UserDocument1. In the Properties window, change the name to Doc1. Add controls to Doc1. Add two text boxes to the form. Name them txtName and txtCompany, respectively. Clear the Text property in both text boxes. Add a Command button and set the following properties for the Command button:

Name: cmdNext Caption: Next

  Add a Class module to the PropBag1 project. Click Add ClassModule on the Project menu. Name the Class module clsMySharedState. The state information you want to share will be stored in an instance of this class. Paste the following code into the General Declarations section of the clsMySharedState class code window:

Sample Code
Option Explicit

'Normally you will use Module-level variables 'and access them from Properties. This example 'uses Globals for simplicity. Public YourName As String Public YourCompany As String

Private Sub Class_Initialize YourName = "" YourCompany = "" End Sub </ol>

To request information from the user, check the property bag to see if a reference already exists. If a reference does not exist, create it and set fields in the object to values on the screen. Use the PutProperty method to store the object in the Internet Explorer property bag. Finally, navigate to the second document. <ol>  Paste the following code into the cmdNext_Click event procedure of Doc1:

Sample Code
Private Sub cmdNext_Click Dim State As clsMySharedState Dim Found As Boolean

'Check the property bag to see if there is a reference 'to the object. On Error Resume Next Set State = UserDocument.Parent.GetProperty("PropBag.SharedState") Found = (Err.Number = 0) On Error GoTo 0

If Not Found Then 'Create and store the object reference in the property bag. Set State = New clsMySharedState UserDocument.Parent.PutProperty ("PropBag.SharedState"), State End If

'Save information into the shared state. State.YourName = txtName State.YourCompany = txtCompany

'Navigate to the second document. UserDocument.Hyperlink.NavigateTo App.Path + "\Doc2.VBD" End Sub </li>  Add the following code to the UserDocument_Show event of Doc1 to populate the text boxes when the user returns to Doc1:

Sample Code
Private Sub UserDocument_Show Dim State As clsMySharedState Dim Found As Boolean

'Check the property bag to see if there is a reference 'to the object. On Error Resume Next Set State = UserDocument.Parent.GetProperty("PropBag.SharedState") Found = (Err.Number = 0) On Error GoTo 0

If Found Then txtName = State.YourName txtCompany = State.YourCompany End If End Sub </li> Compile the project. Click Make PropBag1.dll... on the File menu to compile the project into PropBag1.dll.</li> Set the version compatibility for Propbag1.dll to Binary Compatibility. Click PropBag1 Properties on the Project menu. Choose the Component tab and set the version compatibility for PropBag1.dll to Binary Compatibility. (Click the ellipsis button to browse for the PropBag1.dll).</li> Save the project. Click Save Project on the File menu.</li></ol>

Creating PropBag2.vbp
<ol> In Visual Basic, create an ActiveX Document EXE project. On the File menu, choose New Project and double-click the Active X Document EXE icon.</li> Save the Project. Click Save Project on the File menu. Use Doc2.dob as the document file name and PropBag2.vbp as the project file name.</li> Name the project. Make sure Project2(ProbBag2.vbp) is highlighted in the Project window. In the Properties window, change the project name to PropBag2.</li> Name the user document. Expand the User Documents folder in the Project window and double-click on UserDocument2. In the Properties window, change the name to Doc2.</li> Add a reference to clsMySharedState. Click References... on the Project menu. Select PropBag1.dll and click OK.</li> Add controls to Doc2. Add two labels to the Doc2 form. Name them lblName and lblCompany, respectively. Clear the Caption property of each control.</li>  Add code to retrieve the object stored in the Internet Explorer property bag and display the information. Add the following code to Doc2 in the UserDocument_Show event:

Sample Code
Private Sub UserDocument_Show Dim State As clsMySharedState Dim Found As Boolean

'Check the property bag to see if an object is already there On Error Resume Next Set State = UserDocument.Parent.GetProperty("PropBag.SharedState") Found = (Err.Number = 0) On Error GoTo 0

If Found Then 'Display the information in Doc2 lblName = State.YourName lblCompany = State.YourCompany End If End Sub </li> Compile the project. Click Make PropBag2.exe[ASCII 133] on the File menu to compile the project into PropBag2.exe.</li> Set the version compatibility for Propbag2.exe to Binary Compatibility. On the Project menu, click PropBag2 Properties. Choose the Component tab and set the version compatibility for PropBag2.exe to Binary Compatibility. (Click the ellipsis button to browse for the PropBag2.exe).</li> Save the project. Click Save Project from the File menu.</li></ol>

To test the sample:
 * 1) Open Internet Explorer.
 * 2) Drag Doc1.vbd from Windows Explorer into Internet Explorer. This will run Doc1.
 * 3) Enter your name and company name.
 * 4) Click the Next button to go to Doc2. Your name and company name should appear in the labels.
 * 5) Click the Back button on Internet Explorer. You should return to Doc1 and still see your name and company name. You can navigate to another location such as www.microsoft.com and then return to your user document.

Using the Internet Explorer 4.x and 5.0 Discardable Browser Property
Internet Explorer 4.0 has a new feature known as the Discardable Browser property. This feature is used in conjunction with the property bag. The browser automatically expires and removes the information if it is not accessed after a set period of time. To take advantage of this feature the information stored must be an object, as in the previous example, and the object class must implement the IDiscardableBrowserProperty interface. You can modify the clsMySharedState class to support this feature by creating a type library and modifying clsMySharedState as described below.

Create a type library: <ol>  Use Microsoft Notepad to create a text file with the following text and save it as DiscProp.odl:

Sample Code
[  uuid(30DFC192-230F-11d1-85A4-00AA00C006CB), helpstring("Discardable Browser Property Interface"), version(1.0) ]

library DiscProp {  importlib("stdole2.tlb"); [     uuid(49C3DE7C-D329-11D0-AB73-00C04FC33E80), helpstring("IDiscardableBrowserProperty Interface"), oleautomation ]  interface IDiscardableBrowserProperty:IUnknown {     [helpstring("Never called")] HRESULT DummyProc; } }                   </li> <li>From a command prompt, change to the directory that contains mktyplib.exe. The default should be C:\Program Files\Microsoft Visual Studio\VC98\Bin if you installed Visual Studio 6.</li> <li>Enter the following command to create the type library:

mktyplib C:\DiscProp.odl /tlb C:\DiscProp.tlb

</li> <li>In Visual Basic, click Open Project on the File menu and double-click PropBag1.vbp.</li> <li>Set a reference to the DiscProp.tlb by clicking References... on the Project menu and then browse to look for DiscProp.tlb. This will allow you to implement the IDiscardableBrowserProperty interface with the IID specified in the DiscProp.odl file. Internet Explorer performs a QueryInterface with this IID to see if the object being stored implements this interface. If it does, Internet Explorer can discard the property if it has not been used for the specified length of time.</li></ol>

Modify the clsMySharedState class: <ol> <li>Add the following line in the General Declarations section of the class right after the Option Explicit statement: Implements IDiscardableBrowserProperty</li> <li> Add the following procedure to your class: Private Sub IDiscardableBrowserProperty_DummyProc 'This method is never called. 'It is only included to implement the interface. End Sub </li></ol>

Additional query words: PROPERTY BAG DISCARDABLE

Keywords: kbhowto kbcode KB178057

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.