Tutorial: Creating a WebSnap Application

You can improve it by editing the HomeU.html file, either by using the .... items in the Color tab of the Editor Properties dialog, which can be displayed by.
206KB taille 86 téléchargements 306 vues
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 © 2001–2002 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

1

Creating a WebSnap application

Creating a WebSnap application In this section, you’ll 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 you’ll 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.

2

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 Design”section of the Developer’s Guide’s 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

3

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.

4

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 don’t 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 Developer’s 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

5

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 doesn’t matter where they appear in the module. What matters is that your module contains the same components as shown in the figure.

6

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

7

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

8

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 Design”section of the Developer’s Guide’s 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

9

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 won’t 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

H

buttons, adding to application 12

HTML Script tab 9

C

S

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

sample DBDEMOS database 5 server-side scripting 6

D

T title, specifying application 3

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

Index

v

vi

Tutorial