Using the Contextual Mode

version 2003 (Modified)

The 4D Web server can operate in two different modes: non-contextual mode (standard mode) and contextual mode. This section describes these two modes and details the particularities of the contextual mode.

Warning: The contextual mode can only be used with 4th Dimension and 4D Server. The 4D Client Web server does not support this mode.

Note: The section Your First Time with the Web Server gives a complete example of the publication of a database in contextual mode.

Non-contextual and contextual mode

Starting with version 2003 of 4th Dimension, the 4D Web server uses the non-contextual mode by default (disconnected mode). In this mode, the operation of the 4D Web server is comparable to that of standard Web servers: when an HTTP request is received from a browser (URL, posted form, etc.), the server processes the request, then returns a response when necessary (sending a Web page, for example). No specific connection is maintained subsequently between the server and the browser.

In non-contextual mode, the Web server can send static or semi-dynamic pages. Semi-dynamic pages allow you to access data in the database or to carry out any type of processing using special 4D tags that are evaluated at the time the page is sent. Semi-dynamic pages allow you to build, manage and send Web pages whose content originates in whole or in part from processing carried out by 4D. Non-contextual mode generally meets most Web site development needs.

In contextual mode, connection to a Web browser causes the creation of a context in which the current selection, its variables, etc. will be placed. In a way, each browser is considered as a 4D Client connecting to the database in Custom Menus mode. The context is handled by a specific Web connection process.

This mode allows instant publication of a 4D database on the Web, without it being necessary to create Web pages: 4D manages and sends to the browser dynamic pages stemming from automatic conversion of database menu bars and forms into HTML. In contextual mode, it is still possible to send semi-dynamic or static pages. It is also possible to insert HTML or Javascript code into 4D forms in order to add functions to the pages displayed on the Web.

In addition, in this mode 4D automatically handles simultaneous access to data: when a browser or a 4D Client machine loads a record, 4D locks it for other users in a transparent manner, whether they be browsers or other 4D Client machines. Moreover, 4D allows you to carry out data entry during a transaction with a Web browser, in the same way as with 4th Dimension or 4D Client. This system enables the 4D Web server to control the actions of the browsers and to guarantee data integrity.

In return for this ease of publication, the contextual mode includes several constraints:

- Web browsers allowing "surfing" from one Web page to another, one site to another, etc. With a client/server type database, this navigation must be controlled in order to respect the logic of database transactions. Each entry carried out by a user in a record must be validated or cancelled in order not to remain in an uncertain state. The 4D Web server engine contains automatic mechanisms that manage database sessions and contexts. These mechanisms prevent the use of certain standard browser functions (Reload, Previous page, etc., see next paragraph).

- The connection process in charge of maintaining the context remains active until the timeout of the browser defined in the database Preferences is reached. If, for instance, the browser has left the site in the meantime, the context is then "wasted".

These constraints mean that the contextual mode is intended rather for Intranet use or for use within the framework of specific Internet applications.

How 4D Web Server functions is summarized in the following figure:

Choosing the 4D Web server operating mode is carried out as follows:

• On startup of the server, using the Starting Mode option of the database Preferences,

• During Web server use, according to the URLs sent or the commands executed.

In fact, some special URLs and certain 4D commands can be used to change the mode. In principle, the current mode remains in use as long as no URL or 4D command causes it to change.

By default, the Web server starts in non-contextual mode. You can start the Web server directly in contextual mode. This means that when a user connects to the database, a context is automatically generated.

To specify the non-contextual mode on startup, check the Contextual Mode (permanent context) option on the Configuration page in the Web theme of the database Preferences dialog:

During database operation, you can change mode by calling the following elements:

• Change to non-contextual mode:

- SEND HTML BLOB by passing True in the optional noContext parameter

- SEND HTML TEXT by passing True in the optional noContext parameter

- SEND HTTP REDIRECT

- URL beginning with /4DACTION

• Change to contextual mode:

- URL beginning with /4DMETHOD/MyMethod.

When the /4DMETHOD/MyMethod URL is sent, the 4D Web server creates a new context and carries out the following operations:

- The On Web Authentication Database Method is executed (if any),

- The On Web Connection Database Method is executed (if any) — in this particular case, $1 is equal to /4DMETHOD/MyMethod instead of / (slash),

- Finally, the requested method is executed in the newly created context.

Depending on the actions that they carry out, some Web processes use Web contexts and other do not.

You can find out the number of contexts generated using the PROCESS PROPERTIES command: for any Web process, this command indicates, in the origin parameter, whether it uses a context (-11, Web process with context) or not (-3, Web process without context).

The number present in the name of the Web connection process is called the context ID, which is randomly generated and uniquely identifies each Web connection. The context ID is maintained on both the 4D and the browser sides during the entire Web connection. In this example, the context ID is 1066993139. In the Web browser window shown here, you can see this number in the URL displayed in the Location area of the browser:

The URLs are automatically maintained by 4D during the whole Web session in contextual mode. Each time an HTTP request is received via TCP/IP, 4D extracts the context ID from the URL, and thereby can redirect the request to the right Web Connection process.

Context IDs:

• Enable 4D to maintain both a Web and Database session over each Web connection.

• Transparently handle multiple concurrent Web connections.

• Prevent future undesirable connections when using bookmarks, because a different context ID is generated at each connection.

In the window shown above, note that the context ID is followed by a dot and a second number, called the subcontext ID. 4D automatically manages and increments this number each time a new 4D-based HTML page is sent to the browser in contextual mode. The subcontext ID is essential to the maintenance of the database session.

Usually, a Web browser includes navigation controls, such as the Back and Forward buttons, History windows, and so on. These controls are useful when you are browsing documents, news, bulletin boards, etc. They are less appealing when you perform a database transaction.

For example, if a Web user is adding a record to a table, you need to know whether or not the data entry is validated, that is, whether or not the Web user clicked the Accept or Cancel buttons of your 4D form. If, at this point, the Web user navigates to other pages, the data entry is left in an uncertain state. To prevent this, 4D uses the subcontext ID to synchronize the Web session on the browser side with the database session on the 4D side.

Each time a form is submitted or an HTTP request is sent to 4D by the browser, if a desynchronization of the Web and database sessions is detected, 4D sends the message "Using browser navigation controls, you left a form requiring data validation. 4th Dimension will now return to that form so you can accept or cancel it." 4D then goes back to the Web data entry page using the subcontext ID.

This synchronization is also essential for the Web Connection process. You need to correctly get out of, for example, an ADD RECORD ([...]) to pursue the execution of your 4D code.

The synchronization is selective. If the current Web page displayed on the browser side is a 4D form (ADD RECORD, DISPLAY SELECTION, DIALOG, etc.), the synchronization will eventuallly occur.

If the current Web page is an HTML page accessed by link from another Web page (sent using the command SEND HTML FILE), then you can navigate freely through the pages.

Given the following piece of 4D code:

   ADD RECORD ([Customers])
   SEND HTML FILE ("anyPage.HTM")
   DISPLAY SELECTION ([Products])

The following figure details what happens both on 4D and the Web browser during execution.

• Lines in red denote 4D form translations and submissions.

• Lines in blue denote switching back and forth between 4D-based and non 4D-based HTML pages.

• Areas in green denote non 4D-based HTML pages.

(1) An ADD RECORD is issued. 4D translates the current input form of the table into an HTML page and sends it to the Web browser. If the form is a multi-page form, the standard 4D page navigation buttons allow you to navigate through the pages of the form. This 4D-based navigation is implemented and performed transparently by 4D (via Web form submission).

(2) During data entry (therefore within the ADD RECORD call), a button is clicked and its object method issues a SEND HTML FILE call.

(3) Within the SEND HTML FILE call, if the HTML page includes links, it is possible to navigate through several pages. Eventually, when a SEND HTML FILE("") is issued, the HTML mode is exited.

(4) The object method of the button that was clicked and the data entry initiated by ADD RECORD are executed. Note that steps (2) and (3) can be repeated several times within the data entry.

(5) Finally, the data entry is accepted or canceled, and the Web Connection process is executed.

(6) The next call is a SEND HTML FILE.

(7) This step is analogous to step 3. If the HTML page includes links, it is possible to navigate through several pages. Eventually, when a SEND HTML FILE("") is issued, the HTML mode is exited.

(8) The Web Connection process is executed.

(9) A DISPLAY SELECTION is issued. 4D translates the current output form of the table into an HTML page and sends to the Web browser. During the DISPLAY SELECTION, 4D transparently navigates between the selection page and the display of individual records. 4D also uses MODIFY SELECTION to manage data entry and record locking, via Web form submissions.

(10) During navigation through the selection, a button in the footer area of the form is clicked and its object method issues a SEND HTML FILE call.

(11) This step is analogous to steps 7 and 3. If the HTML page includes links, it is possible to navigate through several pages. Eventually, when a SEND HTML FILE("") is issued, the HTML mode is exited.

(12) The object method of the button that was clicked and the selection display initiated by DISPLAY SELECTION are executed. Note that steps (10) and (11) can be repeated several times during navigation of the selection.

(13) Finally, the selection display is exited and the Web Connection process is executed.

And so on...

Free Web navigation (clicking on the Back or Forward buttons for instance) is possible within any SEND HTML FILE (green areas in the figure above). On the other hand, any 4D-based HTML page (data entry, selection display... including standard dialog boxes such those displayed by CONFIRM or Request) is exited through the use of one of the browser navigation controls, 4D will eventually synchronize the Web sessions and the Database sessions by going back to the Web page whose subcontext ID corresponds to that of the issued 4D command currently being executed on the Web Connection process side.

From the user viewpoint, the user's actions on the Web browser side pilot a Web session.

From the programmatic viewpoint, the Web Connection process pilots the Web session, not the reverse. The Web browser displays the pages sent by the Web Connection process, which either:

• Executes 4D code, or

• Waits for the submission from the browser of the current Web page.

From a Design viewpoint, the Web Connection process should be seen as a 4D process whose domain of execution is 4th Dimension or 4D Server, but whose user interface is remotely echoed on the connected Web browser.

With this in mind, always take into account this duality of the Web Connection process when designing Web database applications in contextual mode. For example:

• During data entry of any kind, the main menu bar is that of the browser, not that of 4D. Within a form, do not rely on the 4D menu bar; it is on the Web server machine, not on the Web browser machine,

• When you design forms to be used on the Web browser, remember that the 4D form set of features is limited to that of HTML (but sometimes with some 4D additions). Do not rely on the whole 4D forms feature set (i.e., object types and form events). For more information on this point, refer to the paragraph "Automatic HTML conversion" below.

• In terms of interprocess communication, CALL PROCESS, when applied to a Web Connection process, has no effects because its current active form is displayed on the Web browser. On the other hand, a Web Connection process can issue a CALL PROCESS toward another 4D process.

In addition, interprocess communication can be indifferently performed in both directions using the GET PROCESS VARIABLE and SET PROCESS VARIABLE commands, which do not require a process to have a user interface.

As explained previously, a Web Connection process in contextual mode is either executing 4D code or waiting for the submission of the Web page currently displayed on the browser side. In the latter case, a Web Connection process will wait for a delay equal to the Inactive Web Process Timeout, set on the Advanced page (Web theme) of the Preferences window or set programmatically using the SET WEB TIMEOUT command.

The scope of the Web Server Connections Timeout setting is the database session. All contextual Web Connection processes are subjected to that value; they are immediately affected if that setting is changed. The default value is 5 minutes.

Note: The command SET WEB TIMEOUT allows you to specify a different Timeout for each Web process.

You can increase or decrease this timeout at your convenience. For example, you can increase the timeout if your application allows Web users to surf to other Web sites via HTML links in the pages served by your database. By increasing the timeout, you enable users to navigate longer within the other Web sites without closing their connections to your databases.

WARNING: There is no way to programmatically stop a Web Connection process. If you specify a long timeout, the process will wait for that delay, even though the Web user may have stopped working with the Web Connection for quite some time. If you specify No Timeout, the Web Connection processes will stop only when the database is exited. However, a Web connection process is automatically aborted as soon as the Web server switches to non-contextual mode.

Tip: Unlike Web Server process, Web Connection processes can be aborted using the Abort command (available in the Runtime Explorer when the Process page is displayed).

This paragraph specifies the elements, objects and mechanisms handled automatically during database conversion into HTML by 4th Dimension in contextual mode.

• Each menu bar is translated into one HTML page. Each menu title appears as text only and menu commands associated with 4D methods appear as links to these 4D methods. Menu commands that are only associated with automatic actions appear as text only.

• Clicking a menu item on the Web Browser side starts the execution of the associated 4D method on the Web Connection process side.

Note: When the "Start a New Process" property is assigned to a menu command, the associated method is executed by the 4D Web server in a new Web connection process using the 4DMETHOD URL. In this case, the method of the menu must have the Available through 4DACTION, 4DMETHOD and 4DSCRIPT attribute (unchecked by default for new databases). For more information, refer to the Connection Security section.

• The picture associated with a menu bar is placed below the menus on the browser.

• Objects are translated from top to bottom and from left to right, and they have the same position on the browser as they do in the 4D form. Note, however, that HTML is a word processing oriented application; horizontal objects positions may be different and wrap-around may occur.

• Multi-page forms are supported transparently, including a page zero and inherited forms.

• Automatic actions, when appropriate, are supported transparently.

• Form events (On Load, On Unload, On Clicked and On Timer) are supported. Other events are not supported.

• The Header, Detail, Break and Footer tags are taken into account during calls to DISPLAY SELECTION and MODIFY SELECTION. The Header of the form appears once at the beginning of the HTML page, the detail area is repeated as many times as necessary, and variables (such as buttons) placed in the Footer area appear at the end of the HTML page, just under the automatic selection page navigation links.

• The tips associated with buttons displayed as pictures in the form editor appear on the browser — if the browser allows these tips to be displayed.

• A picture replicated ("Replicated" display) inserted in the (0,0,x,x) coordinates in 4D's form editor is sent as a background picture on the browser. Please note that dark pictures should be avoided.

Note: The 4D Web server uses CSS1 to produce HTML pages with a very similar appearance to the 4D forms themselves. CSS1 (Cascading Style Sheet 1) specifications have been defined by the World Wide Web Consortium (W3C). These style sheets set some characteristics related to the document appearance: font, size, color, title, body, spacing, etc. .CSS documents are sent with the MIME type "text/css". In both contextual or non-contextual mode, these documents are not processed by 4D.

For compatibility reasons, you can modify the Web conversion mode to use for the forms using the SET DATABASE PARAMETER command (selector 8, Web Conversion Mode).

When a 4D form is translated to an HTML page, field objects are translated as follows:

(*) or text only if non-enterable

(**) If the text value is composed of several lines

(***) If the text value is composed of only one line or is empty

Note: Enterable variables behave like fields of the same type.

When a 4D form is translated to an HTML page, form objects are translated as follows:

The following objects are not supported by HTML and therefore are ignored during the translation:

Hierarchical Pop-up menu, Hierarchical List, Subform, Radio Picture, Thermometer, Ruler, Dial, Picture Pop-up Menu, Picture Button, 3D Check Box, 3D Radio Button.

1. Non-horizontal lines are not supported in HTML; they are therefore ignored.

2. Invisible-like buttons are objects of type Invisible Button, Highlight Button, 3D Button, and Button Grid. If a static picture is not overlapped by an invisible-like button, the picture is translated as a static image. If it is overlapped by at least one invisible-like button, it is translated as a Server-Side Image Map. On the Web browser side, the image is treated as a Server-Side Image Map. On the 4D side, when the submission is received, 4D recalculates the position of the click in order to generate an On Clicked event for the appropriate button, as if the button was actually clicked. Managing invisible-like buttons is therefore quite simple, provided that they overlap with static pictures. You manage these buttons through the Form method or their object methods, as you would do in the regular 4D interface. This also provides you with a very simple way to handle Web Image Mapping. If an invisible-like button does not overlap with any static picture objects, it is ignored during the translation.

3. Radio button grouping is maintained though the translation.

4. Grouped scrollable areas are not supported in HTML. 4D translates them as independent scrollable lists located on the same line.

5. Tab controls (of type array or created by using the values defined in the Object properties) are converted into URL lists.

If the array elements are empty strings, 4D displays 1, 2, 3... on the browser.

6. Plug-in areas are publishable on the Web, by first being converted into HTML, Image or Image Map. This last solution allows you to manage mouse clicks inside the plug-in area (for example, the integrated plug-in 4D Chart is published in an Image Map and the 4D_Pack _AP External clock area is published as an Image). The way in which a plug-in area, which is on a 4D form, is published on the Web depends on the plug-in editor's specifications.

• The UserSet mechanism is not supported

• An automatic selection paging mechanism is provided by 4D. For more information, see the description of the SET WEB DISPLAY LIMITS command.

While developing a 4D Web database, you may ask what happens when this or that command is called. Will the command take effect on the Web Server machine or on the Web Browser machine? The Web Connection Process is executing on the Web Server machine, but its user interface is remotely echoed on the connected Web Browser. Consequently, for Web database development, the 4D commands can be classified as follows:

A command such as CREATE RECORD works within the executing process; in this case, it creates a record within the Web Connection process. The same applies to commands such as Screen width, which returns the width of the screen on the Web Server machine (the machine on which the process is executing).

The following commands execute locally on the Web Server machine.

For example, you can invoke the printing of a selection from a Web Browser. However, the printing will be performed on the Web Server machine.

In addition, when a user interface component is involved, it appears on the Web Server machine, i.e., Open document("") vs Open Document("This document"). You should avoid such calls, because the Web Browser will wait for a reply until the dialog box is closed on the Web Server machine. On the other hand, it is perfectly OK to call these routines when no dialog boxes are involved.

Embedding HTML

You can customize the content of 4D forms converted into HTML by embedding HTML code (or Javascript) into the form. The resulting form, on the Web browser side, is a combination of HTML and 4D objects.

A static text object of a 4D form containing, for instance, the string "{page.HTM}", inserts the HTML document "page.HTM" into the 4D form at the place where the text object is located.

You insert a document in its entirety (in fact, everything included between the <BODY> and </BODY> tags). You can either use an existing HTML document, or, using language, build a document that you save to disk and to which you refer subsequently.

Note: In some cases, HTML conversion of 4D forms created in version 6.0.x that contain a reference to an HTML document ({mapage.htm}) do not always give the expected result with 4D version 6.7 and later. In this case, it is possible to modify the form conversion mode using the SET DATABASE PARAMETER command.

Any 4D text variable can embed HTML code into a 4D form, if its first character has the ASCII code 1 (for example, vtHTML:=Character(1)+"...HTML code...").

You can thus insert pieces of code and, in this case, you can build the HTML code into memory.

In contextual mode, to insure the maintenance of the database context and subcontext IDs, 4D automatically remaps file references and URLs. For example, 4D remaps all IMG and HREF references to local files.

If you insert your own HTML code into a 4D form using a text variable, you must follow the 4D remapping syntax.

Local GIF files are remapped as "/4DBin/_/GIF_file_pathname", where GIF_file_pathname is the full HTML path name of the GIF file relative to the root of the volume where the file is located.

The following 4D method returns the remapped reference for the pathname received as parameter:

      ` WWW Local GIF URL Project Method
      ` WWW Local GIF URL Project ( Text )
      ` WWW Local GIF URL ( Native pathname ) -> URL to local GIF file
   C_TEXT($0;$1)
   $0:="/4Bin/_/"+HTML Pathname ($1)

Note: For details about the method HTML Pathname, see the examples of the command Mac to ISO.

Then, when inserting HTML code into a 4D form using a text variable, you can write:

   vtHTML:=Char(1)+"<P><IMG SRC="+Char(34)+WWW Local GIF URL("F:\ThisImage.HTM"+Char(34)
                                                +" ALIGN=MIDDLE></P>"+Char(13)

This will insert the GIF document in the 4D form at the location of the 4D variable vtHTML.

Important: You only need to write this kind of code to insert custom HTML code into a 4D form. If you just send an HTML page using SEND HTML FILE or if you use a command such as ADD RECORD, remember that 4D transparently translates and remaps the HTML.

The remapping does not change links that have the following protocols:

• http:

• ftp:

• mailto:

• news:

• gopher:

• javascript:

• nntp:

• wais:

• prospero:

• telnet:

Connection Security, On Web Authentication Database Method, On Web Connection Database Method, SET DATABASE PARAMETER.