|
|
|
|
|
|
|
|
|
|
version 2003 (Modified)
This section describes the means made available by the 4D Web server for exchanging information via the Web, i.e. for dynamically sending and receiving values. The following points will be dealt with:
• Sending dynamic values stored in 4D variables
• Receiving dynamic values via Web forms
• Using the COMPILER_WEB project method
• Managing server-side image mapping
• Embedding JavaScript
Note: the sending and receiving of dynamic values can be carried out automatically in contextual mode via converted 4D forms. For more information on this point, refer to the section Using the contextual mode.
Sending dynamic values
References to 4D variables can be inserted in your HTML pages. You can bind these references with any type of HTML object. When the Web pages are sent to the browser, 4D will replace these references with the current values of the variables. The pages received are therefore a combination of static elements and values coming from 4D. This type of page is called semi-dynamic.
Notes:
• You work with process variables.
• As HTML is a word processing oriented language, you will usually work with Text variables. However, you can also use BLOBs variables (which avoid the 32 000 characters limitation of text type variables). You just need to generate the BLOB in Text without length mode.
First, an HTML object can have its value initialized using the value of a 4D variable.
Second, after a Web form is submitted back, the value of an HTML object can be returned into a 4D variable. To do so, within the HTML source of the form, you create an HTML object whose name is the same as the name of the 4D process variable you want to bind. That point is studied further in the paragraph "Receiving dynamic values" in this document.
Note: In non-contextual mode, it is not possible to make a reference to 4D picture variables.
Since an HTML object value can be initialized with the value of a 4D variable, you can programmatically provide default values to HTML objects by including <!--#4DVAR VarName--> in the value field of the HTML object, where VarName is the name of the 4D process variable as defined in the current Web process. This is the name that you surround with the standard HTML notation for comments <!--#...-->.
Note: Some HTML editors may not accept <!--#4DVAR VarName--> in the value field of HTML objects. In this case, you will have to type it in the HTML code.
The <!--#4DVAR --> tag also allows the insertion of 4D expressions in the pages sent (fields, array elements, etc.). The operation of this tag with this type of data is identical to that with variables. For more information, refer to the section 4D HTML Tags.
In fact, the syntax <!--#4DVAR VarName--> allows you to insert 4D data anywhere in the HTML page. For example, if you write:
<P>Welcome to <!--#4DVAR vtSiteName-->!</P>
The value of the 4D variable vtSiteName will be inserted in the HTML page.
Here is an example:
` The following piece of 4D code assigns "4D4D" to the process variable vs4D
vs4D:="4D4D"
` Then it send the HTML page "AnyPage.HTM"
SEND HTML FILE("AnyPage.HTM")
The source of the HTML page AnyPage.HTM is listed here:
In the HTML source code shown, note the hidden input object named vs4D. The value of this object is set to the text value "<!--#4DVAR vs4D-->". Since the project method sending the HTML file has previously defined the 4D process variable vs4D, 4D replaces the value of the HTML object and sets it to "4D4D", the value of the 4D variable.
The embedded JavaScript function Is4DWebServer tests the value of the vs4D HTML object. Here is the trick: if the HTML page is served by 4D, the object's value is changed to "4D4D". However, if the HTML page is served by another application (i.e., 4D WebSTAR on Macintosh), the object stays with its value as defined in the page, "[vs4D]". Bingo! By using JavaScript to test the value of that object, from within the page on the Web Browser side, you can detect whether or not the page is being served by 4D.
This first example shows how you can build "intelligent" HTML pages that provide additional features when being served by 4D, while staying compatible with other Web servers.
Important: You bind process variables only. In addition, the current version of 4D does not allow you to bind a 4D array to an HTML SELECT object. On the other hand, each element of a SELECT object can refer to separate 4D variables (i.e., the first element to V1, the second to V2, and so on).
The binding in the direction 4D toward Web Browser works with any encapsulation method (SEND HTML FILE, SEND HTML BLOB, as well as, in contextual mode, static text or text or BLOB variable in a 4D form).
Parsing of pages sent by the server
• In contextual mode, before sending an HTML page (HTML document or translated 4D form), 4D always parses the HTML source code in order to look for objects referring to 4D variables.
• In non-contextual mode, for the purpose of optimization, the parsing of the HTML source code is not carried out by the 4D Web server when HTML pages are called using simple URLs that are suffixed with ".HTML" or ".HTM". Of course, 4D offers mechanisms that allow you to "force" the parsing of pages when necessary (refer to the section 4D HTML Tags).
Inserting HTML Code into 4D Variables
You can insert HTML code into 4D variables. When the HTML static page is displayed on the Web browser, the value of the variable is replaced by the HTML code and will be interpeted by the browser.
To insert HTML code into 4D variables, you have two possibilites:
• Make the 4D variable start with ASCII code 1 as first character (i.e., vtHTML:=Char(1)+"...HTML code...") and add it to the HTML page using the <!--#4DVAR vtHTML--> tag.
• Insert directly the 4D variable (i.e., vtHTML:="...HTML code...") in the HTML page using the <!--#4DHTMLVAR vtHTML--> tag.
You can use a Text or a BLOB variable (the BLOB should have been generated in Text without length mode).
For more information, refer to section "HTML Tags".
Receiving dynamic values
When you send an HTML page using SEND HTML FILE or SEND HTML BLOB, you can also bind 4D variables with HTML objects in the "Web Browser toward 4D" direction. The binding works both ways: once the HTML form is submitted, 4D can copy back the values of the HTML objects into the 4D process variables. With a view to database compilation, these variables must be declared in the COMPILER_WEB method (see paragraph below).
It is also possible to retrieve values from the Web forms sent to 4D without prior knowledge of the fields that they contain, using the GET WEB FORM VARIABLES command. For more information, refer to the description of this command.
Warning: Getting the values back into the 4D process variables is only possible with HTML pages sent using SEND HTML FILE or SEND HTML BLOB. With HTML encapsulated in a 4D form in contextual mode, getting back values is restricted to the actual 4D objects located in the form.
Consider the following HTML page source code:
When 4D sends the page to a Web Browser, it looks like this:
The main features of this page are:
• It includes three Submit buttons: vsbLogOn, vsbRegister and vsbInformation.
• When you click Log On, the submission of the form is first processed by the JavaScript function LogOn. If no name is entered, the form is not even submitted to 4D, and a JavaScript alert is displayed.
• The form has a POST 4D Method as well as a Submit script (GetBrowserInformation) that copies the Navigator properties to the four hidden objects whose names starts with vtNav_App.
• The initial value of the object vtUserName is <!--#4DVAR vtUserName-->.
Let's examine the 4D method WWW Welcome that sends this HTML page using the SEND HTML FILE command. This method is called by the On Web Connection Database Method.
` WWW Welcome Project Method
` WWW Welcome -> Boolean
` WWW Welcome -> Yes = Can start a session
C_BOOLEAN($0)
$0:=False
` Hidden INPUT HTML objects returning Browser information
C_TEXT(vtNav_appName;vtNav_appVersion;vtNav_appCodeName;vtNav_userAgent)
vtNav_appName:=""
vtNav_appVersion:=""
vtNav_appCodeName:=""
vtNav_userAgent:=""
` Text INPUT HTML object where the user name is entered
C_TEXT(vtUserName)
vtUserName:=""
` HTML submit button values
C_STRING(31;vsbLogOn;vsbRegister;vsbInformation)
Repeat
` Do not forget to reset the values of the submit buttons!
vsbLogOn:=""
vsbRegister:=""
vsbInformation:=""
` Send the Web page
SEND HTML FILE("Welcome.HTM")
` Test the values of the submit buttons in order to detect which one was clicked
Case of
` The Log On button was clicked
: (vsbLogOn # "")
QUERY([WWW Users];[WWW Users]User Name=vtUserName)
$0:=(Records in selection([WWW Users])>0)
If ($0)
WWW POST EVENT ("Log On";WWW Log information )
` The method WWW POST EVENT saves information to a table of the database
Else
CONFIRM("This User Name is unknown, would you like to register?")
$0:=(OK=1)
If ($0)
$0:=WWW Register
` The method WWW Register allow a new Web User to register
End if
End if
` The Register button was clicked
: (vsbRegister # "")
$0:=WWW Register
` The Information button was clicked
: (vsbInformation # "")
DIALOG([User Interface];"WWW Information")
End case
Until (Not(<>vbWebServicesOn) | $0)
The features of this method are:
• The 4D variables vtNav_appName, vtNav_appVersion, vtNav_appCodeName, and vtNav_userAgent (bound to the HTML objects having the same names) use the GetBrowserInformation JavaScript script to get back the values assigned to the HTML objects. Simple and direct, the method initializes the variables as strings, then gets back the values after the Web page has been submitted.
• The 4D variables vsbLogOn, vsbRegister and vsbInformation are bound to the three Submit buttons. Note that these variables are reset each time the page is sent to the browser. When the submit is performed by one of these buttons, the browser returns the value of the clicked button to 4D. The 4D variables are reset each time, so the variable that is no longer equal to the empty string tells you which button was clicked. The two other variables are empty strings, not because the browser returned empty strings, but because the browser "said" nothing about them; consequently, 4D left the variables unchanged. That is why it is necessary to reset those variables to the empty string each time the page is sent to the browser.
This the way to distinguish which Submit button was clicked when several Submit buttons exist on the Web page. Note that 4D buttons in a 4D form are numeric variables. However, with HTML, all objects are text objects.
If you bind a 4D variable with a SELECT object, you also bind a text variable. In 4D, to test which element of a drop-down list was chosen, you test the numeric value of the 4D array. With HTML, this is the value of the selected item that is returned in the 4D variable bound to the HTML object.
No matter which object you bind with a 4D variable, the returned value is of type Text, so you bind String or Text 4D process variables.
An interesting point of this example is that after you have obtained information about the Browser, you can store these values in a 4D table, again combining Web and database capabilities. This is what the (unlisted) WWW POST EVENT project method does. It does not "post an event"; it saves the web session information into the tables shown here:
After you have saved the information in a table, you can use other project methods to send the information back to the Web user. To do so, simply use QUERY to find the right information and then use DISPLAY SELECTION to show the [WWW Log] records. The following figure shows the log information available to the registered user of the Web site:
Using the binding features shown in this example, combined with all the information you can give to or gather from users via HTML dialogs or 4D forms, you can add some very interesting administrative capabilities to your database Web site.
COMPILER_WEB Project Method
When the 4D Web server receives a posted form, it automatically calls the project method called COMPILER_WEB (if it exists). This method must contain all the typing and/or variable initialization directives, which are the variables whose names are the same as the field names in the form. It will be used by the compiler when compiling the database.
The COMPILER_WEB method is common to all the Web forms. By default, the COMPILER_WEB method does not exist. You must explicitly create it.
Note: You can also use the GET WEB FORM VARIABLES command, which gets the value for all the variables included in a submitted HTML page.
Web Services: The COMPILER_WEB project method is called, if it exists, for each SOAP request accepted. You must use this method to declare all the 4D variables associated with incoming SOAP arguments, for all methods published as Web Services. In fact, the use of process variables in Web Services methods requires that they be declared before the method is called. For more information on this point, refer to the description of the SOAP DECLARATION command.
Binding HTML Objects with 4D Variables - Image Mapping
As seen in the section Using the Contextual Mode, when a 4D form is used as a Web page, 4D provides Server-side Image Mapping by means of invisible-like buttons that overlap a static picture.
If you send an HTML document using SEND HTML FILE or SEND HTML BLOB, you can bind 4D variables with Image Map HTML objects (INPUT TYPE="IMAGE") to retrieve information. For example, you can create an Image Map HTML object named bImageMap (you can actually use any name). Each time you click on the image on the browser side, a submit with the click position is sent back to the 4D Web Server. To retrieve the coordinates of the click (expressed relative to the top left corner of the image), you just need to read the value the 4D process variables bImageMap_X and bImageMap_Y (of type Longint) which contain the horizontal and vertical coordinates of the click. These variables should be declared in the COMPILER_WEB project method (see previous paragraph).
• In the HTML page, you write something like:
<P><INPUT TYPE="image" SRC="MyImage.GIF" NAME="bImageMap" BORDER=0></P>
• The 4D method that sends the HTML page contains:
SEND HTML FILE("ThisPage.HTM")
• In the COMPILER_WEB project method, you write:
C_LONGINT(bImageMap_X;bImageMap_Y) bImageMap_X:=-1 `Initializing the variable bImageMap_Y:=-1 `Initializing the variable
• Then, in the POST action 4D method or in the current method, after the POST action method issued a SEND HMTL FILE("") call, you retrieve the coordinates of the click in the bImageMap_X and bImageMap_Y variables :
If (($bImageMap_X#-1)&($bImageMap_Y#-1)) ` Do something accordingly to the coordinates End if
JavaScript Encapsulation
4D supports JavaScript source code embedded into HTML documents, and also JavaScript .js files embedded in HTML documents (for example <SCRIPT SRC="...").
Using SEND HTML FILE or SEND HTML BLOB in standard mode, you send a page that you have prepared in an HTML source editor or built programmatically using 4D and saved as a document on disk. In both cases, you have full control of the page. You can insert JavaScript scripts in the HEAD section of the document as well as use scripts with the FORM markup. In the previous example, the script refers to the form "frm" because you were able to name the form. You can also trigger, accept, or reject the submission of the form at the FORM markup level.
In contextual mode, if you encapsulate HTML in a 4D form, you do not have control over the HEAD section or the FORM declaration. The scope of the scripts is therefore different. For example, you cannot access the HTML form by its name. However, compare the Is4DWebServer JavaScript function of the previous example with this one:
Both functions do the same thing, but the second example uses the forms property of the HTML document object to access the object through the element forms[0]. As a result, it operates even if you do not know the name that 4D may or may have not given to the translated HTML page (form).
Note: 4D supports Java applets transport.
See Also
4D HTML Tags, SEND HTML BLOB, SEND HTML FILE, URLs and Form Actions.
|
|
|
|
|
|
|
|
|
|