Page History

The new and modern Akioma Swat Client Logic API (CLA).

The CLA includes the following features among others -

• Object-Oriented framework
• Compile-time checking
• Intellisense and documentation
• Simplified design

TypeScript

The Client Logic API (CLA) is written in TypeScript is a superset which allows for compile-time checking and intellisense among others.

TypeScript is an extension of JavaScript which adds optional typing and compiles to plain JavaScriptso . JavaScript code is also valid TypeScript code (although it depends on the compiler settings).

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

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

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

Lastly, TypeScript can 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 an a quick introduction to TypeScript see the link below -

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

Installing TypeScript

TypeScript comes pre-installed and setup with the AKIOMA framework. To verify that TypeScript is installed -

From the command line, go to the "swat-webui/akioma/sass" directory and type "npm list typescript".

If an empty list is shown, type "npm install" to install the missing TypeScript package.

TypeScript Configuration

The tsconfig.json is the TypeScript configuration file placed at the project root directory.

The TypeScript SDK tsconfig.json is in the "swat-webui/akioma/ts" directory.

The TypeScript client logic tsconfig.json for the Sports demo application is in the "sports-webui/ClientLogic" directory.

...

Visual Studio Code

In the following examples 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.

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

To install VS Code follow the link below -

https://wwwcode.typescriptlangvisualstudio.org/docs/handbook/compiler-options.html

Compiling TypeScript

TypeScript compilation is part of the regular AKIOMA build scripts. For example -

When running the AKIOMA build script with "npm run akioma" the TypeScript SDK is compiled and added to the application.

When running the Sports demo build script with "npm run sports" the TypeScript client logic is compiled and added to the application.

Visual Studio Code

Visual Studio Code is a popular, free code editor from Microsoft with TypeScript support.

To install VS Code com/docs/?dv=win

To install a portable version follow the link below -

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

For introductory videos on VS Code see the link below -

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

Calling TypeScript Functions

TypeScript functions calls in event handlers, in the visual designer or SCL maintenance (starting with the "$" sign) look just like JavaScript function calls

the only difference is that they must pass the "eventSource" object instead of the "self" object.

Writing TypeScript Functions

Place the client logic TypeScript files in the "ClientLogic" directory just like the JavaScript files.

Remember that the TypeScript file extension is ".ts" instead of the JavaScript ".js".

For a TypeScript function example, look at the "onCustomerSalesrepValueChanged.ts" in the "sports-webui/ClientLogic" directory.

Migrating to the Client Logic API

In the following example we will migrate a function to the CLA. The function gets the foreign keys 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).

Image Added

Calling Client Logic API 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 CLA object, for the event.

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

All the Object Types in Swat, in the SCL Maintenance have equivalent CLA TypeScript 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).

Image Added

Writing Client Logic API Functions

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

Image Added

1. Replace
   
   Use namespaces to avoid naming conflicts. Note that functions must be exported to be used outside the namespace.
   
   
2. Replace "self" with "eventSource: akioma.swat.SwatObject".
   
   Note that the function parameter 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.
   
   
3. Replace getObject("CustomerDetailsForm") with getForm("CustomerDetailsForm") and getObject("CustomerGrid") with getGrid("CustomerGrid").
   
   The CLA supports generic traversing functions like getObject(), getLink() etc. which return the generic base SwatObject class object.
   
   The CLA also supports type specific traversing function like getForm(), getGrid(), getRibbon() etc. to avoid casting.
   
   Alternatively you can use TypeScript casting. For example: (eventSource.getObject("MyObject") as akioma.swat.Form).
   
   
4. 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.
   
   Save (Ctrl-S) and rename (F2) the file as Order/getOrderForeignKeys.ts using the .ts TypeScript file extension (see picture below).

Image Added

Calling JavaScript functions from TypeScript

There are cases where you might need to call JavaScript functions and objects you have created or global functions and objects that have not yet been migrated to TypeScript in the CLA.

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 has the type any to opt-out of type checking and pass through compile-time checks.

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

For example, the JavaScript code: akioma.sports.myFunction() is equivalent to the TypeScript code in the CLA: window.akioma.sports.myFunction().

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

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

Compiling Client Logic API Functions

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

Image Added

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

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 Client Logic API 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).

Image Added

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.