Tutorial: Creating a

WebSnap Application

Borland

Delphi 7
for Windows
Borland Software Corporation
100 Enterprise Way, Scotts Valley, CA 95066-3249
www.borland.com

COPYRIGHT 20012002 Borland Software Corporation. All rights reserved. All Borland brand and product names
are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries.
All other marks are the property of their respective owners.
D7-WS-0802

Contents
Creating a WebSnap application
Creating a WebSnap application . . . . . . . .
Starting the WebSnap application wizard .
Saving the generated files and project . . .
Specifying the application title . . . . . . .
Creating a CountryTable page . . . . . . . . .
Adding a new Web page module. . . . . .
Saving the new Web page module . . . . .
Adding data components to the
CountryTable module . . . . . . . . . . . . .
Adding data-aware components . . . . . .
Specifying a key field . . . . . . . . . . . .
Adding an adapter component . . . . . . .
Creating a grid to display the data . . . . . . .
Adding a grid . . . . . . . . . . . . . . . . .
Adding editing commands to the grid . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

2
2
2
3
3
3
4

.
.
.
.
.
.
.

.
.
.
.
.
.
.

5
5
6
6
7
7
9

Adding an edit form . . . . . . . . . . . . .

Adding a new Web page module . . . .
Saving the new module. . . . . . . . . .
Making CountryTableU accessible
to the new module. . . . . . . . . . . .
Adding input fields . . . . . . . . . . . .
Adding buttons . . . . . . . . . . . . . .
Linking form actions to the grid page. .
Linking grid actions to the form page. .
Running the completed application . . . .
Adding error reporting. . . . . . . . . . . .
Adding error support to the grid . . . .
Adding error support to the form . . . .
Testing the error-reporting mechanism .

Index

iii

. . . 10
. . . 10
. . . 11
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

11
11
12
13
14
14
15
15
15
16

iv

1
Creating a WebSnap application

Chapter1

This tutorial explains how to create a WebSnap application called Country Tutorial.
The application displays a table of information about countries to users on the Web.
Users can add, delete, and edit the table information.
Follow the tutorial instructions from beginning to end. If you need a break, use the
File|Save All command at any time to save your project.
When you have completed the tutorial, your application will look similar to the one
shown in Figure 2.
Figure 2

Note

Completed Country Tutorial application

This tutorial requires the Enterprise edition of Delphi, which includes WebSnap
components. The tutorial assumes that you are familiar with Windows and have
read the introduction to Delphi programming and the IDE in the Quick Start.

Creating a WebSnap application

Creating a WebSnap application

Creating a WebSnap application

In this section, youll create and save the application files, and provide an application
title.

Starting the WebSnap application wizard

1 Use Windows Explorer to create a folder called WebSnapTutorial to hold the
project files that youll create while working through this tutorial.
2 Start the Delphi IDE and choose File|New|Other.
3 In the New Items dialog box, select the WebSnap tab and choose WebSnap
Application and click OK.
4 In the New WebSnap Application dialog box:

Select Web App Debugger executable.

In the Class Name field, type CountryTutorial.
Select Page Module as the component type.
In the Page Name field, type Home.

5 Click OK.

Saving the generated files and project

To save the Delphi unit and project files:

1 Select File|Save All.

2 In the Save dialog, navigate to your WebSnapTutorial folder.
3 In the File name field, change unit2.pas to HomeU.pas and click Save.
4 In the File name field, change unit1.pas to CountryU.pas and click Save.
5 In the File name field, change project1.dpr to CountryTutorial.dpr and click Save.

Tutorial

Creating a CountryTable page

Specifying the application title

The application title is the name displayed to the end user. To specify the application
title:

1 Choose View|Project Manager.

2 In the Project Manager expand CountryTutorial.exe and double-click the HomeU
entry.
3 In the top line of the Object Inspector, select ApplicationAdapter from the pulldown list.
4 In the Properties tab, enter Country Tutorial for the ApplicationTitle property.
5 Click the Preview tab in the editor window. If the Preview tab is not shown, use
the right arrow at the bottom to scroll through the tabs. The application title is
displayed at the top of the page with the page name, Home.
This page is very basic. You can improve it by editing the HomeU.html file, either by
using the HomeU.html editor tab or by using an external editor. For more
information on how to edit the page template, see the Advanced HTML
Designsection of the Developers Guides WebSnap chapter.

Creating a CountryTable page

A Web page module defines a published page, and it also acts as a container for data
components. Whenever a Web page needs to be returned to the end user, the Web
page module extracts the necessary information from the data components it
contains and uses that information to help create a page.
Here you will add a new page module to the WebSnap application. The page module
will add a second viewable page to the Country Tutorial application. The first page,
Home, was defined when you created the application. The second page, called
CountryTable, shows the table of country information.

Adding a new Web page module

To add a new page module:

1 Choose File|New|Other.
2 In the New Items dialog box, select the WebSnap tab, choose WebSnap Page
Module, and click OK.
3 In the dialog box, set the Producer Type to AdapterPageProducer.

Creating a WebSnap application

Creating a CountryTable page

4 In the Page Name field enter CountryTable. Notice that the Title also changes as
you type.
5 Leave the rest of the fields with their default values.
The dialog should appear as shown in Figure 3.

6 Click OK.
Figure 3

New WebSnap Page Module dialog box for the CountryTable page

The CountryTable module should now appear in the IDE. After saving the module,
you will add new components to the CountryTable module.

Saving the new Web page module

Save the unit to the directory of the project file. When the application runs, it searches
for the CountryTableU.html file in the same directory as the executable.

1 Choose File|Save.
2 In the File name field, enter CountryTableU.pas and click Save.

Tutorial

Adding data components to the CountryTable module

Adding data components to the CountryTable module

TTable and TDataSetAdapter are data-aware components; they provide access to data.
TTable provides the data for the HTML table. TDataSetAdapter allows server-side
script to access the TTable component. Here we will add these data-aware
components to your application.
The following topics assume some basic familiarity with database programming, but
you dont need it in order to complete this tutorial. WebSnap acts only as an interface
(through adapter components) to database components. To learn more about
database programming, refer to Part II of the Developers Guide.

Adding data-aware components

1 Choose View|Project Manager.
2 In the Project Manager expand CountryTutorial.exe and double-click the
CountryTableU entry.
3 Choose View|Object TreeView. The Object TreeView window becomes active.
4 Select the BDE tab on the Component palette.
5 Select a Table component and add it to the CountryTable Web page module.
6 Select a Session component and add it to the CountryTable Web page module. The
Session component is required because you are using a BDE component (TTable)
in a multi-threaded application.
7 Select the Session component, named Session1 by default, in the Web page module
or the Object TreeView. This displays the Session component values in the Object
Inspector.
8 In the Object Inspector, set the AutoSessionName property to True.
9 Select the Table component in the Web page module or the Object TreeView. This
displays the Table component values in the Object Inspector.
10 In the Object Inspector, change the following properties:

Set the DatabaseName property to DBDEMOS .

In the Name property, type Country.
Set the TableName property to country.db.
Set the Active property to True.

Creating a WebSnap application

Adding data components to the CountryTable module

Specifying a key field

The key field is used to identify records within a table. This becomes important when
you add an edit page to the application. To specify a key field:

1 In the Object TreeView, expand the Session and DBDemos node, then select the
country.db node. This node is the Country Table component.
2 Right-click the country.db node and select Fields Editor.
3 Right-click on the CountryTable.Country editor window and choose Add All
Fields.
4 Select the Name field from the list of added fields.
5 In the Object Inspector, expand the ProviderFlags property.
6 Set the pfInKey property to True.

Adding an adapter component

You are finished adding database components. Now, to expose the data in the TTable
through server-side scripting, you must include a dataset adapter (TDataSetAdapter)
component. To add a dataset adapter:

1 Choose the DataSetAdapter component from the WebSnap tab of the Component
palette. Add it to the CountryTable Web module.
2 Change the following properties in the Object Inspector:
Set the DataSet property to Country.
Set the Name property to Adapter.
When you are finished, the CountryTable Web page module should look similar
to what is shown in Figure 4.
Figure 4

CountryTable Web page module

Since the elements in the module are non-visual, it doesnt matter where they appear
in the module. What matters is that your module contains the same components as
shown in the figure.

Tutorial

Creating a grid to display the data

Creating a grid to display the data

Adding a grid
Now, add a grid to display the data from the country table database:

1 Choose View|Project Manager.

2 In the Project Manager, expand CountryTutorial.exe and double-click the
CountryTableU entry.
3 Choose View|Object TreeView or click on the Object TreeView.
4 Expand the AdapterPageProducer component. This component generates serverside script to build an HTML table quickly.
5 Right-click the WebPageItems entry and choose New Component.
6 In the Add Web Component dialog box, select AdapterForm and click OK. An
AdapterForm1 component appears in the Object TreeView.
7 Right-click AdapterForm1 and select New Component.
8 In the Add Web Component window, select AdapterGrid then click OK. An
AdapterGrid1 component appears in the Object TreeView.
9 In the Object Inspector, set the Adapter property to Adapter.
To preview the page, select the CountryTableU tab at the top of the code editor, then
select the Preview tab at the bottom. If the Preview tab is not shown, use the right
arrow at the bottom to scroll through the tabs.
The preview should appear similar to Figure 5.

Creating a WebSnap application

Creating a grid to display the data

Figure 5

CountryTable Preview tab

The Preview tab shows you what the final, static HTML page looks like in a Web
browser. That page is generated from a dynamic HTML page that includes script. To
see a text representation showing the script commands, select the HTML Script tab at
the bottom of the editor window (see Figure 6).
Figure 6

Tutorial

CountryTable HTML Script tab

Creating a grid to display the data

The HTML Script tab shows a mixture of HTML and script. HTML and script are
differentiated in the editor by font color and attributes. By default, HTML tags
appear in boldfaced black text, HTML attribute names appear in black, and HTML
attribute values appear in blue. Script, which appears between the script brackets <%
%>, is colored green. You can change the default font colors and attributes for these
items in the Color tab of the Editor Properties dialog, which can be displayed by
right-clicking on the editor and selecting Properties.
There are two other HTML-related editor tabs. The HTML Result tab shows the raw
HTML contents of the preview. Note that the HTML Result, HTML Script, and
Preview views are all read-only. You can use the HTML-related editor tab,
CountryTable.html, for editing.
If you want to improve the look of this page, you can add HTML using either the
CountryTable.html tab or an external editor at any time. For more information on
how to edit the page template, see the Advanced HTML Designsection of the
Developers Guides WebSnap chapter.

Adding editing commands to the grid

Users may need to update the content of the table by deleting, inserting or editing a
row. To allow users to make such updates, add command components.
To add command components:

1 In the Object TreeView for the CountryTable, expand the AdapterPageProducer

component and all its branches.
2 Right-click the AdapterGrid1 component and choose Add All Columns. Five
columns are added to the adapter group.
3 Right-click the AdapterGrid1 component again and choose New Component.
4 Select AdapterCommandColumn and then click OK. An
AdapterCommandColumn1 entry is added to the AdapterGrid1 component.
5 Right-click AdapterCommandColumn1 and choose Add Commands.
6 Press the Ctrl key and multi-select the DeleteRow, EditRow, and NewRow
commands and click OK.
7 To preview the page, click the Preview tab at the bottom of the code editor. There
are now three new buttons (DeleteRow, EditRow, and NewRow) at the end of
each row in the table, as shown in Figure 7. When the application is running,
pressing one of these buttons performs the associated action.

Creating a WebSnap application

Adding an edit form

Figure 7

CountryTable Preview after editing commands have been added

Choose File|Save All to save the application before continuing.

Adding an edit form

You can now create a Web page module to handle the Edit form for the country table.
Users will be able to change data in the CountryTutorial application through the Edit
form. Specifically, when the user presses the EditRow or NewRow buttons, an Edit
form appears. When the user is finished with the Edit form, the modified information
automatically appears in the table.

Adding a new Web page module

To add a new Web page module:

1 Choose File|New|Other.
2 In the New Items dialog box, select the WebSnap tab and choose WebSnap Page
Module and click OK.
3 In the dialog box, set the Producer Type to AdapterPageProducer.
4 Set the Page Name field to CountryForm.

10

Tutorial

Adding an edit form

5 Uncheck the Published box, so this page does not appear in a list of available
pages on this site. The Edit form is accessed through the Edit button, and its
contents depend on which row of the country table is to be modified.
6 Leave the rest of the fields and selections set to their default values. Click OK.

Saving the new module

Save the module in the same directory as the project file. When the application runs,
it looks for the CountryFormU.html file in the same directory as the executable.

1 Choose File|Save.
2 In the File name field enter CountryFormU.pas and click Save.

Making CountryTableU accessible to the new module

Add CountryTableU unit to the uses clause to allow the module access to the
Adapter component.

1 Choose File|Use Unit.

2 Choose CountryTableU from the list then click OK.
3 Choose File|Save.

Adding input fields

Add components to the AdapterPageProducer component to generate data entry
fields in the HTML form.
To add input fields:

1 Choose View|Project Manager.

2 In the Project Manager window, expand CountryTutorial.exe and double-click the
CountryFormU entry.
3 In the Object TreeView expand the AdapterPageProducer component, right-click
WebPageItems, and select New Component.
4 Select AdapterForm and click OK. An AdapterForm1 entry appears in the Object
TreeView.
5 Right-click AdapterForm1 and select New Component.
6 Select AdapterFieldGroup then click OK. An AdapterFieldGroup1 entry appears
in the Object TreeView.

Creating a WebSnap application

11

Adding an edit form

7 In the Object Inspector, set the Adapter property to CountryTable.Adapter. Set the
AdapterMode property to Edit.
8 To preview the Page, click the Preview tab at the bottom of the code editor. Your
preview should resemble the one shown in Figure 8.
Figure 8

Previewing the CountryForm

Adding buttons
Add components to the AdapterPageProducer component to generate the submit
buttons in the HTML form. To add components:

1 In the Object TreeView, expand the AdapterPageProducer component and all its
branches.
2 Right-click AdapterForm1 and choose New Component.
3 Select AdapterCommandGroup then click OK. An AdapterCommandGroup1
entry appears in the Object TreeView.
4 In the Object Inspector, set the DisplayComponent property to
AdapterFieldGroup1.
5 Right-click AdapterCommandGroup1 entry and choose Add Commands.
6 Press the Ctrl key and multi-select the Cancel, Apply, and Refresh Row
commands. Click OK.

12

Tutorial

Adding an edit form

7 To preview the page, click the Preview tab at the bottom of the code editor
window. If the preview does not show the country form, click the Code tab and
then click the Preview tab again. Your preview should resemble the one shown in
Figure 9.
Figure 9

CountryForm with submit buttons

Linking form actions to the grid page

When the user clicks a button, an adapter action is executed which in turn carries out
the described action. To specify which page to display after an adapter action is
executed:

1 In the Object TreeView, expand AdapterCommandGroup1 to show the

CmdCancel, CmdApply, and CmdRefreshRow entries.
2 Select CmdCancel. In the Object Inspector, type CountryTable in the PageName
property.
3 Select CmdApply. In the Object Inspector, type CountryTable in the PageName
property.

Creating a WebSnap application

13

Running the completed application

Linking grid actions to the form page

An adapter action is executed by pushing a button in the grid. To specify which page
is displayed in response to the adapter action:

1 Choose View|Project Manager.

2 In the Project Manager, expand CountryTutorial.exe and double-click the
CountryTableU entry.
3 In the Object TreeView, expand the AdapterPageProducer component and all its
branches to show the CmdNewRow, CmdEditRow, and CmdDeleteRow entries.
These entries appear under the AdapterCommandColumn1 entry.
4 Select CmdNewRow. In the Object Inspector, type CountryForm in the PageName
property.
5 Select CmdEditRow. In the Object Inspector, type CountryForm in the PageName
property.

Running the completed application

To verify that the application is working and that all buttons perform some action,
run the application. When you run the application, you start a server and view the
application in a Web browser.
To run the application:

1 Choose Run|Run. A form is displayed. Web App Debugger executable Web

applications are COM servers, and the form you see is the console window for the
COM server. The first time you run the project, it registers the COM object that the
Web App Debugger can access directly.
2 Choose Tools|Web App Debugger.
3 In the Web App Debugger window, click Start.
4 Click the default URL link to display the ServerInfo page. The ServerInfo page
displays the names of all registered Web Application Debugger executables.
5 Choose CountryTutorial in the drop-down list and click on the Go button.
Your browser now shows the Country Tutorial application. Click on the
CountryTable link to see the CountryTable page.
To continue the tutorial, close the browser window, click Stop in the Web App
Debugger window, and choose Run|Program Reset.

14

Tutorial

Adding error reporting

Adding error reporting

Right now, your application wont show any errors to the user. For example, if
someone types letters into the Area field of a country record, that user will receive no
notification that an error occurred. You will now add an AdapterErrorList component
to display errors that occur while executing adapter actions which edit the country
table.

Adding error support to the grid

To add error support to the grid:

1 In the Object TreeView for CountryTable, expand the AdapterPageProducer

component and all its branches to show AdapterForm1.
2 Right-click AdapterForm1 and choose New Component.
3 Select AdapterErrorList from the list and click OK. An AdapterErrorList1 entry
appears in the Object TreeView.
4 Move AdapterErrorList1 above AdapterGrid1 (either by dragging it or by using
the upward-pointing arrow in the Object TreeView toolbar).
5 In the Object Inspector, set the Adapter property to Adapter.

Adding error support to the form

To add error support to the form:

1 Choose View|Project Manager.

2 In the Project Manager, expand CountryTutorial.exe and double-click the
CountryFormU entry.
3 In the Object TreeView, expand the AdapterPageProducer component and all its
branches to show AdapterForm1.
4 Right-click AdapterForm1 and choose New Component.
5 Select AdapterErrorList from the list and click OK. An AdapterErrorList1 entry
appears in the Object TreeView.
6 Move AdapterErrorList1 above AdapterFieldGroup1 (either by dragging it or by
using the upward-pointing arrow in the Object TreeView toolbar).
7 In the Object Inspector, set the Adapter property to CountryTable.Adapter.

Creating a WebSnap application

15

Adding error reporting

Testing the error-reporting mechanism

To observe the error-reporting mechanism, you must first make a small change to the
IDE. Select Tools|Debbugger Options. In the Language Exceptions tab, make sure
the Stop on Delphi Exceptions checkbox is unchecked, which will allow the
application to proceed when exceptions are detected. Now, to test for grid errors:

1 Run the application and browse to the CountryTable page using the Web
Application Debugger. For information on how to do this, see Running the
completed application on page 14.
2 Open another browser window and browse to the CountryTable page.
3 Click the DeleteRow button on the first row in the grid.
4 Without refreshing the second browser, click the DeleteRow button on the first
row in the grid.
An error message, Row not found in Country, is displayed above the grid.
To test for form errors:

1 Run the application, and browse to the CountryTable page using the Web
Application debugger.
2 Click on the EditRow Button. The CountryForm page is displayed.
3 Change the area field to 'abc', and click the Apply Button.
An error message (Invalid value for field Area) will be displayed above the first
field.
You have now completed the WebSnap tutorial. You might want to recheck the Stop
on Delphi Exceptions checkbox before continuing. Also, save the application by
choosing File|Save All so your completed application is available for future
reference.

16

Tutorial

Index
B

buttons, adding to application 12

HTML Script tab 9

colors for HTML 9

commands, adding to application 9
creating a Web page module 10

sample DBDEMOS database 5

server-side scripting 6

T
title, specifying application 3

data-aware components 5
dataset adapter component 6
DBDEMOS sample database 5

Index

vi

Tutorial