2. First things first

In the previous section we used the terms JSON and
JavaScript object. But what is it exactly and what are the differences? In
JavaScript, a variable can contain a simple value as well as an object
or an array.

// JavaScript
let i = 5;
let s = 'some text';
let o = {
  a = 'text',
  b = i
}

In this example the variable o contains a JavaScript object
with the two attributes a and b where a contains a text and b contains a
number.

In TMS WEB Core there is a type JSVALUE for the value of a
variable from the JavaScript world. Whenever we want to access the value of a JavaScript variable, we can use the JSVALUE type
for it.

// WEBCore

function sampleJavascriptVariable : JSVALUE; assembler;
asm
  let i = 5;
  return i;
end;

procedure AccessJsvalue;
var
  javascriptvalue: JSVALUE;
  i: integer;

begin
  javascriptvalue := sampleJavascriptVariable;
  // value will now contain the JavaScript VALUE (hence JSVALUE) 5
  i := integer(javascriptvalue);
  // we needed to typecast javascriptvalue to integer because the compiler
  // doesn't know the type of the value actually stored in that variable
end;

So whenever we want to access JavaScript values directly
from TMS WEB Core, we need a typecast to tell the compiler which type the value in the variable with the type JSVALUE contains. This is already
cumbersome with simple types and also error-prone and it gets even more complex when we want to access JavaScript objects.

Let’s summarize: A JavaScript object is an object in the
JavaScript world that is stored in an internal representation in a JavaScript variable. To store such a JavaScript object in an Object
Pascal variable in TMS WEB Core, the object pascal type JSVALUE is available.

And what has all this to do with JSON ?

JSON (JavaScript Object Notation) is a string that
represents a JavaScript object. A JavaScript object can be converted to JSON
and a JSON string can be converted to a JavaScript object. More information about the syntax definition of JSON can be
found here: https://www.json.org/json-en.html.

Whenever we talk about JSON, we mean a string from an
Object Pascal point of view. Whenever we talk about a JavaScript object we mean a JSVALUE from an Object Pascal point of view.

// WEBCore

var
  json: String;
  javascriptobject: JSValue;

begin
  json := '{ "x" : 5, "y" : 7 }';
  javascriptobject := TJSJSON.parse(json);
end;

In this example the JSON variable contains a JSON
representation (data type String) of an object with the members x and y, both containing numbers. This string is parsed into a JavaScript
object using the static method TJSJSON.parse() and stored in the variable javascriptobject.

Note: All sample sources use only the units that are already
automatically included in the uses list of a standard TMS WEB Core web project. So you can try and reproduce everything directly in TMS WEB Core
when you include the source texts in the unit1.pas of a newly created project. To keep the example source code short, only
necessary code is shown, in real world code you would need to add some
exception handling here and there…

All well and good, now we have a JavaScript object in an
Object Pascal JSVALUE variable in TMS WEB Core. But how to access it and the individual elements?

3. Practical uses

This is where the backstage pass comes in handy: backstage
we learn what the pas2js compiler actually does with the TMS WEB Core source code when our source code is compiled.

type
  TCoordinate = record
    x: double;
    y: double;
  end;

var
  javascriptobject: JSValue;
  json: string;
  coordinate: TCoordinate;

begin
  json := '{ "x" : 5, "y" : 7 }';
  javascriptobject := TJSJSON.parse(json);
  coordinate := TCoordinate(javascriptobject);
  ShowMessage(Format('The coordinate is (%f,%f).',[coordinate.x, coordinate.y]));
end;

Backstage information: The pas2js compiler creates
JavaScript code from our Object Pascal source code and finally there is (almost)
no difference between a record and a JavaScript object. A
record is a JavaScript object in the resulting JavaScript code.

As in the previous example with the typecast from JSVALUE to
integer, we can tell the compiler with a typecast from JSVALUE to TCoordinate that we expect an object in the javascriptobject
variable that corresponds to the structure of the TCoordinate record type we defined.

In the following ShowMessage() we can then access the values
coordinate.x and coordinate.y and it even works with auto code completion.

Let that sink in.

If we tell the compiler what the structure of the JavaScript
object looks like by typecasting JSVALUE to an arbitrary record type, we only need one typecast and can then continue programming
exactly as if the variable would contain an Object Pascal record. Code completion works and error detection already at compile
time. No more cumbersome single accesses with potential typos.

What can we do with this new bag of tricks now?

To clarify this and to understand the following sample code
let’s have a quick look at the service https://jsonplaceholder.typicode.com. Here we can retrieve various JSON object representations of
sample data through a simple HTTPRequest and use them for testing purposes.

For example, the call
https://jsonplaceholder.typicode.com/users/1 returns the following object as
JSON:

{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
  "street": "Kulas Light",
  "suite": "Apt. 556",
  "city": "Gwenborough",
  "zipcode": "92998-3874",
  "geo": {
    "lat": "-37.3159",
    "lng": "81.1496"
    }
  },
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
  "name": "Romaguera-Crona",
  "catchPhrase": "Multi-layered client-server neural-net",
  "bs": "harness real-time e-markets"
  }
}

Accessing this data with our new knowledge is now pretty simple:

procedure TMainForm.BtnFetchUserClick(Sender: TObject);
type
  TUser = record
    id: integer;
    name: string;
    email: string;
  end;

var
  request: TJSXMLHttpRequest;
  json: string;
  javascriptobject: JSValue;
  user: TUser;

begin
  WebHTTPRequest.URL := 'https://jsonplaceholder.typicode.com/users/1';
  request := await ( TJSXMLHttpRequest, WebHttpRequest.Perform() );
  json := string(request.response);
  javascriptobject := TJSJSON.parse(json);
  user := TUser(javascriptobject);
  ShowMessage(Format('User %d''s name is %s. You can reach him/her at %s', [user.id, user.name, user.email]));
end;

Note: For this code example to work, we first place a
non-visual component TWebHttpRequest on the main form and change its name to WebHttpRequest in the Object Inspector. Additionally, in the
declaration of the form it is necessary to mark the BtnFetchUserClick method with the [async] attribute:

type
  TMainForm = class(TWebForm)
    WebHTTPRequest: TWebHTTPRequest;
    [async] 
    procedure BtnFetchUserClick(Sender: TObject);
  end;

In this example we have declared a record type TUser with
the fields id, name and email. Using the WebHttpRequest component, we fetch the JSON for a user from the typicode.com web service
and store the result in a JSON string variable. Then we convert the obtained JSON to a javascriptobject using TJSJSON.parse(json) and
cast it to our TUser type and store it in the user variable.

The variables user and javascriptobject then contain the
same values. Once as type TUser and once as JSVALUE. But both reference the same object in memory.

Using the variable user we can now access the individual
members of the user and display them in the ShowMessage() method as in this example. When entering the code we are supported by the
editor with Code Completion.

The question arises what happened to the rest of the values
of the JavaScript object for which we did not define any members in our TUser type declaration?

Well, they are still there, we just can’t access them with
our TUser type because the compiler doesn’t know about their existence. With our TUser type declaration we have not changed any data. We
only told the compiler how we imagine the representation of the JavaScript object and how we want to access it. A typecast
does not result in additional JavaScript code. It is merely information for the compiler that enables it to perform static type checks at
compile time.

If we want to access more details of the JavaScript object
from the example, we can simply extend our TUser type and get full access to all details:

procedure TMainForm.BtnFetchComplexUserClick(Sender: TObject);
type
  TGeo = record
    lat, lng: string;
  end;

  TAddress = record
    street, suite, city, zipcode: string;
    geo: TGeo;
  end;

  TCompany = record
    name, catchPhrase, bs: string;
  end;

  TUser = record
    id: integer;
    name: string;
    email: string;
    address: TAddress;
    company: TCompany;
    nonExistentField: string;
  end;

var
  request: TJSXMLHttpRequest;
  json: string;
  javascriptobject: JSValue;
  user: TUser;
  doesOrDoesNot, msg: string;

begin
  WebHTTPRequest.URL := 'https://jsonplaceholder.typicode.com/users/3';
  request := await ( TJSXMLHttpRequest, WebHttpRequest.Perform() );
  json := string(request.response);

  javascriptobject := TJSJSON.parse(json);

  user := TUser(javascriptobject);

  if isDefined(user.nonExistentField) then
    doesOrDoesNot := 'does'
  else
    doesOrDoesNot := 'does not';

  ShowMessage( Format('%s lives in %s (Geolocation [%s,%s]) and works for %s. '
    + 'The field "nonExistentField" %s exist.',
    [ user.name, user.address.city, user.address.geo.lat, user.address.geo.lng, user.company.name, doesOrDoesNot ]) );

  ShowMessage('Value of user.nonExistentField is ' + user.nonExistentField);
end;

In the extended example we use a modified TUser type that
contains all the details of the JSON supplied by typicode.com and even defines an additional field.

The rest of the example code is the same for now and in the
ShowMessage() we can access all the details of the user, including the sub objects. Like such as using user.address.geo.lat to access
the coordinate of the address.

Since we have defined a field nonExistendField in our record
type, which does not occur in the JSON string at all, the typecast itself won’t be a problem. However, we would get a runtime error if
we access such field in the program code assuming that the field exists and contains a valid value. The good news is: with the
isDefined function, it is possible to check for the presence of a field value.

Again, no additional code is generated with our typecast. It
only tells the compiler which structure of the JavaScript object we expect and how we want to access it. A JavaScript object is a
JavaScript object and it is still a JavaScript object after the typecast. BUT
we can use it after the typecast as if it were an Object Pascal record.

Of course, this can go wrong if the structure of the JavaScript
object does not match the type definition. Is that a problem? It depends…

You usually know what data you expect from a service or in
an object. If the assumptions are not correct, you may get a runtime error, but it can be dealt with with exception handling.

Is this an additional new problem I’m introducing with
TypeCasts? No, the same problem exists in the pure JavaScript world. (But there it exists even without typecasts) There too, as a developer,
you make assumptions about the contents of my data structures. There too, a possible runtime error has to be handled. In the JavaScript
world, however, there is no compiler that helps you out with type checks.

4. Going even further

As we have seen, a JavaScript object is easy to use in TMS WEB Core if we have defined a suitable record type for it.

The pas2js compiler (or better transpiler) converts Object
Pascal to JavaScript and records become JavaScript objects. But not only that, Object Pascal arrays become JavaScript arrays. Better said:
Records are JavaScript objects, Arrays are JavaScript arrays. And since JavaScript arrays are just a special form of JavaScript
objects we can take advantage of this and access JavaScript arrays in the same
way we access JavaScript objects.

This is illustrated by the following example, where we
retrieve a whole list of users via https://jsonplaceholder.typicode.com/users.
The corresponding code looks like this:

procedure TMainForm.BtnFetchMultipleUsersClick(Sender: TObject);
type
  TUser = record
    id: integer;
    name: string;
    email: string;
  end;

  TUserArray = array of TUser;

var
  request: TJSXMLHttpRequest;
  json: String;
  javascriptarray: JSValue;
  users: TUserArray;
  user: TUser;

begin
  WebHTTPRequest.URL := 'https://jsonplaceholder.typicode.com/users';
  request := await ( TJSXMLHttpRequest, WebHttpRequest.Perform() );
  json := string(request.response);
  javascriptarray := TJSJSON.parse(json);
  users := TUserArray(javascriptarray);

  user := users[4];

  ShowMessage(Format('Received %d users. User %d''s name is %s. You can reach him/her at %s',
   [Length(users), user.id, user.name, user.email]));
end;

Here we convert the result of the web request using a type
cast into a standard array and can thus access all contained user records of
the array in a type-safe manner as shown in the ShowMessage() method.

5. The other way round

In the previous examples we always cast JavaScript objects
into records to be able to access JavaScript objects easily and comfortably from TMS WEB Core. Often we need to go the other way. If we need
to pass more complex data structures to web services, we need to serialize records or objects to pass them to JavaScript functions. Our
new principle works fine in this direction as well. Wherever a JSVALUE is expected, we can easily pass a record and this time we don’t
even need a typecast, because the receiving side (JavaScript) only knows universal variables, in which arbitrary values or objects
can be stored.

Here is a small example:

function AddAToB(value : JSValue): string; assembler;
asm
  value.result = value.a + value.b;
  value.s = 'The sum is ' + value.result;
  return JSON.stringify(value);
end;

procedure TMainForm.BtnTheOtherWayRoundClick(Sender: TObject);
type
  TSampleRecord = record
    a, b, c, result : double;
    s : string;
  end;

var
  sample: TSampleRecord;
  json: string;

begin
  sample.a := 4.5;
  sample.b := 3.2;
  json := AddAToB(sample);

  ShowMessage (json);
end;

In this example, we use the assembler directive to define a
JavaScript function AddAToB() that expects a JavaScript object as a parameter. This function does not know the type of the passed object,
but it makes assumptions about it in its code (welcome to the dark side). And so it performs an addition of the values value.a and value.b
and stores the result in value.result. Also, the result is stored as a string
in value.s and the entire value object in JSON representation
is returned as the result.

To call this dark side function AddAToB(), we define a
TSampleRecord with the values a and b, which we assign numbers to and then use that record as parameter for the function call.

Because of the type declaration, we as callers are not able
to preset the values a and b with strings. The type check of the compiler will prevent that.

We can get another interesting information from the function
result: The member c is contained in the result and has the value 0. Although the function AddAToB neither knows about the
existence of c nor has set the value. This is because we passed our record as a parameter to the function and there the c is defined and
during the initialization of the record in the Object Pascal world all members
were preset with default values.

So if we use records for values passed to JavaScript
functions, we can’t forget to create necessary members in the code, because
they are always pre-allocated by the record usage.

We hope that this blog article gave you some interesting
insights into the backstage of JSON and JavaScript objects in the TMS WEB Core concert.

Author: Martin Suer

Symproject GmbH https://www.symproject.com