Show/Hide Toolbars

TMS XData Documentation

Navigation: Web Applications with TMS Web Core

Setting Up the Connection with TXDataWebConnection

Scroll Prev Top Next More

TXDataWebConnection is the first (and key) component you need to use to connect to XData server from TMS Web Core applications. Simply drop the component in the form set its URL property to the root URL of XData server:

 

XDataWebConnection1.URL := 'http://localhost:2001/tms/music';

 

(Even though the examples above and below will show setting properties from code, since TXDataWebConnection is available at design-time, you can set most of the properties described here at design-time in object inspector, including testing the connection).

 

Then you perform the connection setting Connected property to true:

 

XDataWebConnection1.Connected := True;

 

It's as simple as that. However, for web applications, you must be aware that all connections are performed asynchronously. This means that you can't be sure when the connection will be performed, and any code after Connected is set to true is not guaranteed to work if it expects the connection to be established. In the following code, for example, the second line will probably not work because the connection is probably not yet finished:

 

XDataWebConnection1.Connected := True;
// The following line will NOT work because connection
// is still being established asynchronously
PerformSomeRequestToXDataServer();

 

To make sure the component is connected and you can start performing requests to XData server, you should use OnConnect and OnError events:

 

OnConnect and OnError events

 

When connecting, either one of those two events will be fired upon request complete. Use the OnConnect event to be sure the connection was performed and start communicating with XData server:

 

procedure TForm1.ConnectButtonClick(Sender: TObject);
begin
  XDataWebConnection1.URL := 'http://localhost:2001/tms/music';
  XDataWebConnection1.OnConnect := XDataWebConnection1Connect;
  XDataWebConnection1.OnError := XDataWebConnection1Error;
  XDataWebConnection1.Connected := True;
end;
 
procedure TForm1.XDataWebConnection1Connect(Sender: TObject);
begin
  WriteLn('XData server connected succesfully!');
  PerformSomeRequest;
end;
 
procedure TForm1.XDataWebConnection1Error(Error: TXDataWebConnectionError);
begin
  WriteLn('XData server connection failed with error: ' + Error.ErrorMessage);
end;

 

Open method

 

As an alternative to events, you can connect using Open method, which you pass two parameters: a callback for success and a callback for error.

 

procedure TForm1.ConnectButtonClick(Sender: TObject);
 
  procedure OnConnect;
  begin
    WriteLn('XData server connected succesfully!');
    PerformSomeRequest;
  end;
 
  procedure OnError(Error: TXDataWebConnectionError);
  begin
    WriteLn('XData server connection failed with error: ' + Error.ErrorMessage);
  end;
 
begin
  XDataWebConnection1.URL := 'http://localhost:2001/tms/music';
  XDataWebConnection1.Open(@OnConnect, @OnError);
end;

 

OnRequest event

 

OnRequest event is called before every request about to be sent to the XData server. This is an useful event to modify all requests at once. For example, it's often used to add authentication information the request, like a authorization token with a JWT header:

 

procedure TForm1.XDataWebConnection1Request(Request: TXDataWebConnectionRequest);
begin
  Request.Request.Headers.SetValue('Authorization''Bearer ' + LocalJWTToken);
end;

 

DesignData property

 

DesignData property is intended to be used just at design-time, as an opportunity for you to add custom headers to be sent to the server. Analogously to the OnRequest event, it's useful to add authorization header to the request so you can connect to XData server at design-time. To use it just click the ellipsis button in the DesignData.Headers property and add the headers you need.

 

xdata_web_designdata

 

Those headers will by default not be saved in the dfm, meaning you will lose that information if you close/open the project, or even the form unit. This is for security purposes. In the exceptional case you want information to be saved (and thus also loaded at runtime), you can set the Persist property to True.