URLs and Form Actions

Home

4D v16.3

The 4D Web Server offers different URLs and HTML form actions that allow you to implement various actions in your database.

These URLs are the following:

4DACTION/, to link any HTML object to a project method of your database,
4DCGI/, to call the On Web Connection Database Method from any HTML object.
4DSYNC/, to synchronize the data of the tables.

In addition, the 4D Web Server accepts several additional URLs:

/4DSTATS, /4DHTMLSTATS, /4DCACHECLEAR and /4DWEBTEST, to allow you to obtain information about the functioning of your 4D Web site. These URLs are described in the section Information about the Web Site.
/4DWSDL, to allow you to access the declaration file of Web Services published on the server. For more information, refer to the Web Services (Server) Commands section and to the Design Reference manual.

URL 4DACTION/

Syntax: 4DACTION/MyMethod{/Param}

Usage: URL or Form action.

This URL allows you to link an HTML object (text, button...) to a 4D project method. The link will be /4DACTION/MyMethod/Param where MyMethod is the name of the 4D project method to be executed when the user clicks on the link and Param an optional Text parameter to pass to the method in $1 (see paragraph “The Text Parameters Passed to 4D Methods Called via URLs” below).

When 4D receives a /4DACTION/MyMethod/Param request, the On Web Authentication Database Method (if it exists) is called. If it returns True, the MyMethod method is executed.
4DACTION/ can be associated with a URL in a static Web page. The syntax of the URL must be in the following form:

<A HREF="/4DACTION/MyMethod/Param"> Do Something</A>

The MyMethod project method should generally return a "reply" (sending of an HTML page using WEB SEND FILE or WEB SEND BLOB, etc.). Be sure to make the processing as short as possible in order not to block the browser.

Note: A method called by 4DACTION must not call interface elements (DIALOG, ALERT, etc.).

Warning: For a 4D method to be able to be executed using the 4DACTION/ URL, it must have the “Available through 4D HTML tags and URLS (4DACTION...)” attribute (unchecked by default), defined in the Method properties. For more information on this point, refer to the section Connection Security.

Example 1

This example describes the association of the 4DACTION/ URL with an HTML picture object in order to dynamically display a picture in the page. You insert the following instructions in a static HTML page:

<IMG SRC="/4DACTION/PICTFROMLIB/1000">

The PICTFROMLIB method is as follows:

 C_TEXT($1) // This parameter must always be declared

 C_PICTURE($PictVar)

 C_BLOB($BlobVar)

 C_LONGINT($Number)

  // We retrieve the picture’s number in the string $1

 $Number:=Num(Substring($1;2;99))

 GET PICTURE FROM LIBRARY($Number;$PictVar)

 PICTURE TO GIF($PictVar;$BlobVar)

 WEB SEND BLOB($BlobVar;"Pict/gif")

4DACTION to post forms

The 4D Web server also allows you to use “posted” forms, which are static HTML pages that send data to the Web server, and to easily retrieve all the values. The POST type must be associated to them and the form’s action must imperatively start with /4DACTION/MethodName.

Note: A form can be submitted through two methods (both can be used with 4D):

POST, usually used to add data into the Web server - to a database,
GET, usually used to request the Web server - data coming from a database.

In this case, when the Web server receives a posted form, it calls the On Web Authentication Database Method (if it exists). If it returns True, the MethodName method is executed. In this method, you must call the WEB GET VARIABLES command in order to retrieve the names and values of all the fields included in an HTML page submitted to the server.

Compatibility note: In converted databases, if the "Automatic variable assignment" option on the Compatibility page is checked, the special COMPILER_WEB project method (if it exists) is called first; 4D retrieves the values of HTML fields found in the form and automatically fills the 4D variables in the called method with their contents if they have the same name. This functioning is obsolete. For more information, refer to the Binding 4D objects with HTML objects section.

The HTML syntax to apply in the form is of the following type:

to define the action in a form:

<FORM ACTION="/4DACTION/MethodName" METHOD=POST>

to define a field in a form:

<INPUT TYPE=Field type NAME=Field name VALUE="Default value">

For each field in the form, 4D sets the value of the field to the variable with the same name.

Example 2

In a 4D Web database, we would like for the browsers to be able to search among the records by using a static HTML page. This page is called “search.htm”. The database contains other static pages that allow you to, for example, display the search result (“results.htm”). The POST type has been associated to the page, as well as the /4DACTION/SEARCH action.

Here is the HTML code that corresponds to this page:

<FORM ACTION="/4DACTION/PROCESSFORM" METHOD=POST>
<INPUT TYPE=TEXT NAME=VNAME VALUE=""><BR>
<INPUT TYPE=CHECKBOX NAME=EXACT VALUE="Word">Whole word<BR>
<INPUT TYPE=SUBMIT NAME=OK VALUE="Search">
</FORM>

During data entry, type “ABCD” in the data entry area, check the "Whole word" option and validate it by clicking the Search button.

In the request sent to the Web server:

VNAME="ABCD"
vEXACT="Word"
OK="Search"

4D calls the On Web Authentication Database Method (if it exists), then the PROCESSFORM project method is called, which is as follows:

 C_TEXT($1) //mandatory for compiled mode

 C_LONGINT($vName)

 C_TEXT(vNAME;vLIST)

 ARRAY TEXT($arrNames;0)

 ARRAY TEXT($arrVals;0)

 WEB GET VARIABLES($arrNames;$arrVals) //we retrieve all the variables of the form

 $vName:=Find in array($arrNames;"vNAME")

 vNAME:=$arrVals{$vName}

 If(Find in array($arrNames;"vEXACT")=-1) //If the option has not been checked

    vNAME:=VNAME+"@"

 End if

 QUERY([Jockeys];[Jockeys]Name=vNAME)

 FIRST RECORD([Jockeys])

 While(Not(End selection([Jockeys])))

    vLIST:=vLIST+[Jockeys]Name+" "+[Jockeys]Tel+"<BR>"

    NEXT RECORD([Jockeys])

 End while

 WEB SEND FILE("results.htm") //Send the list to the results.htm form

  //which contains a reference to the variable vLIST,

  //for example <!--4DHTML vLIST-->

  //...

End if

URL 4DCGI/

Syntax: 4DCGI/<action>

Usage: URL.

When the 4D Web server receives the /4DCGI/<action> URL, the On Web Authentication Database Method(if it exists) is called. If it returns True, the Web server calls the On Web Connection Database Method by sending the URL “as is ” to $1.

The 4DCGI/ URL does not correspond to any file. Its role is to call 4D using the On Web Connection Database Method. The “<action>” parameter can contain any type of information.

This URL allows you to perform any type of action. You just need to test the value of $1 in the On Web Connection Database Method or in one of its submethods and have 4D perform the appropriate action. For example, you can build completely custom static HTML pages to add, search, or sort records or to generate GIF images on-the-fly. Examples of how to use this URL are in the descriptions of the PICTURE TO GIF and WEB SEND HTTP REDIRECT commands.

When issuing an action, a “response” must be returned, by using commands that send data (WEB SEND FILE, WEB SEND BLOB, etc.).

Warning: Please be sure to execute the shortest possible actions so as not to hold up the browser.

The Text Parameters Passed to 4D Methods Called via URLs

4D sends text parameters to any 4D method called via special URLs (4DACTION/ and 4DCGI/), in both contextual and non-contextual modes. Regarding these text parameters:

Although you do not use these parameters, you must explicitly declare them with the C_TEXT command, otherwise runtime errors will occur while using the Web to access a database that runs in compiled mode. The message is of the following type:
"Error in dynamic code
Invalid parameters in an EXECUTE command
Method Name:
Line Number:
Description: [<date and time>]"
This runtime error is caused by the fact that the text parameter $1 was not declared in the 4D method called when you clicked on the HTML link. Since the execution context is the current HTML page, the error does not specifically reference the method line. Explicitly declaring the text parameter $1 will eliminate these errors:
//M_SEND_PAGE project method C_TEXT($1) // This parameter MUST be explicitly declared //... WEB SEND FILE($mypage)
The $1 parameter returns the extra data placed at the end of the URL, and can be used as a placeholder for passing values from the HTML environment to the 4D environment.

Parameters to declare explicitly in the called 4D method

You must declare different parameters depending on the nature and the origin of the call to a 4D method.

On Web Authentication Database Method (if any) and On Web Connection Database Method
You must declare the six parameters of the connection:

  //On Web Connection Database Method

 C_TEXT($1;$2;$3;$4;$5;$6) //These parameters MUST be explicitly declared

Method called by the URL 4DACTION/
You must declare the $1 parameter:

  //Method called by the URL 4DACTION/

 C_TEXT($1) //This parameter MUST be explicitly declared

Method called by the tag 4DSCRIPT/ as an HTML comment in a document
The method should return a value in $0. You must declare the $0 and $1 parameter:

  //Method called by the tag 4DSCRIPT/ as an HTML comment

 C_TEXT($0;$1) //These parameters MUST be explicitly declared

URL 4DSYNC/

Syntax:
4DSYNC/$catalog{/TableName}
4DSYNC/TableName{/TableName}{/FieldName1,...,FieldNameN}{Params}

Usage: URL in POST or GET method

This URL synchronizes the data in the tables of the local 4D database with a remote database using HTTP. It is used to synchronize a 4D database with a client application installed for example on a Smartphone or other third-party HTTP applications.

The 4DSYNC/ URL is used in a GET method to recover the data of the 4D database or in a POST method to update the data in the 4D database.

Here are the different HTTP requests that can be received:

GET /4DSYNC/$catalog
Returns the list of database tables and how many records they contain. For example, if you have a structure with two tables: PEOPLE (2 records) and INVOICES (3 records), when you use the syntax: http://localhost/4DSYNC/$catalog/ it returns PEOPLE 2 INVOICES 3 in the browser.

GET /4DSYNC/$catalog/TableName
Returns a description of the TableName structure (XML format).

GET /4DSYNC/TableName/FieldName1{,FieldName2},...
Returns the data of the FieldName field in the TableName table.

GET /4DSYNC/TableName/FieldName1?$stamp=0&$format=json
Returns the data of the FieldName field in the TableName table starting from stamp 0 and in the json format.

POST /4DSYNC/TableName/FieldName1{,FieldName2},...
Integrates the modifications made on the client machine into the 4D database.

Note: The data exchange format is JavaScript Objet Notation (JSON). The complete grammar is available from the technical support of 4D, Inc.

Note: In order for synchronization mechanisms to be enabled, the Allow database access through "4DSYNC" URLs option must be checked on the "Web/Configuration" page of the Database Settings (see below). Otherwise, requests containing 4DSYNC URLs will fail.

Notes about synchronization with HTTP

When using the 4DSYNC/ URL, you need to take the following principles into account:

4D works with the virtual structure of the database if it exists. In this case, the TableName and FieldName parameters correspond to table and field names that have been specified using the SET FIELD TITLES and SET TABLE TITLES commands. Note that the scope of these commands is the session and when using 4D Server you must call them in a stored procedure on the server.
Replication of BLOB and Picture type fields is not supported.
To be able to synchronize data:
- The HTTP server must be launched.
- The Allow database access through "4DSYNC" URLs option must be checked on the "Web/Configuration" page of the Database Settings (see the Connection Security section).
- The "Enable Replication" property must be checked for each table where you want to synhronize the data. If a virtual structure has been defined, these tables must be included in it. Warning: checking this option publishes additional information; you must make sure that access to your database is protected (see the description of this option in Connection Security).
When 4D receives a /4DSYNC request, the On Web Authentication Database Method is called (except when the password is incorrect, see the connection diagram in Connection Security). If it returns True, the request is executed; otherwise it is refused.