Client Logic API - CLAPI

The new Akioma Swat Client Logic API - CLAPI.

Below are some of the features that CLAPI introduces:

• Object-oriented programming.
• Compile-time checking.
• Intellisense and documentation.

TypeScript

The CLAPI is written in TypeScript which allows for compile-time checking and intellisense, among others.

TypeScript is a superset of JavaScript which mainly adds optional typing. JavaScript code is also valid TypeScript code (although it depends on the compiler settings).

TypeScript compiles (or transpiles) to plain JavaScript. The compiled JavaScript code looks almost exactly the same as the TypeScript source code without the typings (when compiling to ES6 and beyond).

TypeScript allows for compile-time checking not just for types but also for identifier names, syntax etc. even while typing code in your editor.

TypeScript also allows for intellisense on class methods and properties in addition to JSDoc.

Lastly, TypeScript allows to compile down to an older version of JavaScript (like ES5) so you can use modern JavaScript features and still support older browsers like Internet Explorer.

For a quick introduction to TypeScript see the link below -

https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html

TypeScript Configuration

There is only one TypeScript configuration file - tsconfig.json placed at the project root directory for all the TypeScript project configuration.

The CLAPI TypeScript configuration file is in the <application>-webui/ClientLogic/ directory, for example: sports-webui/ClientLogic/tsconfig.json

Note that you do not need to be familiar with the TypeScript configuration file to use CLAPI.

For a detailed explanation on tsconfig.json see the link below -

https://www.typescriptlang.org/docs/handbook/tsconfig-json.html

For a list of tsconfig.json compiler options see the link below -

https://www.typescriptlang.org/docs/handbook/compiler-options.html

Visual Studio Code

In the following example we will be using Visual Studio Code.

Visual Studio Code (VS Code) is a modern, popular and free code editor from Microsoft with built-in TypeScript support.

Fun fact: VS Code is actually written in TypeScript running on the electron framework.

To install VS Code follow the link below -

https://code.visualstudio.com/docs/?dv=win

To install a portable version follow the link below (if you are having permissions issues installing VS Code) -

https://code.visualstudio.com/docs/?dv=winzip

For introductory videos see the link below -

https://code.visualstudio.com/docs/getstarted/introvideos

Migrating to the CLAPI

In the following example we will migrate a function to the CLAPI. The function gets the foreign keys (or initial field values) when launching a window to create a new record.

In the Sports Sample Application, open the Customers desktop window. Click the New Order button in the Customer Grid Floating Action Button (FAB) (see picture below).

The foreign keys (like customer no.) or initial values in the New Order window are taken from the get foreign keys functions.

Calling CLAPI Functions

You can pass several system objects to a function call written in the Layout Designer or the Smart Component Library (SCL) Maintenance (starting with "$") -

• self - The repository object called dynObject for the event.
• oSelf - The widget object called controller for the event.
• eventSource - The CLAPI object for the event.

The CLAPI replaces the dynObject and controller objects with a single eventSource object. Use the eventSource object for CLAPI function calls.

All the Object Types in Swat, in the SCL Maintenance have equivalent CLAPI classes (except for a few exceptions).

Open the SCL Maintenance for the Sports Sample Application. Open the "New Customer Order" Menu Function in the Menu Function Maintenance. Replace "self" with "eventSource" in the Action Options field and save (see picture below).

Writing CLAPI Functions

Open the /sports-webui/ClientLogic/ folder in VS Code. Open Order/getOrderForeignKeys.js from the Explorer view (see picture below).

1. Start by renaming (F2) the file and replacing the JavaScript .js file extension to the TypeScript .ts file extension.
   
   Now that the file is saved as a TypeScript file, you can see the compile errors and use the intellisense.
   
   The compile errors are marked with a red squiggly underline. Hover over the error to show the error messages.
   
   Lines with errors are marked in red on the side scroll bar. Files with errors are marked in red in the File Explorer.
   
   The intellisense and JSDoc comments opens automatically when typing object method and properties (starting when typing "." after an object).
   
   If the JSDoc comments are not shown together with the intellisense, click the blue circle with an "i" to show the JSDoc comments.
   
   

2. Replace 

   if (akioma.samples)
       akioma.samples = {};

   akioma.samples.getOrderForeignKeys = function(self) {

   With

   namespace akioma.samples {

       export function getOrderForeignKeys(self) { 

   Use namespaces to avoid naming conflicts. Note that functions must be exported to be used outside the namespace (namespaces are compiled into closures).
   
   

3. Replace self with eventSource: akioma.swat.SwatObject.
   
   Note that the function parameter name does not have to be eventSource. For example: eventGrid eventForm, eventRibbon etc. Although self might be confusing with the JavaScript dynObject.
   
   Note that the function parameter type does not have to be the generic base SwatObject as in this case. Use the correct Object Type class to avoid casting.
   
   
4. Replace getObject("CustomerDetailsForm") with getForm("CustomerDetailsForm"), getObject("CustomerGrid") with getGrid("CustomerGrid") and container with window.
   
   The CLAPI supports generic traversing functions like getObject(), getLink() etc. which return the generic base SwatObject class object.
   
   The CLAPI also supports type specific function like getForm(), getGrid(), getRibbon() etc. to avoid casting.
   
   Alternatively you can use TypeScript casting. For example: (eventSource.getObject("MyForm") as akioma.swat.Form).
   
   
5. Replace getValue with getDataValue.
   
   The Form and Grid classes have both a getScreenValue() and getDataValue() functions for getting the field screen value or record value respectively.
   
   
6. Remember to save (Ctrl-S) your work (see picture below).

Documentation

In addition to the intellisense of the class methods, properties and their explanations

you can find the documentation for the complete list of CLAPI TypeScript classes, their methods and properties in the link below 

https://clapi-documentation.akiomacloud.de/

Calling JavaScript functions from TypeScript

There are cases where you might need to call JavaScript functions and objects you have created or framework functions and objects that have not yet been migrated to TypeScript from CLAPI functions.

The problem is that JavaScript functions and objects have no type declaration so they cannot be called from TypeScript.

For cases like these where the type is unknown TypeScript provides the type any to opt-out of type checking and bypass compile-time checking.

To call global functions and objects, the CLAPI added .akioma, .app .dhtmlx, .$ etc. properties with type any to the global Window type declaration.

For example, the JavaScript code: akioma.sports.myFunction() is equivalent to the CLAPI TypeScript code: window.akioma.sports.myFunction() (Note the global window object in the beginning).

To call dynObject and controller functions and properties, the CLAPI added .dynObject and .controller properties also with type any to the base SwatObject.

For example: The JavaScript code: self.myProperty is equivalent to the CLAPI TypeScript code: eventSource.dynObject.myProperty.

Compiling CLAPI Functions

Open the swat-webui/akioma/sass/ directory in the command line interface. Type npm run sports and press Enter (see picture below).

Note that for the changes to take effect you will need to do a hard refresh on the web page (Ctrl-F5).

If you still cannot see the changes after doing a hard refresh, try opening a new incognito window.

Note that other environments may have their own custom build and watch scripts that watch for file changes and launch the build scripts automatically.

Debugging CLAPI Functions

You can view and debug your TypeScript source code using source maps.

Source maps are a mapping between the TypeScript source code and the compiled JavaScript code which runs in the browser, created when compiling the code.

Source maps allow for viewing and debugging TypeScript even though the browser cannot run TypeScript by mapping the JavaScript being run and debugged to the TypeScript source code.

Note that you can only debug not update the TypeScript code in the browser.

Open DevTools (F12) in your Sports Application environment. Open the getOrderForiegnKeys.ts file (Ctrl-P) in the Sources tab (see picture below).

You can turn off source maps in DevTools to view the underline JavaScript code which would also allow you to edit the code.

Open the Settings (F1) in DevTools. Uncheck Enable JavaScript source maps under Sources, in the Preference tab.