WebSpeed
Developer’s Guide
Simple HTML Mapping
HTML mapping usually begins with a file containing HTML form markup, like the example
w-csget.htm
:
Note that this file is equivalent to
w-sstget.html
. However, it does not contain any embedded SpeedScript. (Also notice that the call to the Web objectw-cstget.w
is an attribute of the FORM element inw-csget.htm
.) Instead of embedding SpeedScript in this file, you can use the HTML Mapping Wizard in the AppBuilder to:
- Map each INPUT and TEXTAREA form element to a field in the Sports2000 database.
- Generate an offset file that specifies the position of the form elements in the HTML that is returned to the client.
- Edit process-web-request, which controls the flow of your Web object logic, by adding a SpeedScript FIND statement.
- Create
w-cstget.w
by compiling and saving in the AppBuilder.Mapping Form Elements to Database Fields
You begin by choosing File
New from the AppBuilder main menu, and then selecting HTML Mapping from the list of Web objects. The wizard guides you through the process of specifying an HTML file and a database. (When you specify the Sports2000 database for this example, you must add the Customer table in the wizard’s Query Builder.) Then, it allows you to map the form elements to database fields. The wizard also has an Automap feature that can map form elements to database fields that have similar names.
Generating the Offset File
When the HTML Mapping Wizard completes, it automatically creates an offset file that contains the type and location of each form element in the HTML file. The offset file generated from
w-csget.htm
is calledw-cstget.off
and looks similar to the following:
When it runs, an HTML mapped Web object uses the offset file to determine where to insert data values in the HTML that it generates. The numbers at the end of each field line in
w-cstget.off
indicate where the form field begins and ends in thew-csget.htm
source file.NOTE: If you make any changes in your HTML source files, you will probably need to generate a new offset file. If you add a single carriage return to your HTML source, for example, all of positional information in an existing offset file might be invalid. Although you could update the offset file yourself, manual editing is error prone. It is safer to use the HTML Mapping Wizard and to generate a new offset file.
You can automatically re-map by opening the Web object in the AppBuilder. An updated offset file will be generated. The WebSpeed Transaction Server also automatically generates the offset file at run time if the file does not exist or is out of date.When the HTML Mapping Wizard completes and saves the offset file, you will see the tree view representation of the object, as shown in Figure 4–4.
Figure 4–4: Tree View of HTML Mapping Source
![]()
By selecting a node in the tree view you can modify the code or properties of the section represented by the node.
Notice that there is a procedure called htmOffsets in the tree view. When htmOffsets runs in the final Web object, it creates the associations between the HTML form fields and the database fields. The Web object then refers to the offset file,
w-cstget.off
, to determine where to place the data in the HTML output.Editing process-web-request
The process-web-request procedure is where you add the SpeedScript FIND statement for
w-cstget.w
.NOTE: Instead of editing process-web-request to add the FIND statement, you could have used the HTML Mapping Wizard to define a query. When you use the wizard, your query is added as an override to the findRecords procedure.When you view process-web-request in the Section Editor (it is listed under Code Sections in Figure 4–4), you will see that it a runs a number of procedures that control the flow of information between the client and the Web object, and between the Web object and the data source. It also generates header information for the HTML output.
The procedures (assignFields, displayFields, etc.) contain default behavior that you can override. The super procedure, install-path
/tty/web2/html-map.r
. defines their behavior. You override the default behavior by creating local versions of the procedures. The WebSpeed Agent first looks in the Web Object for a procedure. If the procedure is not found in the Web Object, the Agent looks for it among registered super procedures. For more information about super procedures, see the Progress Programming Handbook.Also note that process-web-request runs a different sequence of processes depending on whether the HTML Form METHOD attribute is GET or POST. With GET, data from the client request is appended to the URL of the Web object. Usually, GET code processes the first request and returns a blank form. With POST, data is sent to the Web object as a separate stream. Usually, POST code processes subsequent requests.
The area in bold text shows where the FIND statement was added to process-web-request in order to create
w-cstget.w
:
Notice that the default Run findRecords procedure was commented out.
Compiling and Running
After adding the FIND statement to process-web-request, you can save, compile, and run the Web object from the AppBuilder. Selecting the Save button from the AppBuilder tool bar saves and compiles the file. Selecting the Run button from the AppBuilder runs the Web object (
w-cstget.r
) and displays the output in your default browser.When you run the Web object, the result looks similar to the Web page shown in Figure 4–5.
Figure 4–5: Web Page Generated by w-cstget
![]()
The Web object displays the first record from the Customer table. When you enter another Customer ID number, it will display the associated record.
Note that unlike
w-sstget.html
, this Web object generates the complete form on the initial request. Having the HTML in a separate file makes any attempt to selectively display parts of the form much more difficult.SpeedScript Form Buffer
So, how does it work? Here is another look at the SpeedScript added for the Web object in
w-cstget.w
:
Every Web object that maps to a Web page requires a query mechanism that specifies the data that you want to retrieve from a database. In this case, you use the FIND statement to retrieve the Customer record whose CustNum field (Customer.CustNum) equals the value entered for Enter Customer ID in the Web page. The HTML form element that accepts the entered value is specified by the notation, CustNum:SCREEN-VALUE IN FRAME {&FRAME-NAME}.
This notation identifies a particular SpeedScript field object in the Web object’s form buffer (FRAME {&FRAME-NAME}). The form buffer is a Web object buffer where all HTML form element values are stored, both for input from and output to a Web page. A field object is a SpeedScript construct that defines the visualization of a particular value stored in the form buffer. That is, a field object determines whether the value is represented by a string of characters, a selection list, a radio set, or some other visual control that is compatible with a corresponding HTML form element. The mapping between a field object and form element is done by a different procedure for each display type. The procedures are located in install-path
/src/web/support
. The procedures used for each display type are defined in a tag mapping file, install-path/tagmap.dat
, which comes installed with default mappings.NOTE: The SpeedScript form buffer is identical in function to the Progress 4GL screen buffer. The screen buffer is the buffer from which individual field objects are displayed directly on the screen of a client workstation in a traditional client/server environment. However, SpeedScript access to the client screen is entirely determined by the HTML that it outputs as a block to the Web server. It is essential that you remember this difference when you consult Progress 4GL documentation while doing WebSpeed development. For more information on how input and output differs between the Progress 4GL and SpeedScript, see "SpeedScript and Progress 4GL" in SpeedScript."Using the Automap feature of the AppBuilder, WebSpeed defines database field objects by default for HTML form elements that have the same names. Thus, in this case, the form element name is “CustNum,” the database field name. You can also have the AppBuilder map a form element to another database field or SpeedScript variable field object with any valid SpeedScript name up to 32 characters.
The visual characteristics of a field object are defined by properties or attributes associated with that object. In this case, the FIND statement references the SCREEN-VALUE attribute of the CustNum object and is separated from the field object name by a colon ( : ). The SCREEN-VALUE attribute stores the actual form element/data item value in character string form. For information on setting field object properties and attributes "Customizing Field Object Control Handlers" in Controlling WebSpeed Transactions."
SpeedScript also requires each field object to be defined within a special container object known as a frame. This SpeedScript frame is not to be confused with HTML frames, but is just another way that SpeedScript organizes field objects in the form buffer. Typically, there is one frame per Web object, identified by the preprocessor name reference, {&FRAME-NAME}, hence CustNum:SCREEN-VALUE IN FRAME {&FRAME-NAME}.
NOTE: When you compile an HTML-mapping Web object in the AppBuilder, it might tell you that it cannot find a particular field object in a frame. You can often resolve this by appending IN FRAME {&FRAME-NAME} to the problem field object reference.The FIND statement also references the CustNum object as input to the SpeedScript INTEGER function. This function simply converts the numeric string value of the field object to an integer for compatibility with the CustNum database field, which is also an integer.
An Alternative to Form Buffer Input
Here is another way to access HTML input using the FIND statement in
w-cstget.w
:
As described previously for embedded SpeedScript Web objects, WebSpeed provides the get-value API function to return values from a Web page. For the CustNum form element, this function accesses the value directly from HTML input. Using this technique avoids any need to reference the form buffer to retrieve input values from the Web.
NOTE: When the POST method is used, process-web-request, calls the inputFields procedure by default. The inputFields procedure loads the form buffer with input by running the get-value function for every field on the form.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |