Icon Executing a Server Request

The most common use for the TServerRequest component is to receive/send content to/from the web server. Elevate Web Builder does just that for loading the columns and rows for datasets, as well as committing database transactions and sending inserts, updates, and deletes to the web server. Datasets use the JSON format for exchanging data with the web server, but server requests do not impose any restriction on the format of the content that is sent or returned from the web server other than the fact that it must be textual (or encoded in a textual format, as is the case with Base64 encoding).

Use the following steps to execute a server request using a TServerRequest component:
  • Make sure that the TServerRequest Method property is set to the desired value. The default value is rmGet.


  • Assign the proper URL to the TServerRequest URL property.

    Warning If the origin (protocol, host, and port) specified in the URL is different than the origin for the application, then you will need to set the TServerRequest CrossOriginCredentials property to true in order to have any HTTP cookies and/or authentication headers sent to the web server that is servicing the HTTP requests for the URL.

  • Assign any URL parameters to the TServerRequest Params property. The Params property is a TStringList object instance with an equals (=) name/value separator. Each parameter should be specified in the name=value format as a separate string in the list.

    Information URL parameters are automatically appended directly to the URL by the TServerRequest component when the Execute method is called, so do not add them directly to the URL property. You can use the RequestURL property to retrieve the full URL that will be sent to the destination web server when the server request is executed.

  • Assign any custom request headers to the TServerRequest RequestHeaders property. The RequestHeaders property is a TStringList object instance with a colon (:) name/value separator. Each header should be specified in the following format as a separate string in the list:

    Name: Value

  • Create and assign an event handler to the TServerRequest OnComplete event. This will ensure that you can determine when the request is complete.


  • Call the TServerRequest Execute method to initiate the web server request.
TServerRequest Example
For example, suppose that you wanted to retrieve customer data from the web server in the following key-value format:

ID=100
Name=ACME Manufacturing, Inc.
Contact=Bob Smith
Address1=100 Main Street
Address2=
City=Bedford Falls
State=NY
ZipPostal=11178

To do so, you would use code like the following:

procedure TMyForm.MyFormCreate(Sender: TObject);
begin
   MyRequest:=TServerRequest.Create(nil);
end;

procedure TMyForm.MyFormDestroy(Sender: TObject);
begin
   MyRequest.Free;
end;

procedure TMyForm.RequestComplete(Request: TServerRequest);
begin
   if (Request.StatusCode=HTTP_OK) then
      ShowMessage('The value of the customer ID is '+
                  Request.ResponseContent.Values['ID'])
   else
      raise EError.Create('Response Error: '+Request.StatusText);
end;

procedure TMyForm.GetCustomerClick(Sender: TObject);
begin
   MyRequest.URL:='/customer';
   MyRequest.Params.Add('method=info');
   MyRequest.ResponseContent.LineSeparator:=#10;
   MyRequest.OnComplete:=RequestComplete;
   MyRequest.Execute;
end;

TServerRequestQueue Example
To use the TServerRequestQueue component instead of the TServerRequest component, you would use the following code:

procedure TMyForm.MyFormCreate(Sender: TObject);
begin
   MyRequestQueue:=TServerRequestQueue.Create(nil);
end;

procedure TMyForm.MyFormDestroy(Sender: TObject);
begin
   MyRequestQueue.Free;
end;

procedure TMyForm.RequestComplete(Request: TServerRequest);
begin
   if (Request.StatusCode=HTTP_OK) then
      ShowMessage('The value of the customer ID is '+
                  Request.ResponseContent.Values['ID'])
   else
      raise EError.Create('Response Error: '+Request.StatusText);
end;

procedure TMyForm.GetCustomerClick(Sender: TObject);
var
   TempRequest: TServerRequest;
begin
   TempRequest:=MyRequestQueue.GetNewRequest;
   TempRequest.URL:='/customer';
   TempRequest.Params.Add('method=info');
   TempRequest.ResponseContent.LineSeparator:=#10;
   TempRequest.OnComplete:=RequestComplete;
   MyRequestQueue.AddRequest(TempRequest);
end;

Information If the request results in a status code other than HTTP_OK class of status codes (200-299), then the request queue will automatically stop executing requests until the request is retried or cancelled. This is also the case if the OnComplete event handler raises an exception. You can call the ExecuteRequests method to retry the requests from the last request that failed, or call the CancelRequest to cancel the last request that failed and continue with the next queued request.

Cancelling a Server Request
Sometimes it is necessary to cancel a pending server request, and this can be done by calling TServerRequest Cancel method. If you're using a TServerRequestQueue component, then you can call the CancelRequest or CancelAllRequests methods to cancel one or more queued requests.
Image