Posting Files to Your Intranet or Extranet - 19 Jun 2000

Last month, I talked about getting Microsoft Posting Acceptor to work on Microsoft IIS. This month, I continue with a look at the file upload control (flupl.ocx) and how it enhances basic Posting Acceptor capabilities with user-friendly features such as drag and drop. Posting Acceptor is a server-side component that handles the HTTP upload of files to a Web server. The example I use in this article assumes that you already have Posting Acceptor working correctly on your Web server. As with any client-side ActiveX control, the client needs a browser that supports ActiveX.

I approach the file upload control in three steps. First, I talk about the Active Server Pages (ASP) involved when a client loads flupl.ocx. Next, I show you how to create a basic ASP page that uses the control and discuss the settings you need for flupl.ocx to work (I also briefly describe where to look if the control isn’t working). Finally, I go beyond the basic ASP page and provide some customization tips to enhance flupl.ocx.

Configuring the ASP to Use Flupl.ocx
When a client uses the file upload control, the control needs to know where Posting Acceptor exists on the Web server so that it can submit files. For the control to succeed, three different ASP pages need to work together:

The basic interaction among these pages is that when the page containing flupl.ocx loads, the control makes an HTTP query for your site’s default Web page. For example, on the site http://www.interknowlogy.com, flupl.ocx opens http://www.interknowlogy.com/default.asp (because the control relies on the default page; however, it sends only the base URL—e.g., http://www.interknowlogy.com). The control then examines the content of this page for a metatag named postinfo. This tag tells flupl.ocx where to find the file postinfo.asp, which is part of the Posting Acceptor installation. The tag usually reads

/Scripts/postinfo.asp

references the virtual directory and file that contain the details of your Posting Acceptor implementation. Flupl.ocx initializes only if it can locate both the postinfo metatag and the accompanying postinfo.asp file from your site’s default Web page. The control uses the site’s base URL to make separate HTTP queries to the current server. The control first parses the site’s default page looking for the metatag just described so that it can query the server. Using the value defined in the content portion of the metatag, the control then parses the returned file looking for information about how to connect to Posting Acceptor. Flupl.ocx must get its initial settings from postinfo.asp. If the control can’t access the virtual directory or the ASP file is missing, flupl.ocx will remain disabled regardless of Posting Acceptor’s status. If the directory containing postinfo.asp requires authorization, flupl.ocx will query the client browser for cached credentials and send them as part of a requery.

Although the Posting Acceptor installation creates postinfo.asp, which Listing 1 shows, the source of your installation affects the default contents of that file. If you read Ken Spencer’s Windows 2000 Magazine article "Using Posting Acceptor in Site Server Express 3.0" (August 1999) and downloaded the Microsoft Site Server Express 3.0 software tools, your postinfo.asp file consists of several lines that don’t appear in Listing 1. In addition to the basic lines that Listing 1 shows, the Site Server Express version of postinfo.asp has logic to ensure that a validated user is calling it. This version also references an additional include file, pasetup.inc, to set common values and returns additional lines. However, if you installed Posting Acceptor from Disk 2 of Microsoft Visual Studio (VS), you have the much smaller postinfo.asp file that Listing 1 shows.

In either case, the first five lines in postinfo.asp are the same no matter which version you use. The first line is the version information. (Currently, these components are at version 1.5.) The next line is a globally unique ID (GUID) enclosed in brackets.

The third line displays a value for the PostingURL. This value provides flupl.ocx with the fully qualified reference to Posting Acceptor. This line is always present in the default postinfo.asp files, but its inclusion is optional. Later in this article, I show you how to customize the settings that flupl.ocx uses, but you can leave the line and the default reference in postinfo.asp if you want.

The fourth line defines the TargetURL. As with PostingURL, this value is optional. TargetURL defines the upload directory on your Web server. However, keep in mind that the default page on your Web site contains a reference to postinfo.asp, and some clients could use this reference to discover which directory on your server has Write permission. Thus, I prefer to give TargetURL an invalid value both for security and customization reasons. However, if the PostingURL or TargetURL values in postinfo.asp are invalid, your default use of flupl.ocx in myfluplenh.asp, which I discuss in the next section, won’t work.

The final value in Listing 1 is ComponentInstall. Setting this value to "yes" indicates that the component GUID previously defined is on the server.

Getting Flupl.ocx to Work
To access flupl.ocx from Microsoft Visual InterDev, you can create a new ASP page called myfluplenh.asp. Open the Toolbox in Visual InterDev, and click ActiveX Controls. Right-click the display area under this button, and select Customize Toolbox to access the Customize Toolbox dialog box, which Figure 1 shows. Click the ActiveX Controls tab, then scroll through the list of tools until you reach Microsoft ActiveX Upload Control. Notice that beside the name of the control, the dialog box shows the physical path to the control. From Windows Explorer, you can go to this directory, right-click flupl.ocx, and select Properties. The Version tab on the Properties dialog box should show version 7.0.794.27.

On the ActiveX Controls tab, select the check box beside the tool name, then click OK. This process creates a new entry at the bottom of the list of ActiveX Controls in the Visual InterDev Toolbox. You can now select this entry and drag it onto your new myfluplenh.asp page. With the control on a blank page, you can begin to reference the sample code in Listing 2.

The top portion of Listing 2 contains code that sets up the local variables that you’ll use to customize portions of the client script. A couple of these values might seem familiar from last month’s article. The variables build the same two key references that Posting Acceptor uses as input parameters. The value PostingURL matches the Action attribute on the upload form from last month. The TargetURL sent as a form element is used for the same purpose in a call to initialize flupl.ocx.

Although two key references are the same, two differences exist between flupl.ocx and last month’s form:

Flupl.ocx encapsulates the call to the server when it uploads the file. The effects of this difference are twofold. First, you can’t add custom values to the form data sent to postupload.asp. Second, the call to the repost page, postupload.asp, isn’t necessary. However, I suggest that you use postupload.asp because a problem exists when clients make two uploads from different directories that contain a file with the same name. For information about this problem, see the Microsoft article "Posting Acceptor Release Notes" (http://support.microsoft.com/support/kb/articles/q230/2/98.asp). When you have Posting Acceptor call postupload.asp, secondary processing, such as renaming or relocating the uploaded files, can occur to prevent naming conflicts.

The dynamic HTML sent to the client differs in several important ways. First, the tag includes a reference to execute client script when the document loads. The call to InitControls() ensures that the control includes the PostingURL and TargetURL that the server defined. Second, the function InitControls() in the client script makes two calls to the Posting Acceptor object initialized on the page body. The first call is to CreateTempBinding, which provides the TargetURL on the Web server and references the Posting Acceptor GUID. The second call is to SetBindingParam, which sets the named parameter, PostingURL, to the desired value. In this case, you’re overriding the default value from the postinfo.asp file with one that references the location of both Posting Acceptor and postupload.asp. (For information about these calls, go to the Microsoft Developer Network—MSDN—Web Workshop at http://msdn.microsoft.com/workshop/management/tools/reference/file_upload_control.asp.)You’ve now created a basic working instance of the file upload control in myfluplenh.asp. To avoid memory conflicts, always test uploading files from a machine other than the Web server that is hosting Posting Acceptor. You can drag and drop files either from Windows Explorer or from your desktop directly onto the control in your browser. You can also click the control image to access the Open dialog box. From that dialog box, you can select one or more files. The selected files will upload when you click Open.

Troubleshooting Myfluplenh.asp
If you’re having problems, be sure to review the baseline setup for Posting Acceptor that I described last month. In particular, ensure that you can use the upload.asp and repost.asp pages to successfully upload files to your server. If you’ve verified that Posting Acceptor is working, ensure that the metatag referencing postinfo.asp is present on your server’s default page. Without this tag, the control won’t be able to make a request for postinfo.asp.

Next, attempt to open postinfo.asp from your browser. This step verifies that flupl.ocx can get the data from that file. If this step works, then verify that the values used for the TargetURL and PostingURL in myfluplenh.asp match those that the working upload.asp file is using.

Going Beyond the Basics
To customize flupl.ocx, you need to know some additional methods, properties, and events. The easiest way I’ve found to view an object’s properties is to look at the object in Microsoft Visual Basic’s (VB’s) Object Browser. To view flupl.ocx, open a new VB project, then choose References from the Project menu. Scroll through the list of available references, and select the FlUpl Upload Control. Close the References window, then choose Object Browser from the View menu. Figure 2 shows the properties, methods, and events that the file upload control supports. The list is long, and demonstrating all the items is beyond the scope of this article. However, it seems appropriate to cover a couple of items and see how they work.

Let’s start with the object parameters that show up in myfluplenh.asp. These parameters represent two properties of flupl.ocx. If you see a graphic in Visual InterDev instead of the text for the control, go to InterDev’s View menu and choose View controls as text. Now you should see an object definition that matches the one in Listing 2. By default, the control has two parameter values defined to "" and 0, respectively. The first property, ImageSrc, determines what image to display for the file upload control. Flupl.ocx uses the image that the ImageSrc property specifies unless the value of the second parameter, AlternateGraphic, is 1. When you change the value of this entry from 0 to 1 and you define a valid image for the ImageSrc property, flupl.ocx displays a second image embedded in the file upload control. This step generates three options:

Following the function InitControls() you’ll see some additional functions that I’ve provided to further enhance flupl.ocx. The first function, OpenBrowse(), opens a file browse window when you call it. Another nice feature with myfluplenh.asp is notification of the completion of a large upload. Although flupl.ocx provides a dialog box with a progress bar while the upload is taking place, the progress bar doesn’t update, although the display changes as each file starts uploading. Myfluplenh.asp implements two events from the file upload control to provide feedback to the user after the upload is complete.

The first event, UploadedFile, occurs for each uploaded file. Unfortunately, the event doesn’t occur immediately after each upload, but instead fires repeatedly after all uploads are complete. Myfluplenh.asp simply uses this event to count the number of uploaded files.

The UploadComplete event occurs once after flupl.ocx has finished uploading the selected files. Myfluplenh.asp modifies this event to check that at least one file was uploaded and then presents a message with the number of uploaded files to the user. This feedback lets users leave a computer conducting a large update unattended or leave their browser in the background while doing other work until the upload is complete.

With the relatively minor additions I made in myfluplenh.asp, you can use the file upload control’s built-in properties, methods, and events to enhance it. If you intend to use this control in your intranet or extranet, you might want to get a copy of the cabinet files included with Site Server Express 3.0 software tools, which contain flupl.ocx and add the appropriate codebase statement to the object declaration.