WebSnap^TM Basics

WebSnap^TM is a new component-based framework introduced in Delphi 6 Enterprise for developing Web Server applications in a RAD environment. This article provides a quick overview of building a simple WebSnap server that will provide a complete editing and browsing interface for a simple dataset that includes a graphic field. Even though this is a "simple" WebSnap server because no code must be written, it is still provides complete functionality for modifying a database table from a browser.

Let's get started.

Creating the WebSnap Server

First, we should display the new WebSnap toolbar that makes creating a WebSnap application much more convenient. We can do this with a right mouse click on the toolbars in the Delphi 6 Enterprise IDE, and turning the "Internet" toolbar on. After doing this, you should see something like this:

The first icon (the hand under the globe) is for creating a new WebSnap application. When you click that, the WebSnap wizard comes up. We'll specify the name of the page to be our Home page. We're also going to make this a Web App Debugger application, which will allow us to use the special web server (written in Delphi) that ships with Delphi 6 Pro and Enterprise. We'll call this server BasicDemo.

After pressing the OK button, you will get a standard Delphi form (which is useful for knowing when the web server is running) and a WebModule that includes the components your Home page will use. The components you see on this webmodule are used for handling page requests and dispatching the actions the browser client requests when the user clicks on specific links or buttons.

Creating a data module

Now we'll create a WebSnap data module we can use to publish information from a dataset (or multiple datasets, for that matter). You can create the WebDataModule by clicking the third button (dataset in front of the globe) on the WebSnap toolbar. Once it's created, I drop a TClientDataSet component from the Data Access tab of the component palette, and point it at a MyBase^TM XML DataSet version of the reliable old Paradox Biolife.db table, which contains a graphic and memo field as well as numeric and text fields we can publish and edit with WebSnap.

Supporting stateless servers

Once the ClientDataSet filename is specified, we can go into the object treeview, expand the ClientDataset, click on Fields, and right mouse click to Add All fields to the tree view. Because WebSnap builds stateless servers for database operations, we must indicate a primary key for the dataset to enable client-requested navigation and data manipulation. WebSnap will do this all for us automatically once we specify the primary key. We'll use the field Species No as the primary key. First, select it in the Object Treeview:

Then, modify its ProviderFlags property in the object inspector to indicate that Species No is the primary key for this dataset by setting pfInKey to True.

If you don't have this dataset, you can do the same thing with the Paradox table using the BDE. The only difference is, you will need to explicitly drop a BDE session component down, set its AutoSessionName property to True, and use a TTable component to point to the DBDEMOS biolife.db table. All other steps should be the same.

Rendering data to the browser

After we've set up the primary key for the dataset, we can select a DataSetAdapter from the WebSnap component palette, shown here.

And drop the DataSetAdapter onto the DataModule. The DataModule should now look something like this:

Now, we hook up the adapter to the dataset by using the Object Inspector. This shot of the Object Inspector shows its support for in-line expansion of component references. Notice how the dataset properties are a different color and indented from the left edge of the Object Inspector view.

This next step is not required, but I'll include it for clarity. We'll go back to the Object Treeview and expand the adapter properties, and add all commands adapters and field adapters for this dataset. You can see that all the standard operations on a dataset are supported (navigation and data modification). The field adapters will provide automatic support for both displaying and editing data in any dataset, including BLOB fields containing text or graphics.

Displaying a data grid with a DataSetAdapter

We use the second button on the WebSnap toolbar (the document in front of the globe) to create another page for this web server. We'll call it our "Grid" page. Leave the default options on. The Published checkbox will make our Grid link displayed on the home page of the server.

Use Unit3 (the WebDataModule) in this unit so we can see the DataSetAdapters declared on it. In this case, of course, there's only one. Then, in the Object Treeview, right mouse click on the AdapterPageProducer's WebPageItems and add an AdapterForm component. Then add an AdapterGrid to the AdapterForm.

Set the AdapterGrid's Adapter property to the WebDataModule's Dataset adapter, and click the preview tab in the editor to see the data in the dataset.

You'll notice that the grid doesn't look very attractive, primarily because the Notes field makes each row very large. So, let's override the default display behavior and add the columns we specifically want to the grid. Right mouse click on the AdapterGrid in the Object Treeview and select "Add Columns". Select those shown below.

The Object Treeview has been updated to show those specific columns.

Our preview in the editor now shows the grid with only the columns we've selected.

Editing Data

We'll now use the same page wizard (second button on the WebSnap toolbar) to create our edit page. Use the values shown in this screen shot.

As we do with a GUI Delphi application, we can also use the same data module here for building a WebSnap-based editing interface to our data. Don't forget to use Unit3 again (the WebDataModule) with this unit, which should be Unit5. Using the right mouse button in the object treeview, add the components shown here.

Hook up the AdapterFieldGroup and AdapterErrorList to the DataSetAdapter. Assign the DisplayGroup for the AdapterComamndGroup to the AdapterFieldGroup. If you have the preview tab in the editor active, you should see warning messages for required properties that will help you make sure to set up your component references correctly. The AdapterFieldGroup will display our data either in browse mode or edit mode. The AdapterErrorList will display any data validation errors that may be encountered when the user is editing data. The AdapterCommandGroup will display the buttons that allow us to perform all the actions on the data displayed, including navigation and modifying data.

Linking pages by name

Now that we've got our editing/browsing page done for specific records, it would be a good idea to support jumping directly to editing or browsing a specific record from the grid. Select Unit4 (the Grid) and add a AdapterCommandColumn to the Grid by using the right mouse button in the Object Treeview. You will notice the command column displays a whole bunch of buttons by default, all in a single line. First, set the display columns for the AdapterCommandGroup to 1. We should now see all buttons underneath each other. We only need four of the buttons, so let's right mouse click on the AdapterCommandColumn and add the specific commands we want to show in the grid.

Now the grid looks a little better.

In the ObjectTreeView, select CmdEditRow, CmdBrowseRow, and CmdNewRow, and assign their PageName property to "EditPage" or whatever you named your editing page. This will set up the "Page-by-name" link for those commands.

We're ready to test our application. Click the "Save All" button and save all the units and the project somewhere, and click the Run button, select Run|Run, or press F9. We have just compiled the WebSnap web server application and registered it for the Delphi 6 Web App Debuggger.

Web App Debugger

The Web App Debugger is included in both the Pro and Enterprise SKUs of Delphi 6. We can use it to debug WebSnap applications very effectively, because we can set breakpoints in our web server application while using the Web App Debugger. Let's start the Web App Debugger by selecting it from the Tools menu and clicking the Start button. It should look something like this:

To see what Web App Debugger servers are registered, click on the server info hot link. In the following list, you may notice that I've already registered all the WebSnap demos that are included with Delphi 6 Enterprise by following the instructions listed in your Delphi/Demos/WebSnap directory. Just about in the middle of the list is the WebSnap server we just created and registered.

We can get to the details for this server as well by clicking the detail link on the ServerInfo page.

Display the home page of our server by either clicking the "Go" button on the list view of ServerInfo, or by clicking the link for the application on the detail view. You should see something like the following:

Click on the Grid link to display the grid.

Select a row of the grid, and click on the EditRow button. You can see that we're now ready to edit the record we selected from the grid. Note that we can even change the graphic by simply clicking the browse button to select a new image file and clicking the Apply button.

If you want to make sure it's the same page, click the BrowseRow button so you can see the graphic again. It is possible to always display the graphic even in edit mode. Right now, all the adapter field's ViewMode properties are set to vmDefault, which means they get their settings from the AdapterFieldGroup's current ViewMode. If we want to always display the graphic regardless of editing mode, we could add another AdapterDisplayField to the field group, assign it to the graphic field, and set its ViewMode property to vmDisplay instead.

Switch back to editing mode by clicking the EditRow button and put in some bad data. Try to apply the change and you'll see something like the following displayed:

If you click Cancel, your changes to the record will be rejected.

We have just touched the surface of what you can do with WebSnap. It is an extremely flexible and extensible component-based Web Server development framework, and there's lots of additional things to cover. Unfortunately, they'll have to wait for another article. If you want to see more of what WebSnap can do in the meantime, look at your Delphi 6 Enterprise WebSnap demos directory for some further examples. You may find the Community TV interview I had with Jim Tierney, the WebSnap architect, of interest as well.

Enjoy, and code well.

John Kaster, Borland Developer Relations