Modules (part 1)

This page describes the module system for the CrossmarX Scripting API.

Introduction

The CrossmarX Scripting API contains a large collection of entities (i.e. objects, types, constants) to use in your scripts, which are organized in modules. A module is best viewed as a bundle of related functionalities, i.e. types and objects that are (mostly) used within a certain functional domain. For example, the crossmarx.io module contains types and objects which are used to access files on the file system for your application, and the crossmarx.model module contains objects, types, and constants that have to do with the blueprint of your application. In order to use an entity in a script, you typically have to import it from its module into your script's runtime. Note that this does not apply to objects that are returned from methods, and importing is only necessary when entities are referenced by name. This is the case for constants and enumerations, and when accessing constructors and static methods.

Default objects and modules

In the previous pages in the CrossmarX Scripting documentation series, you will have encountered a number of entities, for instance Record and Query, which were referenced by name, for example when constructing a Query object using its constructor and the new keyword. If you have already inspected the API documentation for those entities, you may have noticed the modules that contain those entities, in this case data, and search, respectively. However, in order to use those entities, it is not strictly necessary that you know to which module those belong. This is because both entities - and indeed all entities mentioned in these pages - are by default available to your scripts, and do not need to be explicitly imported from their respective modules. At present, the entities that are automatically available are Blueprint, Classes, FieldRoute, Filter, FilterOperator, LookupLists, Methods, Module, Query, Record, RecordList, Route, Service, Session, Type, and UserGroups (note that modules are themselved entities).

Importing entities

Every entity that is not available by default, and you want to reference by name, needs to retrieved from its module, which needs to be imported. This is done by using the static method import from the Module object. For example, to get the ByteBuffer type from the module crossmarx.io:

const ByteBuffer = Module.import("crossmarx.io").ByteBuffer;
let myByteBuffer = new ByteBuffer();

The method Module.import accepts the name of a module as an argument. The result is the imported module - provided it actually exists, from which you can then retrieve a desired entity and have it assigned to a local variable, as shown on line #1. From that point on, it can be used anywhere in your script, for instance to create a new object of the type the variable now represents, as is shown in line #2. Note that you are absolutely free to choose a name any other than "ByteBuffer" for your variable, it will still hold the type ByteBuffer from module crossmarx.io, and can be used as such. However, unless you are forced by some technical reason to choose a different name, it is good practice to use the exact name of the type, to avoid any confusion.

Importing entire modules

When using multiple entities from the same module, repeating the first line of the example above may not be the most efficient option. Better is to first save the imported module itself in a variable, and then refer to the module's content via that variable. Consider the following JavaScript snippet, again using the Module.import function:

const io = Module.import("crossmarx.io");

let tfs = io.FileSystem.TEMP; // get the "temp" file system
let file = tfs.create("myFile.txt"); // create a new file on the temp file system
let writer = new io.FileWriter(file, io.FileAccess.TEXT); // create a writer with access mode "TEXT" for file

Here we use the entities FileSystem, FileWriter, and FileAccess from the crossmarx.io module, but instead of importing them individually, we just import the entire module. In this case, the Module.import function returns an object of type Module, which contains all (named) entities as members. This may be more efficient when using a lot of entities from the same module.