Records and blueprint constants

This page describes, and gives examples of, some basic techniques that you will need for successfuly writing scripts in your application. It is focussed solely on the CrossmarX Scripting API, and will not discuss any details (such as how to write a for-loop) of the programming language you might choose to implement your script in.

Record objects

All information contained in your application is stored in records in the database of your application, and a large portion of your business logic will likely be about retrieving information from, and storing information in, records. In the introduction we have already seen that records are respresented in scripts as objects of the type Record, and that objects of this type provide certain methods to manipulate them, for instance save. For a full overview of all methods available on the class Record (and other classes), see the CrossmarX Scripting API documentation. In this section we will concentrate on two of those methods: get and put, or more specifically: on the relation of the blueprint (i.e. data model) of your application to records in scripts.

The blueprint of your application consists of - amongst other things - classes and their fields. Every record belongs to a (one) class, and its contents are stored in the fields that belong to that class, as defined by the blueprint. If your have a record in your script, retrieving the value of a specific field from that record is done by invoking on that record object the method get, which expects an argument of type DataField. What exactly a data field is will be discussed later, but for now consider it to be equivalent to an object that represents a field in your blueprint. So, in order to tell the get method for which field you request the value, you have to provide an object that represents said field.

The Blueprint object

Since all fields (of all classes) of your application are defined by the blueprint, there is only a limited set of field objects available to use in your scripts, and this set is provided through a special object, which is always available to every script. This Classes object provides access to all classes defined in your blueprint. To get hold of a Field object in order to retrieve its value from a record, we first have to get the object that represents the class that field belongs to. In the Classes object, every class can be found in a property of that object with the name of that class (or rather, a technical rendering of that name, about which more further on). Let's say you need the object (of type Class) for your blueprint class named "person"; this object can be obtained as follows (JavaScript):

let myClass = Classes.person;

Now, the variable myClass in your script will hold the class object for the class "person". Now this object in much the same way, has itself properties for all fields that belong the that class. So, if your class "person" has a field called "Name", it is available as a property of the class object in myClass:

let myField = myClass.Name;

Now the variable myField holds the field "Name" of class "person". Of course you do not have to store the class object in a variable in between, so you could also have written:

let myField = Classes.person.Name;

to the same effect, or indeed use the right hand side of the assignment above directly whereever you were to need this field object.

Getting and putting values

Having gained access to this field object, we now have the means to use the get method on a record object. Let's say you have a record of class "person" (in variable personRecord) and you wish to retrieve its value for field "Name":

let name = personRecord.get(Classes.person.Name);

The value (if there actually was one, i.e. the record did not contain an empty value for that field) will now be stored in the variable name. Note that we could also have used the variable myField from the examples above, as the argument to the get method, to the same effect.

Similarly, field objects can be used to put values in a record, through the put method, which accepts two arguments, one of type Field and the other of type object, which basicallly means anything (any value - i.e. object - you have in your hands in your scripts will be technically accepted by the put method; however, if the value does not match the data type of the field, an exception may be thrown). The next example will put the value "John" in the "Name" field of a record of class "person", replacing whichever value it previously may have held:

personRecord.put(Classes.person.Name, "John");

Here we assume that the field "Name" naturally has data type Text (i.e. string), which means it will accept the string value "John" without causing trouble. We could however - if we wanted to - go completely weird en put something totally unacceptable in this field:

personRecord.put(Classes.person.Name, personRecord);
personRecord.put(Classes.person.Name, Classes.person.Name);

In the first line we try to put the record "into itself", and in the second the field object representing field "Name" as a value (into that very same field in the record). Both are syntactically correct, because both personRecord and Classes.person.Name are objects that are valid arguments for type object, but a bit down the line the engine will realize that those are not proper values to be stored in a field of type Text, and inflict punishment by throwing an exception.

Dealing with more complex names

Of course not every class in your blueprint has a name consisting of just a single word, nor have all of the fields, and this would cause some trouble of you were to try to access their respective class and field objects by exactly their names, given the fact that programming languages impose restrictions on the naming of variables, properties, and methods, most notably that spaces are not allowed. To mitigate this, all inappropriate characters in those names are replaced by underscores ("_"). Also, any diacritics are replaced with their normalized counterpart. For example, a field with name "Employee's annual income" will have the property name (or identifier) Employee_s_annual_income, and a class named "Boötes Void" is refered to by identifier Bootes_Void. (Please also note that any leading underscores are omitted from these identifiers.)