Inside Technique : Client-side Data Access : Using the Common Dialog Control

Windows defines several dialogs which can be used by programs for common tasks like opening or saving a file, selecting a font or color, or printing a document. The code for these dialogs resides in commdlg.dll in the System directory, but this file cannot be accessed by your browser. Microsoft has however provided an ActiveX control which acts as a wrapper for this file, and this control is accessible by means of a scripting language.

The Common Dialog Control can be added to your page by using the following tag:

<OBJECT ID="CommonDialog1" WIDTH=0 HEIGHT=0
 CLASSID="CLSID:F9043C85-F6F2-101A-A3C9-08002B2F49FB">
</OBJECT>

In order to show the Open File dialog, we use this code:
(Note that we are using VBScript here, I will explain why in a moment.)

CommonDialog1.ShowOpen

The main advantage of using this OCX is the control that you have over the appearance of the dialog. You could change the title of the Dialog by setting the DialogTitle property, and the initial directory displayed in the dialog (your game directory, most likely) by the InitDir property. What’s really interesting, however, is that you can set the Filter property to define which types of files are displayed in the dialog. The Filter property is a string of descriptions and filters, separated by the pipe character. It looks something like this:

Filter='description|filter|description|filter|...'

In order to detect the file that the user selected, you can either use the FileName property, which contains the full path of the selected file, or the FileTitle property, which contains only the file name without the path.

So now let us look at the full implementation of our Open File procedure using the Common Dialog control:

<OBJECT ID="CommonDialog1" WIDTH=0 HEIGHT=0
 CLASSID="CLSID:F9043C85-F6F2-101A-A3C9-08002B2F49FB">
    <PARAM NAME="CancelError" VALUE="1">
    <PARAM NAME="DialogTitle" VALUE="Select Data File">
    <PARAM NAME="Filter" VALUE="Level Data Files (*.lvl)|*.lvl|All
    Files (*.*)|*.*">
</OBJECT>

<A HREF="javascript: LoadFile(location.pathname.substr(1));">
Load Data File</A>

<SCRIPT LANGUAGE="VBScript">
Sub LoadFile(GameDir)
On Error Resume Next
CommonDialog1.InitDir=GameDir
CommonDialog1.ShowOpen
If Err.Number=32755 Then
Err.Clear
On Error Goto 0  ‘ Restore Default Error Handler
Exit Sub
End If
On Error Goto 0
MsgBox "You chose "+CommonDialog1.FileTitle
End Sub
</SCRIPT>

Demonstration requires Internet Explorer 4.0 or later

The first thing you will notice is the parameter CancelError which is set to the value '1'. The explanation for this is as follows: If the user clicks on the Cancel button, the FileTitle property will still hold the name of the selected file. (This is unlike the File Input object where, if the user clicks Cancel, the Value is set to a null string). If the CancelError property is set to '1' (it is '0' by default), the ActiveX object will raise an exception in it’s parent document, namely your web page.

Unfortunately, prior to version 5, Jscript had no built-in error handling capabilities, and IE's window.onError() handler is - how shall we put this nicely - inconsistent. This means that if the user does click the Cancel button, an ugly Jscript error dialog will pop up. However, VBScript does have error handling capabilities. The On Error Resume Next statement will prevent this dialog from being popped up, and is generally used to define custom error handlers. The On Error Goto 0 statement restores the default error handling of the page. This is why the LoadFile procedure is written in VBScript.

Moving on, we see that the LoadFile routine is called with the pathname property of the location object, with the initial '/' character stripped off (that’s what the substr(1) is for). This property contains the directory from which the page was loaded without the preceding protocol string ('http:/' or 'file:/').

The first line after the ShowOpen call checks if an error happened by examining the VBScript Err object. If it’s value is set to 32755 (cdlCancel), it indicates that the user has pressed the Cancel button, so the routine exits after resetting the Err object. If not, the routine restores default error handling and displays the file name of the selected file.

That’s all for the Common Dialog control for now. It may look a bit complicated, but it adds a professional touch to your page. A final word of warning: if you mix VBScript and Jscript on your page, never forget to use the LANGUAGE= attribute of the SCRIPT tag, or you risk confusing the scripting engine, resulting in weird and esoteric error messages like the following:

Fig 1: A 'Zen' error message

Next, we take a look at how the Tabular Data control considerably eases the task of managing structured data.

© 1997-2000 InsideDHTML.com, LLC. All rights reserved.