User interface and program flow Professional

When the submit button is clicked in the start-up page, your Web application will create the response and return an HTML page to the Web browser. This is what you program in PRG code using the HTML3 object and a Context object, if necessary. Both objects are passed to a form-function and must be used to prepare and return the response. The HTML3 object is the one you will use most frequently because its task is to assemble the HTML page. For this, it has a variety of methods for creating standard HTML code. However, the individual design of an HTML page is up to you and you should be familiar with the HTML format and the most common HTML tags. How to design HTML pages is beyond the scope of this discussion (there are many good books about this), and we will concentrate on PRG code and focus on logical issues.

The important part of an assembled HTML page is the user interface, or how a user can interact with your Web application. This is analogous to any Xbase++ application running on a single computer. You would use the @..SAY..GET command or a single line edit control (XbpSLE) to obtain user input, assign input data to a variable when the user hits the Enter key and finally process the data in your program. This all happens in the memory of one computer, and it is the point where the similarity between a "normal" Xbase++ program and a HTML based Web application ends.

In a Web application, the user interface is provided by the Web browser and you are limited to the input controls supported in the HTML tag language. However, the most important difference is the fact that you cannot declare a LOCAL or PRIVATE variable in your Web application for holding a value that is edited in a Web browser. Instead, the name of a variable and its value must be bound to the HTML page sent to the remote computer. Let us see now what this means in terms of PRG code:

01:   FUNCTION _Register( oPackage ) 
02:      oPackage:registerForm( "My_Function" ) 
03:      oPackage:registerForm( "UserName"    ) 
04:   RETURN .T. 
05: 
06: 
07:   FUNCTION My_Function( oHtml, oContext ) 
08:      oHtml:header() 
09: 
10:      oHtml:formStart() 
11: 
12:      oHtml:setVar( "WAA_PACKAGE"   , "My_Dll"    ) 
13:      oHtml:setVar( "WAA_FORM"      , "UserName"  ) 
14:      oHtml:SLE( "Enter your name:" , "USER_NAME" ) 
15:      oHtml:submitButton( "Send it" ) 
16: 
17:      oHtml:formEnd() 
18: 
19:      oHtml:footer() 
20:   RETURN .T. 
21: 
22: 
23:   FUNCTION UserName( oHtml, oContext ) 
24:      LOCAL cUserName := oHtml:getVar( "USER_NAME" ) 
25: 
26:      oHtml:header() 
27:      oHtml:put( "<H1>Hello, " + cUserName + "</H1>" ) 
28:      oHtml:footer() 
20:   RETURN .T. 

Note that the functions _Version() and _Copyright() are omitted in this code example for simplicity. Only the _Register() function is included which registers two form-functions that can be invoked by the WAA server. The first function My_Function() is called from the start-up page as described in the previous section. It prepares the initial response and assembles an HTML page displaying an input field (line #14) and a submit button (line #15). Both controls form the user interface for this Web application and are displayed by the Web browser whenMy_function() returns. To be HTML compliant, the definition of the two controls must be embedded in the method calls :header() / :formStart()and :formEnd() / :footer(). If these methods are not called, the Web browser will not display a correct HTML page, and there is no way to find out, if the HTML page assembled byMy_Function() is received correctly or received at all (this is something you have to test on your development computer).

For the Web application's program logic, there are three variables bound to the HTML page: WAA_PACKAGE, WAA_FORM and USER_NAME (lines #12-#14). The values "My_Dll" and "UserName" are assigned to WAA_PACKAGE and WAA_FORM, respectively, while the variable USER_NAME has no value. It will receive what a user types into the SLE control. However, the values of these variables become only important when the user clicks the submit button defined in line #15. Then, the HTML page is returned back to the WAA server which uses the values of WAA_PACKAGE and WAA_FORM to call the corresponding function in your package DLL. In this example, the funtion UserName()would be called, where the value of the variable USER_NAME is retrieved from the HTML object (line #24) and included in a new HTML page as a response (line #27). Since no further input controls are included in this HTML page, it would be the end, or last page, of this Web application.

The following statements summarize this discussion: