Icon Server Request Architecture

Elevate Web Builder produces web applications that are loaded once into a web browser. Such an application is different from a traditional web site with a collection of individual web pages that are navigated to using traditional URL links. In fact, navigating to a different URL in an Elevate Web Builder application will actually cause the application to be unloaded in the web browser, which is not the desired result for most situations.

Given this architecture, there needs to be a way for such an application to communicate with the web server in order to exchange data or content without causing an actual navigation or page load in the web browser. The name for this type of communication in modern web browsers is called AJAX, which stands for "Asynchronous JavaScript and XML". While AJAX was primarily designed to be used with XML data, it can be used with any type of textual content or data. Though AJAX can also be used in a synchronous, as opposed to asynchronous, manner, Elevate Web Builder always uses AJAX functionality in an asynchronous manner. What this means is that when a web server request is executed, the application will continue to execute and respond to user input while the request is being executed, and an event will be triggered when the request completes successfully or encounters an error.

When to Use Server Requests
It is important to understand when a server request should be used and, even more importantly, when one shouldn't be used. The following are cases where you should not use a server request:
  • If you only need to load and display an image, use a TImage control instead.


  • If you only need to send some values from input controls on a form to the web server, use the HTML Forms functionality instead.


  • If you are using databases, then use the built-in database handling that is provided.
HTTP Server Requests
AJAX web server requests are basically equivalent to the requests that are made by a web browser on your behalf when navigating URL links in a web page. These requests use the HTTP protocol which determines how the request and its response from the web server are formatted. A typical HTTP request looks like this:

GET /testproject.html HTTP/1.1
Accept: text/html
Accept-Encoding: gzip, deflate
Accept-Language: en-us
Cache-Control: max-age=0
Connection: keep-alive
Host: localhost
If-Modified-Since: Thu, 16 Aug 2012 18:35:21 GMT
User-Agent: Mozilla/5.0

Every HTTP request begins with a method name, followed by a URL and the version of the HTTP protocol being used by the web browser. Please see the following link for a complete definition of the various HTTP methods:

Method Definitions

Elevate Web Builder supports the GET, HEAD, POST, PUT, and DELETE methods in web server requests.

After the initial request line is one carriage return/line feed pair (0x0D and OxOA), followed by the request headers. All request headers use a format of:

<Header Name>: <Header Value>

Please see the following link for a complete definition of all standard HTTP headers:

Header Field Definitions

After the request headers are two carriage return/line feed pairs. If the request does not send any additional content, as would be the case with a POST request, then the request will not contain any additional data. If there is additional content, then the additional content will be sent after the two carriage return/line feed pairs. In addition, a "Content-Length" request header must be specified in the request headers that indicates the size, in characters, of the additional content.

Warning If you do not specify a content length header, then the most likely result is that the web server will simply ignore the content, return an error code, or both.

For example, suppose that you want to send the following text content to a web server in a POST request:

The quick brown fox jumps over the lazy dog

The length of the text is 43 characters, so the POST request would look like this:

POST /postcontent HTTP/1.1
Accept: text/html
Accept-Encoding: gzip, deflate
Accept-Language: en-us
Cache-Control: max-age=0
Connection: keep-alive
Host: localhost
User-Agent: Mozilla/5.0
Content-Type: text/plain; charset=utf-8
Content-Length: 43

The quick brown fox jumps over the lazy dog

Information At this point it is probably a good idea to point out that you do not have to format web server requests like this in order to use the server request functionality in Elevate Web Builder. However, it is important that you understand how such requests are formatted in order to properly add custom headers or content to web server requests, as well as to properly read and parse response content returned from the web server.

HTTP Server Responses
The format of responses from a web server are very similar to the format of the requests. A typical HTTP response from a web server looks like this:

HTTP/1.1 200 OK
Date: Thu, 17 Aug 2012 01:52:46 GMT
From: admin@elevatesoft.com
Server: Elevate Web Builder Web Server
Connection: Keep-Alive
Cache-Control: no-cache
Content-Type: text/plain; charset=utf-8
Content-Length: 139

NameEdit=Tim Young
EmailEdit=timyoung@elevatesoft.com
CommentsEdit=Comments
RememberMeCheckBox=False

Information The response content is not necessarily representative of the content that may be returned by any web server request, and is only used to represent the response content as a simple key-value example.

Every HTTP response begins with the version of the HTTP protocol being used by the web server, followed by a numeric response code and a textual status message. Please see the following link for a complete definition of the various HTTP response codes:

Status Code and Reason Phrase

In both an Elevate Web Builder application, and an Elevate Web Builder web server module, there are defined constants that represent the common HTTP status codes. In an Elevate Web Builder application, you will find these constants in the WebHTTP unit, which contains the TServerRequest and TServerRequestQueue components (see below) and is part of the standard component library. In an Elevate Web Builder web server module, you will find these constants in the ewbhttpcommon unit, which is distributed as a .dcu (Delphi compiled unit) with the Elevate Web Builder Modules installlation.

The constants are defined as follows:

   HTTP_NONE = 0;
   HTTP_CONTINUE = 100;
   HTTP_OK = 200;
   HTTP_MOVED_PERMANENTLY = 301;
   HTTP_FOUND = 302;
   HTTP_SEE_OTHER = 303;
   HTTP_NOT_MODIFIED = 304;
   HTTP_MOVED_TEMPORARILY = 307;
   HTTP_BAD_REQUEST = 400;
   HTTP_NOT_FOUND = 404;
   HTTP_NO_LENGTH = 411;
   HTTP_INTERNAL_ERROR = 500;
   HTTP_NOT_IMPLEMENTED = 501;
   HTTP_SERVICE_UNAVAILABLE = 503;

Core Components
In Elevate Web Builder, the components that encapsulate the AJAX functionality in the web browser are:

TServerRequest
TServerRequest components can be dropped directly onto a visual form at design-time in a visual project, or created at run-time in both visual and non-visual projects. The TServerRequest component encapsulates a single web server request. The Method property specifies the HTTP method (default rmGet) and the URL property specifies the URL for the request. Although the web browser will automatically populate all required request headers, you can specify additional request headers using the RequestHeaders property. You can use the Execute method to actually execute the request.

TServerRequestQueue
TServerRequestQueue components can be dropped directly on a visual form at design-time in a visual project, or created at run-time in both visual and non-visual projects. The TServerRequestQueue component implements a queue of server requests in order to force serialization of the server requests so that requests are executed in the order in which they are added to the queue. For example, the TDatabase component uses an internal TServerRequestQueue component to ensure that dataset load requests, as well as transaction commit requests, are executed in the order that they are requested.
Image