URLs and Form Actions

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.

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 ...).

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.

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:

The 4D Web server offers an additional possibility when you want to use “posted” forms, which are static HTML pages that send data to the Web server. 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 COMPILER_WEB project method (if it exists, see below), then the On Web Authentication Database Method (if it exists). If it returns True, the MethodName method is executed. 4D analyzes the HTML fields present in the form, retrieves their values and automatically fills the 4D variables with their contents. The field in the form and the 4D variable must have the same name.

You can also use the WEB GET VARIABLES command, which retrieves the names and values of all the fields included in an HTML page submitted to the server.

Note: For more information, refer to the section Binding 4D objects with HTML objects.

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 value of the variable with the same name. For the form options (for example, check boxes), 4D sets the associated variable to 1 if it is selected, otherwise 0.

For numerical data entries, 4D converts the value of the field from Alpha–>Real.

Note: If a field in the form is named OK (for example the Submit button), the OK system variable is set to 1 if the value of the field is not empty, otherwise it is set to 0.

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>
<!-- Usually we put the name of the button in VALUE, for interpretation reasons, you must put a number in VALUE-->
<INPUT TYPE=CHECKBOX NAME=EXACT VALUE="1">Whole word<BR>
<!-- OK is a particular case-->
<INPUT TYPE=SUBMIT NAME=OK VALUE="Search">
</FORM>

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

4D then calls the COMPILER_WEB project method, which is as follows:

In the example, VNAME contains the string “ABCD”, vEXACT is equal to 1 and OK is equal to 1 (because the button’s name is OK).

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

Syntax: 4DCGI/<action>
Mode: Both.

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.

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 command C_TEXT, 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: "A runtime error occurred at line number: 0 when executing the method * ON WEB CONNECTION. Invalid parameter in a Run command".
  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 refers to "line 0" of the method that sent the page to the Web browser. Explicitly declaring the text parameter $1 will eliminate these errors: 
    `M_ADD_RECORDS project method
 C_TEXT($1) ` This parameter MUST be explicitly declared
 Repeat
    ADD RECORD([Clients])
 Until(OK=0)
• 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.

You must declare differents 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:

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

• 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:

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.

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.